Control Screen Studio from the command line. No plugins, no extensions — direct WebSocket connection to the Electron app's MobX state via Chrome DevTools Protocol.
Record, edit, and export Screen Studio projects entirely from the terminal. Built for AI agents (Claude Code, Codex, etc.) to automate screen recording workflows end-to-end.
Screen Studio is an Electron app. Launching it with --remote-debugging-port=9222 exposes Chrome DevTools Protocol, giving direct access to its React/MobX internals. This CLI connects via WebSocket and can:
- Read full project state (slices, zooms, config, recording metadata)
- Mutate the timeline (split, trim, remove, speed up, merge)
- Control zoom ranges (add, remove, split, update position/level)
- Manage masks for blurring sensitive content
- Start/stop/pause recordings programmatically
- Seek, preview, and render frames for verification
- Export the final video
All mutations push to Screen Studio's undo history, so every change is reversible with screenstudio project undo.
- Node.js >= 21 (for built-in WebSocket)
- Screen Studio (macOS)
- ffmpeg (for
renderandanalyzecommands) —brew install ffmpeg
npm install -g screenstudio-cliOr from source:
git clone https://github.com/ShawnPana/screenstudio-cli.git
cd screenstudio-cli
npm install
npm run build
npm link# Launch Screen Studio with CDP enabled
screenstudio launch
# Open a project
open ~/Screen\ Studio\ Projects/MyRecording.screenstudio
# Check connection
screenstudio status
# → Connected to Screen Studio 3.6.0 | Project: MyRecording | Duration: 29.3s | 5 slices
# Read project state
screenstudio state
screenstudio state --json # full structured dump
# Edit the timeline
screenstudio slice list
screenstudio slice split 15000 # split at 15s
screenstudio slice speed 0 2 # 2x speed on slice 0
screenstudio slice remove --from 6000 --to 8000 # cut a section
# Add a zoom
screenstudio zoom add 0 --end 30000 --level 2 --x 0.5 --y 0.5 --id my_zoom
# Preview
screenstudio preview --at 5000 -o /tmp/check.png --open
# Export
screenstudio exportscreenstudio record displays # list displays with visible apps
screenstudio record windows # list windows with titles
screenstudio record start --app Terminal # record display containing app
screenstudio record start --mode window --title "YouTube" # record specific window by title
screenstudio record pause # pause recording
screenstudio record resume # resume
screenstudio record stop # stop and save
screenstudio record cancel # stop and discardrecord displays shows what apps are on each display, so you always record the right one. --app auto-detects which display contains the target app. Window mode uses AppleScript to match by window title.
screenstudio slice list # show all slices
screenstudio slice split 15000 # split at 15s (source ms)
screenstudio slice remove 2 # remove slice by index
screenstudio slice remove --from 6000 --to 8000 # remove a time range
screenstudio slice speed 0 2.0 # set slice 0 to 2x speed
screenstudio slice merge 1 # merge slice 1 with next
screenstudio slice trim 0 --start 2000 --end 10000 # adjust boundaries directlyscreenstudio zoom list # show all zoom ranges
screenstudio zoom add 0 --level 2 --end 50000 --id my_zoom # add with custom ID
screenstudio zoom add 0 --level 2 --x 0.3 --y 0.8 # with target point
screenstudio zoom remove <id> # remove by ID
screenstudio zoom update <id> --level 3 --x 0.5 --y 0.5 # update properties
screenstudio zoom split <id> 25000 # split at timestamp
screenstudio zoom set '[{...}, {...}]' # replace all at onceZoom operations use scene.update({ zoomRanges }) internally, which is reliable — unlike Screen Studio's built-in addZoomRangeAt() which can overwrite adjacent ranges.
screenstudio mask list
screenstudio mask add 0 10000 --x 100 --y 200 --width 400 --height 50 --blur 20
screenstudio mask update <id> --x 150 --width 500
screenstudio mask remove <id>
screenstudio mask clearscreenstudio config --list # all 68 config keys
screenstudio config backgroundColor # read a value
screenstudio config backgroundColor "#FF0000" # write (updates UI immediately)screenstudio preview # screenshot the preview canvas
screenstudio preview --at 5000 --open # seek to 5s, capture, open in Preview.app
screenstudio seek 10000 # move playhead
screenstudio render --fps 10 --from 3000 --to 6000 # render zoomed frames via ffmpeg
screenstudio analyze --interval 2 # extract frames + event timelinescreenstudio project info # name, duration, dirty state
screenstudio project save
screenstudio project undo # undo last CLI mutation
screenstudio project redoscreenstudio export # opens export dialog (Cmd+Shift+E)
screenstudio export --clipboard # quick export to clipboardscreenstudio exec '$project.name'
screenstudio exec --file script.js
echo '$projects.size' | screenstudio exec -All commands support:
--json— structured JSON output (put before the command:screenstudio --json state)--port <n>— CDP port (default 9222)
$project vs $projects: The CLI uses window.$project (the active/focused project), not Array.from($projects.values())[0]. This ensures the correct project is targeted when multiple are open.
Undo support: Every mutation calls p.history.update() before making changes, so screenstudio project undo reliably reverses any CLI edit.
Speed: Screen Studio uses timeScale internally where timeScale = 1/speed. So 4x speed = timeScale: 0.25. The slice speed command handles this conversion — just pass the speed you want.
Zoom operations: All zoom add/remove/split/update operations serialize the full zoom array and call scene.update({ zoomRanges }). This avoids addZoomRangeAt() which can overwrite adjacent ranges and cause ID collisions.
Video file naming: Recording video files can be channel-1-display-0.mp4 or channel-2-display-0.mp4. The CLI dynamically finds the correct file by globbing channel-*-display-*.mp4.
The skills/screenstudio-cli/ directory contains a SKILL.md that AI agents (Claude Code, Codex, etc.) can load to learn how to use the CLI. It includes:
- Full command reference
- The "Watch → Edit → Watch" methodology
- Coordinate system documentation
- Crash prevention rules
The skills/screenstudio-cli/references/demo.md guide covers end-to-end demo recording and editing with a terminal + browser side-by-side layout, including the 2x zoom grid system for framing content.
MIT