Commands

Seventeen commands. You will use six of them daily; the rest are there when CI, tickets or agents need them.

Command	What it does
`playhead guide`	the whole workflow, grouped by task, with examples — start here if you are lost
`playhead doctor [--ci]`	check ffmpeg, browser, fonts, TTS voices, and container prerequisites
`playhead explore <url>`	grounded locator catalog for the current screen; --spec explores as render sees it
`playhead record <url>`	author by doing: click through your flow, get a validated spec
`playhead demo <url> "<goal>"`	one command: author → validate → render → open
`playhead init [path]`	scaffold a spec; --url grounds it in your live app
`playhead validate <spec>`	preflight every locator in one pass; --fix applies the machine-safe fixes
`playhead render <specs...>`	capture → compose → verify; --workers pools specs; --json / --junit for CI
`playhead capture <spec>`	produce a capture bundle only; --from-scene fast-forwards earlier steps unfilmed
`playhead compose <bundle>`	re-render from a bundle with no live app; --spec, --watch, --aspects, --gif
`playhead verify <bundle> <mp4>`	run the verification suite against a rendered video
`playhead say "<line>"`	audition a narration line out loud — no spec, no render
`playhead login <url>`	log in yourself in a headed browser; the session is saved for authed captures
`playhead jira report <KEY>`	attach evidence and post a verdict comment to an existing Jira issue
`playhead attest <verify-dir>`	re-verify a verdict: artifact hashes and signature
`playhead compare <a> <b>`	run-over-run regression report; exits non-zero on regression
`playhead mcp`	run as an MCP server so a coding agent can drive Playhead

The everyday loop

playhead explore http://localhost:3000     # what can I address?
playhead init demo.yaml --url http://localhost:3000
playhead validate demo.yaml                # seconds, not a render
playhead render demo.yaml -o out           # capture → compose → verify
playhead compose out/capture --spec demo.yaml -o out2 --watch   # iterate on words

Rendering several specs

playhead render specs/*.yaml -o out --workers 4 --junit out/junit.xml

Each spec renders in its own browser and its own output directory. The pool’s exit code is the worst individual outcome, so CI fails if any one video is not publishable.