screencli-record

## What It Does screencli records an AI-driven browser session and produces a polished MP4 with gradient backgrounds, auto-zoom, click highlights, and cursor trails. The AI agent navigates the target URL following your prompt instructions, then the recording is composed with effects and auto-uploaded to screencli.sh with a shareable link. No video editing needed. ## When to Use This Skill Use this skill when the user asks to: - **Record a demo or walkthrough** of a web app, feature, or workflow - **Create a screencast or video** showing how something works in a browser - **Generate a shareable link** to a screen recording - **Make a GIF or video** for a README, PR, docs, or social media - **Record a before/after** to show a UI change or bug fix - **Demo a deploy or staging environment** visually Do **not** use this skill for: - Screenshots (use a screenshot tool instead) - Non-browser tasks (terminal recordings, desktop apps) - Editing existing videos ## Quick Start Record a demo and get a shareable link: ``` npx screencli record https://example.com -p "Click the Sign Up button, fill in the form with test data, and submit" ``` On first run, the CLI opens a browser for GitHub login automatically. After that, it records the session, applies effects, uploads, and prints a shareable URL. ## Recording ### Command ``` npx screencli record [url] -p "<prompt>" [options] ``` The URL and prompt are required. If omitted, the CLI prompts interactively. ### Key Options | Flag | Default | Description | |------|---------|-------------| | `-p, --prompt <text>` | *(required)* | Instructions for the AI agent | | `--background <name>` | auto | Override gradient: `midnight`, `ember`, `forest`, `nebula`, `slate`, `copper` | | `--viewport <WxH>` | `1920x1080` | Browser viewport dimensions | | `--login` | off | Open browser for manual login before AI takes over | | `--auth <name>` | — | Save/load auth state by name | | `--local` | off | Skip cloud upload | | `--unlisted` | off | Upload as unlisted (not on public profile) | | `--max-steps <n>` | `50` | Maximum agent iterations | | `--padding <percent>` | `8` | Background padding (0-50%) | | `--corner-radius <px>` | `12` | Video corner radius | | `--no-shadow` | off | Disable drop shadow | | `-m, --model <model>` | `claude-sonnet-4-20250514` | Claude model to use | | `--slow-mo <ms>` | `0` | Extra delay between actions | | `-o, --output <dir>` | `./recordings` | Output directory | | `-v, --verbose` | off | Debug logging | ### Examples **Simple — record a public page:** ``` npx screencli record https://myapp.com -p "Navigate to the pricing page and compare the Free and Pro plans" ``` **With auth — login to a private app first:** ``` # First run: human logs in, auth state saved npx screencli record https://app.internal.com -p "Show the dashboard metrics" --login --auth myapp # Next runs: reuses saved session npx screencli record https://app.internal.com -p "Export the monthly report" --auth myapp ``` ## Exporting Export a recording with platform-specific presets: ``` npx screencli export <recording-dir> --preset <name> ``` ### Presets | Preset | Resolution | Aspect | Format | Max Duration | |--------|-----------|--------|--------|--------------| | `youtube` | 1920x1080 | 16:9 | mp4 | — | | `twitter` | 1280x720 | 16:9 | mp4 | 140s | | `instagram` | 1080x1920 | 9:16 | mp4 | 90s | | `tiktok` | 1080x1920 | 9:16 | mp4 | — | | `linkedin` | 1080x1080 | 1:1 | mp4 | — | | `github-gif` | 800x450 | 16:9 | gif | 12s | ### Example ``` npx screencli export ./recordings/abc123 --preset twitter ``` Export also accepts `--background`, `--padding`, `--corner-radius`, `--no-shadow`, `--no-zoom`, `--no-highlight`, and `--no-cursor`. ## Auth for Private Apps To record behind a login wall, use `--login` and `--auth` together on the first run: ``` npx screencli record https://app.example.com -p "..." --login --auth myapp ``` The browser opens for you to log in manually. Once done, the AI agent takes over and auth state is saved to `~/.screencli/auth/myapp.json`. On subsequent runs, pass just `--auth`: ``` npx screencli record https://app.example.com -p "..." --auth myapp ``` If a session expires, re-run with `--login --auth <name>` to refresh it. ## Cloud Recordings auto-upload to screencli.sh by default. Skip with `--local`. ### Commands | Command | Description | |---------|-------------| | `npx screencli login` | Sign in to screencli cloud | | `npx screencli logout` | Sign out | | `npx screencli whoami` | Show current user, plan, and credits | | `npx screencli recordings` | List your recordings with links | | `npx screencli upload <dir>` | Upload a local recording to the cloud | | `npx screencli delete <id>` | Delete a cloud recording | | `npx screencli render <id>` | Re-render on the cloud with different background/preset | ### Credits 1 credit = 10 agent steps. Free tier includes 15 credits/month. After a recording uploads, the CLI shows credits used and remaining. ## Effects All recordings get automatic post-processing: - **Gradient background** — automatically selected (override with `--background <name>`) - **Auto-trim** — removes idle time between actions - **Auto-zoom** — zooms into the active area during interactions - **Click highlights** — visual pulse on each click - **Cursor trail** — smooth cursor movement overlay Toggle individual effects off with `--no-zoom`, `--no-highlight`, `--no-cursor`. See [references/effects.md](references/effects.md) for gradient colors and the full effects pipeline. ## Troubleshooting | Problem | Fix | |---------|-----| | Not logged in | Run `npx screencli record` — login is triggered automatically | | FFmpeg missing | `brew install ffmpeg` (macOS) or see ffmpeg.org | | Auth expired | Re-run with `--login --auth <name>` | | Agent stuck or looping | Refine prompt, lower `--max-steps` | | Recording too long | Use `--max-steps` to limit, or be more specific in prompt | | Upload failed | Check `npx screencli whoami` for credits, retry with `npx screencli upload <dir>` | ## References - [CLI Reference](references/cli-reference.md) — all commands and flags - [Effects Reference](references/effects.md) — gradients, backgrounds, effects pipeline