# LittleDemo

> AI-powered product demo video generator. Turn any URL into a polished demo video with a natural language prompt.

## Overview
LittleDemo dynamically generates product demo videos from a URL and a prompt. It uses an AI agent to analyze your product's UI, plan an interaction sequence, and record a polished video with cursor animation and keystroke overlays. Videos are hosted and embeddable via iframe, oEmbed, or JS SDK. You can also upload your own MP4/WebM recordings and get the same hosted share/embed/media URLs.

## Quick Start (CLI)
```bash
npm install -g @littledemo/cli
littledemo login           # opens browser for device auth (interactive)
littledemo init            # interactive wizard creates your first demo
littledemo setup --yes     # installs public agent skill + AGENTS.md guidance
```

The `login` command uses a browser-based device authorization flow (RFC 8628 inspired) — it opens https://littledemo.com/device with a one-time code. After authorization, the CLI stores a write-scoped API key at `~/.littledemo/config.json` (mode 0600).

Agents and CI must NOT run `login` or `init` (both are interactive). Set `LITTLEDEMO_API_KEY=ld_live_xxx` instead (keys: https://littledemo.com/settings). Override the API base with `LITTLEDEMO_API_URL` or `--api-url`.

PR demo automation is opt-in. `littledemo setup --pr-demos --yes` creates `.github/workflows/littledemo-pr-demo.yml`, which records same-repo PRs, uploads a hosted demo, and posts one sticky GitHub PR comment when `LITTLEDEMO_API_KEY` and a project id are configured.

## Quick Start (cURL)
```bash
# Generate an API key in https://littledemo.com/settings, then:
curl -X POST https://littledemo.com/api/v1/projects \
  -H "Authorization: Bearer ld_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"My App","url":"https://myapp.com"}'

curl -X POST https://littledemo.com/api/v1/demos \
  -H "Authorization: Bearer ld_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"proj_xxx","prompt":"Walk through the signup flow"}'
```

## API
- POST /api/v1/projects - Create a project
- POST /api/v1/demos - Generate a demo (accepts project_id, prompt, format, duration_target)
- POST /api/v1/demos/local-upload - Upload a local recording as a ready demo.
- POST /api/v1/demos/:id/local-assets?type=thumbnail|gif - Attach a PNG poster (≤5MB) or animated GIF (≤25MB) to an uploaded demo (raw image/png or image/gif body). Uploaded demos have no /thumb or /gif URLs until assets are attached.
  Auth: Bearer ld_live server key or signed-in session (publishable keys rejected).
  Query params: project_id (required), prompt (required), title?, duration_ms?, format? (mp4|webm).
  Body: raw video bytes, Content-Type video/mp4 or video/webm, max 100 MB, Content-Length required.
  WebM requires Starter plan or higher (Free = MP4 only). Counts toward demo quota.
  201 response: {"id", "status": "ready", "jobId", "shareUrl", "embedUrl", "videoUrl"}
- GET /api/v1/demos/:id - Check status and get video URL
- GET /api/v1/demos?project_id=... - List demos
- POST /api/v1/projects/:id/refresh - Trigger regeneration of all demos
- POST /api/v1/device/code - Start CLI device authorization
- POST /api/v1/device/token - Poll for CLI token

## Embed & Media
- iframe: <iframe src="https://littledemo.com/embed/{id}">
- Share page: https://littledemo.com/d/{id}
- oEmbed: https://littledemo.com/oembed?url=https://littledemo.com/d/{id}
- JS SDK: <div data-littledemo-id="{id}"><script src="https://littledemo.com/sdk.js">
- GIF (public, no auth): https://littledemo.com/gif/{id}.gif
- Thumbnail (public, no auth): https://littledemo.com/thumb/{id}.png

## CLI Commands
- littledemo login [--api-key KEY] [--no-browser] [--no-wizard]  (interactive; agents use LITTLEDEMO_API_KEY instead)
- littledemo logout
- littledemo whoami
- littledemo init  (interactive wizard)
- littledemo setup [--yes] [--skill|--no-skill] [--agents|--no-agents] [--pr-demos|--no-pr-demos] [--project ID] [--force] [--dry-run] [--json]  (installs public LittleDemo skill, managed AGENTS.md guidance, and optionally PR demo automation)
- littledemo projects list | create --name NAME --url URL
- littledemo demos list [--project ID] [--json]
- littledemo demos create --project ID --prompt "..." [--duration 5s|10s|30s] [--template ID] [--section HINT] [--no-wait] [--open] [--json] [--timeout SEC]
- littledemo record URL [--steps steps.json] [--out demo.mp4] [--gif] [--deterministic] [--upload --project ID --prompt "..." --yes] [--json]  (local recording: works on localhost/authed apps, no credits until upload; --upload attaches thumbnail+GIF automatically)
- littledemo demos upload FILE --project ID --prompt "..." [--title T] [--duration-ms N] [--format mp4|webm] [--gif [f]] [--thumbnail [f]] [--open] [--json]  (MP4/WebM ≤100MB; WebM needs Starter+; .mov screen recordings are remuxed to mp4 automatically, needs ffmpeg on PATH; --gif/--thumbnail attach a PNG poster + animated GIF, auto-detecting sibling demo.png/demo.gif)
- littledemo demos wait ID [--json] [--timeout SEC] [--open]
- littledemo demos batch FILE --project ID [--concurrency 3] [--timeout SEC]  (one prompt or JSON object per line; prints JSON results, exit 1 on any failure)
- littledemo demos get ID | open ID

With --json, stdout carries only machine-readable JSON (parse with jq); human/progress text goes to stderr or is suppressed. Successful create/wait/upload JSON includes shareUrl and embedUrl.

## CLI Exit Codes
- 0 success
- 1 failure (generation failed, upload rejected, API error)
- 2 usage error (bad flags/arguments)
- 3 auth error (missing/invalid API key)
- 4 quota exceeded or rate-limited (HTTP 429)
- 5 timed out waiting for a demo

## Key Features
- AI-scripted: natural language prompt to browser interaction recording
- Local uploads: publish your own MP4/WebM recordings as hosted demos
- Always fresh: auto-regenerates on schedule or CI/CD webhook
- 10 embed formats: iframe, oEmbed, SDK, MP4, GIF, thumbnail
- Branded: custom cursor, colors, watermark
- CLI with browser-based login (no manual key copy-paste) and --json output for agents/CI

## Links
- Documentation: https://docs.littledemo.com
- Getting Started: https://docs.littledemo.com/quickstart
- API Reference: https://docs.littledemo.com/api/overview
- Pricing: /pricing
- npm: https://www.npmjs.com/package/@littledemo/cli