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

# CLI reference

> Every reframe command — render, inspect, validate, and edit a scene from the terminal.

Run any command with `npx reframe-video <command>` (no clone needed) or `pnpm reframe <command>` in a checkout. Scene paths resolve against the directory you invoke from; outputs default to `out/`.

## Render & output

| command                                                                        | what it does                                                                                                                                                                     |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `render <scene.ts\|.json\|.html> [--overlay f]... [-o out]`                    | deterministic mp4 (mode inferred from extension; composes any `--overlay` first)                                                                                                 |
| `batch <scene.ts> <data.json\|csv> [-o dir] [--overlay f]...`                  | one mp4 per data row (row keys are overlay addresses), in parallel, with a per-row report                                                                                        |
| `frame <scene.ts\|.json> [--t <sec>] [--overlay f]... [-o out.png]`            | render one frame at time `t` to a PNG (chromium only, no mux) — for a render-and-look loop; `--overlay` previews edits                                                           |
| `player <scene.ts\|.json> [--overlay f]... [--edit [--t <sec>]] [-o out.html]` | bundle a scene into one self-contained HTML player; `--overlay` previews edits; `--edit` builds an embedded-editor variant (`window.__reframe` + postMessage, live `setOverlay`) |
| `logo <logo.svg\|brand-slug> [--motion <preset>] [--energy n] [--seed n]`      | animate a logo (or a simple-icons brand) into a sting                                                                                                                            |
| `assemble <media...> [-o name] [--title "…"] [--bgm <synth>]`                  | probe images/videos (ffprobe) and scaffold an editable montage scene `.ts`                                                                                                       |
| `narrate <scene.ts\|.json> [--voice <name>] [--max-speed n] [--dry-run]`       | scene-fitted Kokoro voiceover — synth each `audio.narration` line and auto-fit its rate to the slot (needs python + `kokoro`; `--dry-run` estimates without synthesis)           |

## Inspect & validate

| command                                            | what it does                                                                                                                                                        |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `compile <scene.ts\|.json> [-o out.json] [--json]` | bundle + validate a scene to SceneIR JSON, no render (fast; no ffmpeg/chromium). `--json` returns `{ ok, kind, issues }`                                            |
| `manifest <scene.ts\|.json> [--json]`              | dump the addressable surface — every node, state, timeline label, and beat with the overlay address that reaches it                                                 |
| `geometry <scene.ts\|.json> [--t <sec>] [--json]`  | where each node + motionPath waypoint is on screen at time `t` (the spatial analog of `manifest`; pure, no chromium) — for an editor's selection outlines + handles |
| `lint <scene.ts\|.json> [--json] [--strict]`       | the studio-readiness gate — flag un-addressable motion + verify the scene is a pure function of time. `--strict` exits non-zero on findings                         |
| `labels <scene.ts\|.json>`                         | print the compiled event clock (every timeline label → exact seconds) — the timing source for `audio.cues`                                                          |

## Edit & verify

| command                                                               | what it does                                                                                                                                                                                        |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verify-overlay <base> <overlay>... [--json]`                         | compose an overlay onto a base and report applied-vs-orphaned, no render. Non-zero exit on orphans — the regen-survival check                                                                       |
| `compose <scene.ts\|.json> --overlay <doc>... [-o out.json] [--json]` | compose overlay(s) onto a scene → composed SceneIR on stdout (report on stderr), no render. The IR half of `composeScene`; feed the result to `player`/`frame` for live overlay preview. Non-gating |
| `preview`                                                             | scrub / play / edit UI; edits export as overlay JSON                                                                                                                                                |
| `demo`                                                                | render the edit-survival demo (base, base + overlay, AI-regenerated base + the same overlay)                                                                                                        |

## Author & measure

| command                                                                    | what it does                                                                                                 |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `new <name>`                                                               | scaffold a documented starter scene `.ts`                                                                    |
| `diff <ref-image> [scene.ts] [--t <sec>] [--mode side\|blend\|diff\|grid]` | compare a render against a reference image                                                                   |
| `motion <mp4\|framesDir>`                                                  | calibrated motion profile of a clip (speeds, easing, discontinuities)                                        |
| `trace <ref.mp4> [--apply scene.ts]`                                       | extract a video's motion structure; `--apply` re-tells it on your own nodes                                  |
| `guide [--directing\|--regen\|--html]`                                     | print a guide: eDSL syntax (default), the directing workflow, the regeneration contract, or HTML/GSAP scenes |
| `skill [--path]`                                                           | print the authoring skill for an agent; `--path` prints the plugin dir to load                               |

<Tip>
  Before patching a scene, run `manifest` to see the real addresses; after a regen, run `verify-overlay` against the new base to prove every edit still applies; gate CI with `lint --strict`.
</Tip>

The same load / validate / determinism surface is importable in-process — see the [programmatic API](/api).