← screencli  /  docs

Use the CLI

Record, verify, and export browser sessions from any terminal or AI coding agent with npx screencli — no GitHub App required.

The screencli CLI runs the same browser engine as the GitHub App, from a shell. Any AI coding agent that can run commands — Claude Code, Cursor, Cline, Windsurf — can use it to verify its own work before opening a PR, and you can use it directly for one-off recordings and demos. No install and no account are needed for the first run.

Record a URL

npx screencli record https://your-app.com -p "Walk through the main features"

The agent opens the URL, follows your prompt, and records everything — no account needed for the first run. The -p prompt is the assertion screencli verifies, so name a concrete, observable outcome — see Writing effective prompts. When it finishes you get a composed video and a shareable link at screencli.sh/v/<id>. Run npx screencli login to tie recordings to your account and see them on your dashboard; see CLI login & API access for the token, CI setup, and calling the API directly.

For a permanent install:

npm install -g screencli

Verify a change before you open a PR

verify is the assertion-first command for an AI agent's inner loop: point it at a running preview URL, describe the behavior that must hold, and screencli drives the app in a real browser and returns a pass / fail / inconclusive verdict plus a recording — the same result the GitHub App posts on a PR, but from your terminal before the PR exists.

npx screencli verify https://pr-274-checkout.preview.app \
  -p "Add an item to the cart, go to checkout, complete the purchase, confirm the order ID renders"

It runs the same engine as record and takes the same <url> -p "<prompt>" shape; the difference is intent — verify is for catching a broken flow locally, so a coding agent (Claude Code, Cursor, Cline, Windsurf) can fix a failure before a human ever sees the change. Like record, the first run needs no account or API key and still gives you a shareable link at screencli.sh/v/<id>.

The -p prompt is the assertion, so name a concrete, observable outcome — a vague prompt comes back inconclusive. See Writing effective prompts for how to phrase it, and Verdicts for what each result means.

Record an app that needs login

Use --login to sign in manually first — the agent then takes over your authenticated session. Add --auth <name> to save that session and reuse it later:

npx screencli record https://app.example.com -p "Show the dashboard" --login --auth myapp

Next time, pass just --auth myapp to reuse the saved session without logging in again.

Keep recordings local

By default every recording auto-uploads and gives you a shareable link. Pass --local to skip the upload and keep the recording on disk only.

Export for a specific channel

Turn a recording into a channel-ready clip with export --preset:

npx screencli export ./recordings/your-recording --preset github-gif

github-gif produces an optimized 800×450 GIF (max 12 seconds, under 8 MB) ready to embed in Markdown for a README or PR. Other presets: youtube, twitter, instagram, tiktok, and linkedin.

Automatic video effects

Every recording is composed with idle-time trimming (pauses between actions removed), auto-zoom that follows the active area, click highlights, and cursor trails. You can also choose from six gradient backgrounds — aurora, sunset, ocean, lavender, mint, and ember — with adjustable padding, corner radius, and drop shadow.

Use it from a coding agent

Any agent that can run shell commands — Claude Code, Cursor, Cline, Windsurf — can call the CLI as-is to verify its own work before it opens a PR. For Claude Code specifically, install the skill so the agent runs verify on its own:

npx skills add usefulagents/screencli --skill screencli

See Verify with your coding agent for the full inner-loop workflow, per-agent setup, and a worked pass/fail example.

Notes