Docs — screencli

Install

$ npx screencli login
$ npx screencli record https://your-app.com -p "demo"

No install needed. npx downloads and runs screencli automatically, always up to date. Or install globally with npm i -g screencli.

Record

$ npx screencli record <url> -p "<prompt>" [options]

Flag	Description
-p, --prompt <text>	Instructions for the AI agent (required)
--background <name>	Background style: `aurora` `sunset` `ocean` `lavender` `mint` `ember` (default: aurora)
--padding <n>	Background padding % (default: 8)
--corner-radius <n>	Corner radius in pixels (default: 12)
--no-shadow	Disable drop shadow
--login	Open browser for manual login, then AI takes over
--auth <name>	Save/load auth state (auto-creates on first use)
--no-headless	Show browser window
--viewport <WxH>	Viewport size (default: 1920x1080)
-m, --model <model>	Claude model
--max-steps <n>	Max agent steps (default: 50)
--slow-mo <ms>	Extra delay between actions
-o, --output <dir>	Output directory (default: ./recordings)
-v, --verbose	Debug logging

Export

$ npx screencli export <recording-dir> --preset <name> [options]

Export also supports --background, --padding, --corner-radius, and --no-shadow.

Presets

Preset	Resolution	Aspect	Format
youtube	1920 × 1080	16:9	mp4
twitter	1280 × 720	16:9	mp4
instagram	1080 × 1920	9:16	mp4
tiktok	1080 × 1920	9:16	mp4
linkedin	1080 × 1080	1:1	mp4
github-gif	800 × 450	16:9	gif

Gradient backgrounds

Six background presets applied by default. Change with --background <name> or disable with --no-background.

aurora

sunset

ocean

lavender

mint

ember

Flag	Description
--background <name>	Background style (default: aurora)
--padding <%>	Space around the video (default: 8)
--corner-radius <px>	Rounded corners (default: 12)
--no-shadow	Disable drop shadow

Authentication

Log in manually, then let the AI agent continue with your authenticated session. The login is never recorded.

# First time — login flow + save for reuse
$ npx screencli record https://app.example.com \
    -p "Demo the dashboard" \
    --login --auth myapp

# Subsequent runs — instant, no login needed
$ npx screencli record https://app.example.com \
    -p "Demo the dashboard" \
    --auth myapp

Auth state (cookies, localStorage, sessionStorage) is saved to ~/.screencli/auth/<name>.json.

Effects

Applied automatically during video composition:

Auto-trim — removes idle time between agent actions
Zoom — auto-zooms to the area of activity. Disable with --no-zoom
Click highlights — visual pulse on click positions. Disable with --no-highlight
Cursor trail — smooth cursor movement overlay. Disable with --no-cursor

Examples

Basic recording with gradient

$ npx screencli record https://example.com \
    -p "Show the landing page and key features" \
    --background aurora --no-headless

Export for Twitter

$ npx screencli export ./recordings/a3f2c8e1 \
    --preset twitter --background sunset

Authenticated recording, full options

$ npx screencli record https://app.example.com \
    -p "Walk through the onboarding flow" \
    --auth myapp \
    --background ocean \
    --padding 10 \
    --corner-radius 16 \
    --no-headless

Quick reference.