`doctor` is one of the first commands users and agents run when something is off — remote bug reports (e.g. #294, #316, #317) typically include a doctor screenshot, which is painful to parse programmatically. Every other CLI command that reports state already supports `--json` (info, lint, compositions, catalog, benchmark, validate, capture). This brings `doctor` in line with that convention so: - CI pipelines can gate on `hyperframes doctor --json` (exit 1 on failure) without scraping terminal output - AI agents consuming telemetry / diagnostic data get structured input - Bug report tooling can attach machine-readable doctor output Schema: { "ok": boolean, "platform": "darwin" | "linux" | "win32", "arch": "arm64" | "x64" | ..., "checks": [ { "name": "FFmpeg", "ok": true, "detail": "ffmpeg version 8.1 …" }, { "name": "Docker", "ok": false, "detail": "Not found", "hint": "https://docs.docker.com/get-docker/" } ], "_meta": { "version", "latestVersion", "updateAvailable" } } Uses the existing `withMeta()` helper so the `_meta` envelope matches other `--json` commands. Human output format is unchanged.
hyperframes
CLI for creating, previewing, and rendering HTML video compositions.
Install
npm install -g hyperframes
Or use directly with npx:
npx hyperframes <command>
Requirements: Node.js >= 22, FFmpeg
Commands
init
Scaffold a new Hyperframes project from a template:
npx hyperframes init my-video
cd my-video
preview
Start the live preview studio in your browser:
npx hyperframes preview
# Studio running at http://localhost:3002
npx hyperframes preview --port 4567
render
Render a composition to MP4:
npx hyperframes render ./my-composition.html -o output.mp4
lint
Validate your Hyperframes HTML:
npx hyperframes lint ./my-composition
npx hyperframes lint ./my-composition --json # JSON output for CI/tooling
npx hyperframes lint ./my-composition --verbose # Include info-level findings
By default only errors and warnings are shown. Use --verbose to also display informational findings (e.g., external script dependency notices). Use --json for machine-readable output with errorCount, warningCount, infoCount, and a findings array.
compositions
List compositions found in the current project:
npx hyperframes compositions
benchmark
Run rendering benchmarks:
npx hyperframes benchmark ./my-composition.html
doctor
Check your environment for required dependencies (Chrome, FFmpeg, Node.js):
npx hyperframes doctor
browser
Manage the bundled Chrome/Chromium installation:
npx hyperframes browser
info
Print version and environment info:
npx hyperframes info
docs
Open the documentation in your browser:
npx hyperframes docs
upgrade
Check for updates and show upgrade instructions:
npx hyperframes upgrade
npx hyperframes upgrade --check --json # machine-readable for agents
Documentation
Full documentation: hyperframes.heygen.com/packages/cli
Related packages
@hyperframes/core— types, parsers, frame adapters@hyperframes/engine— rendering engine@hyperframes/producer— render pipeline@hyperframes/studio— composition editor UI