CLI reference

Record Skills + CLI.

A command-line interface designed for agents: browser-based login, deterministic exit codes, structured JSON, targeted capture, proof editing, and durable publishing.

Install and connect

Global install and browser login

npm install --global https://recordthis.dev/downloads/record-cli.tgz && record-cli login

login opens a five-minute authorization request in your browser. Your account password stays in the browser; after explicit approval, the originating CLI stores a named, scoped, revocable agent token for the current OS user and syncs the current Record skill.

Verify

System status

record-cli doctor --json

Choose a capture target

Discover and target one surface

record-cli targets --json
record-cli targets --type app --json
record-cli start --app "Safari" --title "Checkout proof" --agent codex --json

targets returns typed displays, visible apps, and windows. Pass an app name, window id, or display index to exactly one of --app, --window, or --display. Use switch during a recording to move between surfaces; stop joins those segments into one normalized video.

Edit the proof

Trim, reorder, and optionally publish

record-cli edit ./full-run.mov --keep 18-25,0-6,9-14 --output ./proof.mp4 --json
record-cli edit ./full-run.mov --cut 6-18 --publish --json

--keep preserves ranges in the written order, while --cut removes ranges chronologically. Timestamps accept seconds, M:SS, or H:MM:SS. The source is preserved so the agent can verify that a concise edit still represents the result honestly.

Keep it current

Safe CLI and skill updates

record-cli upgrade --check --json
record-cli upgrade --json
record-cli skill check --json
record-cli skill sync --json

The read-only checks compare the installed CLI and agent skill with Record's HTTPS release metadata. Upgrade refreshes both. Every download stays on the same Record origin and is verified by exact size and SHA-256 checksum before installation. Connected CLIs make a lightweight ETag-based check on every operational command. Checks time out after one second, never block recording on failure, and print a notice to stderr only when something is stale.

Capture dependencies

Target switching and proof editing require FFmpeg and ffprobe. macOS supports displays and visible app windows. Linux X11 app/window discovery additionally requires wmctrl. wlroots Wayland supports output/display targeting only; GNOME and KDE portal-only capture is not supported yet.

Common workflows

# Discover exact targets
record-cli targets --json

# Start on one app, then switch surfaces
record-cli start --app "Safari" --output ./full-run.mov --title "Checkout proof" --agent codex --json
record-cli switch --window 14325 --json
record-cli switch --display 2 --json
record-cli stop --json

# Keep the clearest moments, result-first, then publish
record-cli edit ./full-run.mov --keep 18-25,0-6,9-14 --publish --json

# Read new comments
record-cli inbox --type comment.* --json

Automation guarantees

--json prints one machine-readable result object; browser and update instructions go to stderr.
login --no-open prints the verification URL for headless or remote environments.
Errors include a stable code, message, and non-zero exit status.
Accepted target switches become timeline events and segment assembly failures preserve the source segments.
Proof edits create a new file and never overwrite the original recording.
Run tokens are least-privilege and expire when a live run closes.
Uploads stream instead of loading the entire video into memory.
doctor reports capture, media, CLI, and skill readiness without installing updates.

For the complete command list, run record-cli --help.