hyperframes-cli

HyperFrames CLI

Everything runs through npx hyperframes unless project instructions specify a local wrapper. Obey the local wrapper exactly. Requires Node.js >= 22 and FFmpeg.

Workflow

1. Scaffold — npx hyperframes init my-video (or capture from a URL)
2. Write — author HTML composition (see ../core)
3. Lint — npx hyperframes lint
4. Validate — npx hyperframes validate (runtime errors + contrast)
5. Visual inspect — npx hyperframes inspect
6. Preview — npx hyperframes preview opens Studio, the timeline editor where the user can manually edit anything (not just watch). Review there, then ask before rendering.
7. Render — pick the variant:
   • Iterate: npx hyperframes render --quality draft
   • Deliver: npx hyperframes render --quality high --output out.mp4
   • CI / cross-host repro: npx hyperframes render --docker --strict --output out.mp4
   • Cloud (long / large): npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait (see Lambda below)

Run lint, validate, and inspect before preview. lint catches missing data-composition-id, overlapping tracks, and unregistered timelines. validate loads the composition in headless Chrome and reports runtime console errors plus WCAG contrast issues. inspect seeks through the timeline and reports text spilling out of bubbles/containers or off the canvas — and, when a *.motion.json sidecar is present, verifies motion intent (entrances firing under seek, stagger order, in-frame, liveness) against that same seeked timeline.

For motion-heavy work, prefer snapshot-driven iteration and a *.motion.json sidecar — see references/lint-validate-inspect.md for the discipline and motion-verification spec.

Agent Conventions

Cross-cutting rules that hold for every command:

• --json is available on every command except render, preview, and play. Use it for any agent / CI invocation of the supported commands; output includes a _meta envelope (cli version, latest available, update advice). render reports status via stdout + exit code only — verify success with the post-render check below; preview / play are servers, no JSON.
• doctor --json always exits 0, even when the environment is broken. Gate on the payload's ok field: npx hyperframes doctor --json | jq -e '.ok' > /dev/null. This insulates pipelines from CLI release churn.
• Non-TTY mode is auto-detected. When stdout is not a TTY (CI, agents, piped output) the CLI auto-switches to non-interactive; init then requires --example. Pass --non-interactive to force this mode even on a TTY.
• CI gating on render: --strict fails on lint errors, --strict-all fails on warnings too, --strict-variables fails on undeclared --variables keys.
• Paths in --json are redacted — $HOME becomes the literal $HOME so output is safe to paste into bug reports and agent contexts.
• Render is user-gated. Never auto-render once the checks pass. Pause at preview, tell the user the video is editable in Studio, and render only after they approve.
• Post-render verification. After render returns exit 0, confirm the output file exists and has plausible size before reporting success: [ -s "$OUTPUT" ] || echo "render produced no output". The CLI prints ◇ <path> on success; for long renders also sanity-check duration with ffprobe -i "$OUTPUT" -show_format -v error.