# Screencli

> 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.

- Skill: `usefulagents/screencli` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add usefulagents/screencli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/usefulagents/screencli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: usefulagents (https://skillmd.com/u/usefulagents)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/usefulagents/screencli

---


## 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

Set up screencli (one-time):

```
npx screencli init
```

This prompts you to sign in to screencli.sh (free credits, default) or paste your own Anthropic API key. It also offers to install the screencli skill for your coding agent.

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"
```

The AI agent navigates the page, the recording is composed with effects, uploaded, and you get 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 init` to sign in or configure an API key |
| 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