HyperFrames CLI
The complete `hyperframes` CLI reference. Every command, flag, exit code, and JSON output shape in one searchable page.
The hyperframes CLI is the single entry point for authoring, previewing, linting, and rendering deterministic video from HTML. It runs the same code path locally and in CI, so the bytes you ship are the bytes you reviewed.
This page is the index. Each command also has a dedicated reference page with full flag tables and JSON shapes.
Install
npm i -g hyperframes
# or run ad-hoc
npx hyperframes --helpCommands at a glance
| Command | Purpose |
|---|---|
init | Scaffold a new HyperFrames project. |
preview | Hot-reload preview server for a composition. |
lint | Static analysis for determinism, codec, and asset issues. |
inspect | Print composition metadata (duration, fps, tracks, deps). |
render | Produce an MP4 (or webm / prores / png) from HTML. |
doctor | Verify chromium, ffmpeg, and codec availability. |
upgrade | Self-update the CLI. |
browser | Manage the bundled Chromium build. |
add | Add an official recipe or component to your project. |
Global flags
These work on every command.
| Flag | Default | Meaning |
|---|---|---|
--json | off | Emit machine-readable JSON on stdout. Suppresses progress. |
--quiet | off | Suppress all non-error output. |
--human-friendly | on (tty) | Pretty progress, spinners, color. Auto-off when piped. |
--cwd <path> | process.cwd() | Run as if invoked from <path>. |
--no-cache | off | Bypass the on-disk frame cache. Forces a clean render. |
--help | — | Show command help. |
--version | — | Print CLI version and exit. |
--json and --human-friendly are mutually exclusive; the last one wins.
Exit codes
HyperFrames uses dense, stable exit codes so CI can branch on them.
| Code | Meaning |
|---|---|
0 | Success. |
1 | Generic failure (unhandled error, invalid input). |
2 | Lint errors present (also returned by render when lint runs first). |
3 | Render failed mid-pipeline (decoder, muxer, or page crash). |
4 | Encoder not found (ffmpeg or codec missing). |
5 | Browser launch failed (sandbox, permissions, missing chromium). |
64+ | Reserved for third-party plugins. |
Codes are also surfaced in --json output under exit_code.
A typical workflow
Most projects look like this end to end.
<!doctype html>
<html data-duration="5" data-fps="60">
<body>
<h1 data-fade="in" data-start="0.2" data-duration="0.8">
Ship it.
</h1>
</body>
</html>JSON mode
Pass --json to any command to get a structured response. Schemas are stable within a major version.
{
"command": "render",
"status": "ok",
"exit_code": 0,
"out": "video.mp4",
"size": 2400000,
"sha": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"duration_ms": 18402,
"frames": 300,
"warnings": []
}For commands that produce no artifact (lint, inspect, doctor), the shape mirrors the report. See each command page for examples.
Configuration
The CLI reads hyperframes.config.{js,ts,json} if present at the project root. Flags always win over config; config wins over defaults. A minimal config:
import { defineConfig } from "hyperframes";
export default defineConfig({
render: { width: 1920, height: 1080, fps: 60, codec: "h264", crf: 18 },
lint: { rules: { "oversize-asset": "warn" } }
});Tips
- Pin the CLI version in
package.json. Determinism is per-version; major bumps may change encoder defaults. - In CI, set
--no-cachefor release builds and leave the cache on for PR previews. - Combine
--jsonwithjqfor ad-hoc checks:hyperframes render … --json | jq .sha. --quietsuppresses output but preserves exit codes — ideal for shell scripts.
Next
- HTML schema — every
data-*attribute the renderer reads. hyperframes render— the keystone command, in depth.