Commands
Nineteen commands, grouped by what you are trying to do. Run playhead guide for the same grouping in your terminal, or add --help to any command.
Make a video#
render#
playhead render <specs...> [-o out]Capture, compose and verify. Exits 0 only if every spec is publishable, which is the whole CI contract. Several specs render as a pool with per-spec subdirectories.
| Flag | Effect |
|---|---|
-o, --out <dir> | Output directory, default out. |
-w, --workers <n> | Concurrent renders when given several specs. Default 2. |
--junit <path> | JUnit XML with one testcase per verification check. |
--json | Verdict JSON on stdout; human logs go to stderr. |
--gif [width] | Also export an embeddable GIF, default width 960. |
--vision | Run the optional local vision review through Ollama. Frames stay on your machine. |
--jira <issueKey> | Report the outcome to an existing Jira issue — on success or on a flow failure. |
--headed | Show the browser while capturing. |
capture · compose · verify#
The three stages, individually, so you can re-enter the pipeline where you changed something.
playhead capture <spec> [-o out] [--from-scene <id>] [--headed]
playhead compose <bundle> [-o out] [--spec f] [--aspects "9:16,1:1"]
[--gif [w]] [--watch] [--expect-sha <hex>]
playhead verify <bundle> <video> [-m manifest] [--json] [--junit p] [--vision]| Flag | Effect |
|---|---|
capture --from-scene <id> | Fast-forward the earlier steps for state only, unfilmed, and film from this scene. For iterating on one scene. |
compose --spec <file> | Compose with a live spec file instead of the bundled snapshot, so caption, narration, theme, audio and pacing edits are a re-compose and never a re-capture. |
compose --watch | Re-compose whenever that spec file changes. The text-editing loop. |
compose --aspects | Also render these aspects from the same footage. |
compose --expect-sha | Assert the rendered MP4 hashes to this sha256 — same bundle plus same spec should mean the same video. |
Author a spec#
| Command | What it does |
|---|---|
record <url> | A browser opens; you drive the flow; every interaction becomes a validated step. -o, --title, --kind, --viewport, --storage-state. |
explore <url> | Print a grounded catalog of addressable elements. --spec inherits a spec’s world and runs its setup steps first; also --viewport, --storage-state, --headed. |
validate <spec> | Preflight every locator against the live app in one pass, with suggestions for the ones that miss. |
author <url> <goal> | Agent-author a grounded spec toward a goal. --tts, --max-steps, --kind. |
demo <url> <goal> | Explore, author, validate and render in one command. --open plays the result when it is publishable. |
init [path] | With no path: wire MCP, skills, Chromium and Kokoro. With a path: scaffold a spec, optionally from a live --url. |
login <url> | Open a headed browser for you to sign in, then save the session. Playhead never sees the credentials. |
Narration#
playhead say "Adding a teammate takes one form." --provider kokoro --voice heartAudition a line out loud with no spec and no render. --rate means words-per-minute for the macOS say provider but playback speed ×100 for Kokoro; -o also saves the audio. Narration & voices →
Share the result#
| Command | What it does |
|---|---|
evidence [dir] | Write a relocatable HTML page — video, steps and verdict — from a render output directory. render already writes one; this rebuilds it. |
jira report <issueKey> | Attach the video or failure clip, verdict, contact sheet and console log to an existing Jira issue, and post a verdict comment. |
compare <baseline> <current> | Verdict drift, newly failing checks, coverage and per-step timing deltas between two render outputs. Exits 2 when the walkthrough regressed. |
Trust the result#
| Command | What it does |
|---|---|
attest <verdict> | Re-verify a verdict: video, manifest, contact-sheet and bundle hashes recomputed — frame bytes included — and the signature checked. --bundle, --allow-unsigned. |
keygen | Generate an Ed25519 signing keypair so verdicts become third-party verifiable against a pinned key id. |
Housekeeping#
| Command | What it does |
|---|---|
doctor | Check ffmpeg, the browser and fonts, plus optional narration, vision and signing prerequisites. --ci adds container checks (TTS, sandbox, shm). |
guide | The commands grouped by workflow — what to run, in what order, and why. |
mcp | Run Playhead as an MCP server over stdio. Coding agents → |
Exit codes#
| Code | Meaning |
|---|---|
0 | Publishable. Ship it. |
1 | The app broke the flow. A partial bundle and a watchable failure clip are written. |
2 | Rendered, but failed verification. |
3 | Infrastructure problem — ffmpeg, browser, fonts. |
4 | Bad spec or bad arguments. |
Codes 1 and 2 are different on purpose.
1 means your product misbehaved and the video is evidence of a real bug. 2 means the product was fine but the video is not good enough to publish. Conflating them would make CI failures unreadable.Environment variables#
| Variable | Effect |
|---|---|
PLAYHEAD_SIGNING_KEY | HMAC-sign verdicts. For asymmetric signing use keygen instead. |
PLAYHEAD_CAPTURE=screenshot | Force the paced screenshot loop instead of the paint-driven screencast. Denser frames at a higher CPU cost — the escape hatch when a capture has gaps at the action beats. |
GROQ_API_KEY | Only used by author and demo, which fall back to a local Ollama model otherwise. Nothing else in Playhead calls out to a network. |