Use LittleDemo from AI agents

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

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 for pipeline setup and Refresh demos from CI for keeping demos fresh after deploys.