screencli-record

name	screencli-record
description	Record AI-driven browser demos with screencli. One command creates a polished screen recording with gradient backgrounds, auto-zoom, click highlights, and cursor trails — then uploads it to a shareable link. Use when the user wants to record a demo, screencast, walkthrough, or video of a web app.
license	MIT
compatibility	Requires Node.js 18+ and FFmpeg. Works on macOS, Linux, Windows.
metadata	{"author":"danleshem","version":"1.0","website":"https://screencli.sh"}

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 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 — all commands and flags
• Effects Reference — gradients, backgrounds, effects pipeline