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.
• WebM requires the Starter plan or higher — the Free plan accepts MP4 only.
• Optional: --title "...", --duration-ms 12000.
• The upload becomes a ready demo immediately. JSON response on stdout:

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

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

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

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" \  --json)id=$(jq -r .id <<<"$out")share=$(jq -r .shareUrl <<<"$out")gif="https://littledemo.com/gif/${id}.gif"thumb="https://littledemo.com/thumb/${id}.png"   # static preview alternativegh 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.