> ## Documentation Index
> Fetch the complete documentation index at: https://docs.littledemo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local recording

Record any URL — including localhost — into a demo video, then optionally host it in one command.

`littledemo record` runs the LittleDemo recording engine on your machine. It reaches
what cloud generation cannot: localhost dev servers and apps behind your own login.
No credits are consumed until you upload.

```bash
littledemo record http://localhost:3000 --out demo.mp4 --gif
```

Chrome/Chromium and ffmpeg are auto-detected (override with `CHROME_PATH` /
`FFMPEG_PATH`). Outputs the video plus a `demo.png` thumbnail and, with `--gif`,
an animated `demo.gif`.

## Recording authed apps

Three ways to record behind a login:

```bash
# 1. Persistent profile: log in once in the window that opens, re-run forever
littledemo record https://app.example.com --profile

# 2. Playwright storage state (great in CI after a Playwright auth setup step)
littledemo record https://app.example.com --storage-state auth.json

# 3. Attach to YOUR running Chrome (sessions, extensions, everything)
#    chrome --remote-debugging-port=9222 --user-data-dir=$HOME/chrome-debug
littledemo record https://app.example.com --attach 9222
```

Attach mode never closes or kills your browser, records at true speed, and
removes every injected element and emulation override when it finishes.

## Record and host in one shot

```bash
littledemo record http://localhost:3000 \
  --upload --project proj_abc123 \
  --prompt "New billing settings page" \
  --json --yes
```

`--upload` chains straight into `demos upload`, attaching the generated thumbnail
and GIF automatically, and prints the `shareUrl`, `embedUrl`, `gifUrl`, and
`thumbUrl`. Uploading publishes a public-by-link URL, so it asks for confirmation —
pass `--yes` in scripts and CI.

## Scripted steps

Free recordings scroll-tour the page. For a guided flow, pass `--steps steps.json`:

```json
{
  "steps": [
    { "action": "click", "text": "Settings" },
    { "action": "type", "selector": "#team-name", "text": "Acme Corp" },
    { "action": "click", "text": "Save changes" },
    { "action": "pause", "ms": 1200 }
  ]
}
```

Actions: `pause`, `click`, `type`, `key`, `scroll`, `wait`, `navigate`, `hover`,
`select`, `moveTo`, `drag`, `screenshot`, `callout`. Target elements by visible
`text` (preferred — resilient to markup changes) or CSS `selector`. Malformed
steps fail with a field-level error before the browser launches.

## Options

| Flag | Meaning |
|---|---|
| `--steps <file>` | Scripted steps JSON (validated up front) |
| `--out <path>` | Output video path (default `./demo.mp4`) |
| `--duration <sec>` | Target length for the default scroll tour |
| `--gif` | Also encode an animated GIF (640px, 12fps — renders inline on GitHub) |
| `--deterministic` | Stepped virtual clock: reproducible pacing, faster wall-clock |
| `--viewport WxH` | e.g. `1440x900` |
| `--mockup <style>` | `macos-dark`, `macos-light`, `minimal`, `none` |
| `--no-zoom` | Disable click-follow zoom |
| `--profile [dir]` | Launch a visible Chrome with a persistent profile (default `~/.littledemo/chrome-profile`) — log into your app once, record it forever |
| `--attach <port>` | Record an existing Chrome you launched with `--remote-debugging-port=<port> --user-data-dir=<dir>` — never killed, always true-speed capture, all injected UI removed afterwards |
| `--headful` | Show the launched browser window |
| `--cookies <f>` | Inject cookies (JSON array) before navigation |
| `--storage-state <f>` | Inject cookies from a Playwright `storageState` file |
| `--upload` | Upload after recording (requires `--project`, `--prompt`) |
| `--yes` | Skip the publish confirmation (CI) |
| `--json` | Machine-readable result on stdout |

The engine itself ships as [`@littledemo/recorder`](https://www.npmjs.com/package/@littledemo/recorder)
(`npx --package=@littledemo/recorder littledemo-record`), which the CLI uses
automatically when no local install is found.