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

# Use LittleDemo from AI agents

Non-interactive auth, JSON output, exit codes, and copy-paste workflows for coding agents and automation.

The CLI is designed to be driven by coding agents (Claude Code, Cursor, CI bots): every command has a `--json` mode, auth works from an environment variable, and exit codes are machine-friendly. If you ship an `AGENTS.md` in your repo, copy the sections below into it.

## Authentication (non-interactive)

```bash
export LITTLEDEMO_API_KEY=ld_live_xxx
```

- **Agents must never run `littledemo login` or `littledemo init`.** `login` opens a browser and polls a device-authorization code; `init` is an interactive wizard. Both hang without a human.
- Create keys in the [dashboard settings](https://littledemo.com/settings), or run `littledemo login` yourself in an interactive terminal.
- `LITTLEDEMO_API_URL` (or `--api-url <url>`) overrides the API base. Default: `https://littledemo.com`.
- Preflight check: `littledemo whoami` prints plan, monthly demo usage, and credit balance, and fails when the key is missing or invalid.

## Workflows

### 1. Cloud generate (public URL → AI-recorded demo)

```bash
littledemo demos create --project <proj_id> --prompt "Show the signup flow" --json --timeout 300
```

Queues the demo and blocks until it is ready (default wait timeout: 600s), then prints the final demo JSON — including `shareUrl` and `embedUrl` — on stdout.

Optional flags: `--duration 5s|10s|30s`, `--template <id>` (one of `auto`, `cinematic`, `guided-tour`, `plain-scroll`, `section-focus`, `hero-spotlight`, `feature-sweep`, `conversion-flow`, `pricing-focus`, `proof-scroll`), `--section "<hint>"` for `section-focus`.

### 2. Local file → hosted demo

For localhost apps, authenticated flows, or recordings you already have:

```bash
littledemo demos upload ./demo.mp4 --project <proj_id> --prompt "Show the checkout flow" --json
```

- Accepts MP4 and WebM files up to **100 MB**. Format is inferred from the extension; override with `--format mp4|webm`.
- `.mov` screen recordings are remuxed to MP4 automatically when ffmpeg is available.
- **WebM requires the Starter plan or higher** — the Free plan accepts MP4 only.
- Optional: `--title "..."`, `--duration-ms 12000`, `--gif [file]`, `--thumbnail [file]`. Bare `--gif` and `--thumbnail` auto-detect siblings such as `demo.gif` and `demo.png`, and the JSON response includes `gifUrl` and `thumbUrl` when assets attach.
- The upload becomes a ready demo immediately. JSON response on stdout:

```json
{ "id": "demo_x", "status": "ready", "jobId": "job_x", "shareUrl": "...", "embedUrl": "...", "videoUrl": "..." }
```

### 3. Record localhost or authenticated apps

```bash
littledemo record http://localhost:3000 --upload --project "$PROJECT_ID" --prompt "What this shows" --yes --json
```

This records locally, attaches the generated thumbnail and GIF, then uploads the result. Use `--storage-state auth.json`, `--profile [dir]`, or `--attach <port>` for authenticated apps. Always pass `--yes` in non-interactive scripts because `--upload` publishes a public-by-link URL.

### 4. Async (queue now, collect later)

```bash
littledemo demos create --project <proj_id> --prompt "..." --no-wait --json
# → { "id": "demo_x", "status": "pending", "jobId": "job_x", "pollUrl": "/api/v1/demos/demo_x" }

littledemo demos wait <demo_id> --json --timeout 300
# → final demo JSON with shareUrl/embedUrl (or {"id","status":"timeout"})
```

Related: `demos list --project <id> --json`, `demos get <id>`, and `demos batch <file> --project <id> [--concurrency 3] [--timeout <sec>]` — one prompt or JSON object per line; prints a JSON array of results and exits non-zero if any demo failed.

### 5. Install repo guidance and optional PR demos

```bash
littledemo setup --yes
```

This installs the public LittleDemo skill at `.claude/skills/littledemo/SKILL.md` and adds a managed LittleDemo block to `AGENTS.md`. It is safe to run repeatedly; unmanaged files are skipped unless `--force` is passed.

Automatic PR demo videos are opt-in:

```bash
littledemo setup --pr-demos --yes
```

That adds `.github/workflows/littledemo-pr-demo.yml`, which records and uploads same-repo, non-draft PRs and posts one sticky PR comment. Configure `LITTLEDEMO_API_KEY` as a GitHub repo secret, plus `LITTLEDEMO_PROJECT_ID` unless setup wrote a concrete `--project proj_...` into the workflow.

## Output contract: `--json`

With `--json`, **stdout carries only machine-readable JSON**; human/progress text goes to stderr (or is suppressed). Parse stdout with `jq`:

```bash
out=$(littledemo demos upload ./demo.mp4 --project "$PROJECT_ID" --prompt "New checkout flow" --json)
id=$(jq -r .id <<<"$out")
share=$(jq -r .shareUrl <<<"$out")
video=$(jq -r .videoUrl <<<"$out")
```

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | Success |
| 1 | Failure (generation failed, upload rejected, API error) |
| 2 | Usage error (bad flags or arguments) |
| 3 | Auth error (missing/invalid API key) |
| 4 | Quota exceeded or rate-limited (HTTP 429) |
| 5 | Timed out waiting for a demo |

This table is the exit-code contract, implemented as of CLI 0.3.0. Versions 0.2.0 and earlier collapse all failures to exit 1.

## Public media URLs (no auth)

For any ready demo `<id>`:

- Share page: `https://littledemo.com/d/<id>`
- Embed iframe: `https://littledemo.com/embed/<id>`
- GIF: `https://littledemo.com/gif/<id>.gif`
- Thumbnail: `https://littledemo.com/thumb/<id>.png`

Uploaded demos only have GIF and thumbnail shortcut URLs after you attach assets with `--gif` and `--thumbnail`, use `littledemo record --upload`, or call `POST /api/v1/demos/:id/local-assets`.

## Recipe: post a demo on a GitHub PR

GitHub strips iframes from comments, so link the GIF to the share page:

```bash
out=$(littledemo demos upload ./demo.mp4 \
  --project "$LITTLEDEMO_PROJECT_ID" \
  --prompt "Show the changes in this PR" \
  --title "PR demo" \
  --gif \
  --thumbnail \
  --json)
id=$(jq -r .id <<<"$out")
share=$(jq -r .shareUrl <<<"$out")
gif=$(jq -r '.gifUrl // empty' <<<"$out")

gh pr comment "$PR_NUMBER" --body "[![Demo](${gif})](${share})"
```

See also: [CLI in CI](/cli/ci) for pipeline setup and [Refresh demos from CI](/guides/ci-refresh) for keeping demos fresh after deploys.