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). init also checks the installed skills against the latest on GitHub and updates the global set if any are out of date. The --skip-skills flag is currently neutered (temporary, while the skills.sh registry catches up), so every init runs this check and pulls our latest skills regardless. 2. Write — author HTML composition (see the hyperframes-core skill) 3. Lint — npx hyperframes lint 4. Validate — npx hyperframes validate (runtime errors + contrast) 5. Visual inspect — npx hyperframes inspect 6. Preview / edit — 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` server modes. 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 --selection --json and preview --context --json are the preview exceptions: they do not start a server, they query the user's running Studio session and exit.
• `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.
• Use Studio context for user-directed edits. When the user says "this selected element", "the thing I clicked", "current selection", or similar, ask them to select it in Studio, then run npx hyperframes preview --context --json --context-fields selection. Use the returned selection.target.hfId / selector, selection.sourceFile, selection.currentTime, and selection.thumbnailUrl to anchor the edit. If selection is null and errors.selection.code is no-selection, ask the user to click the element and rerun; do not guess from screenshots.
• Keep Studio context compact. preview --context --json returns compact selection by default. Add --context-fields selection, --context-fields selection,lint, or --context-fields lint to avoid bloating agent context. Use --context-detail full only when you need heavy fields like computed styles, inline styles, or text-field metadata.
• 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.

Routing

Cross-Skill Hand-Offs

• Tailwind projects (init --tailwind) → use hyperframes-core (Tailwind reference) before editing classes or theme tokens.
• Registry blocks/components (hyperframes add, hyperframes catalog) → use hyperframes-registry for install paths, sub-composition wiring, and snippet merging.
• Asset preprocessing (tts, transcribe, remove-background) → use hyperframes-media for voice selection, Whisper model rules, captions, and TTS-to-captions chain.
• Parametrized renders (--variables) → declared via data-composition-variables on <html>; see hyperframes-core for the full schema.

Lambda (Cloud Rendering)

hyperframes lambda deploys distributed rendering to AWS Lambda and drives renders from your laptop or CI. End-to-end is three commands:

npx hyperframes lambda deploy                                             # provision SAM stack (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy                                            # tear down (S3 bucket is retained)

Use Lambda when a render is too long / too large for one host (multi-minute videos, 4K, large parallel batches) and you have AWS credentials configured. For dev-loop iteration stay on local render.

See references/lambda.md for prerequisites, all 6 subcommands (deploy, sites create, render, progress, destroy, policies), IAM policy validation, state files, and cost / cleanup rules.

Minimum Completion Gate

Static gates

npx hyperframes lint
npx hyperframes validate

Add inspect for layout-sensitive work and render --strict in CI to fail on lint errors.

Visual smoke test — required when the project uses sub-compositions

lint / validate / inspect evaluate each composition in isolation. They never load index.html and mount sub-compositions via data-composition-src, so they cannot catch cross-file mount failures (see hyperframes-core → references/sub-compositions.md, "Common pitfalls"). The only gate that catches them is one that actually loads index.html and seeks the timeline.

Use hyperframes snapshot — it loads the project the same way render does (so it exercises the same mount path) but only captures the timestamps you request, so it's seconds instead of a full render:

# Capture one frame at the midpoint of every sub-composition.
# Midpoints = data-start + data-duration/2 for each host slot in index.html.
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...

# Or, if you don't need per-scene targeting, an evenly-spaced sample:
npx hyperframes snapshot --frames 9

Output lands in snapshots/frame-NN-at-Xs.png. Eyeball each frame against the scene plan.

Per-frame red flags (each maps to a specific failure mode the static gates miss):

snapshots/ can be deleted after eyeballing; the user-facing final render is a separate pass with npx hyperframes render.

doctor, browser

Environment diagnosis and bundled-Chrome management. Run these first when a render or preview fails.

doctor

npx hyperframes doctor
npx hyperframes doctor --json     # CI / agent output (always exit 0; gate on payload `ok`)

Runs independent checks and reports each as ok/warn/fail:

• Version — installed CLI vs latest on npm (hints upgrade when stale)
• Node.js — ≥ 22 required
• CPU, Memory, Disk — host resources
• Environment — env vars that affect the renderer
• FFmpeg / FFprobe — found, version, codecs
• Chrome — bundled or system, version, path
• Docker / Docker running — required only for render --docker
• /dev/shm — inside containers only

Run doctor first when:

• render fails with a Chrome or FFmpeg error.
• preview opens but the composition fails to load.
• A fresh machine has never run HyperFrames.

Common issues:

• Missing FFmpeg — install via brew install ffmpeg (macOS) or your package manager.
• Missing bundled Chrome — run npx hyperframes browser ensure.
• Low memory — close other Chromes, reduce --workers, or use --quality draft.

browser

npx hyperframes browser ensure    # find or download the pinned Chrome
npx hyperframes browser path      # print the browser executable path (for scripting)
npx hyperframes browser clear     # remove the cached Chrome download

Manage the Chrome build HyperFrames uses for rendering. The pinned version exists because pixel output drifts across Chrome versions — using the bundled build keeps rendered output reproducible across machines.

Use path to embed the binary in scripts: $(npx hyperframes browser path).

init, capture, skills

Scaffolding commands. Use these instead of creating files by hand — they set up the right file structure, copy media, run transcription, and install AI coding skills.

init

npx hyperframes init my-video                                    # TTY: interactive wizard
npx hyperframes init my-video --example warm-grain               # pick an example
npx hyperframes init my-video --example blank --resolution portrait
npx hyperframes init my-video --video clip.mp4                   # with video file
npx hyperframes init my-video --audio track.mp3                  # with audio file
npx hyperframes init my-video --example blank --tailwind         # Tailwind v4 browser runtime
npx hyperframes init my-video --non-interactive --example blank  # CI/agents — flag-only

Default depends on TTY: in a terminal, the CLI prompts for example/options. Outside a TTY (CI, agents, piped output) it auto-switches to non-interactive and requires `--example` (the CLI errors with a usage example if missing). Pass --non-interactive to force flag-only mode even on a TTY.

Templates: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.

Other useful flags:

• --resolution — preset: landscape (1920×1080), portrait (1080×1920), landscape-4k, portrait-4k, square (1080×1080), square-4k. Aliases: 1080p, 4k, uhd, 1080p-square, 4k-square.
• --skip-skills — temporarily ignored: init always checks AI coding skills against GitHub while the skills.sh registry catches up. To opt out (CI/tests), set the HYPERFRAMES_SKIP_SKILLS=1 env var instead.
• --skip-transcribe — don't auto-transcribe --audio / --video with Whisper.
• --model, --language — Whisper model / language for the auto-transcription.

When using --tailwind, invoke the hyperframes-core (Tailwind reference) skill before editing classes or theme tokens. The scaffold uses Tailwind v4 browser runtime patterns, not Studio's Tailwind v3 setup.

When --audio or --video is supplied, init transcribes the file with Whisper. For voice/model selection see the hyperframes-media skill.

capture

npx hyperframes capture https://stripe.com                  # scaffold from a website
npx hyperframes capture https://linear.app -o linear-video  # custom output directory
npx hyperframes capture https://example.com --json          # JSON output for agents
npx hyperframes capture https://example.com --skip-assets   # skip image/SVG download
npx hyperframes capture https://example.com --max-screenshots 12
npx hyperframes capture https://example.com --timeout 60000 # page-load timeout in ms

Captures a live URL as an editable HyperFrames project: screenshots become layered scenes, assets are downloaded locally, and the result is a normal project you can lint / preview / render. Use this when the user supplies a URL as the starting point for a video.

skills

npx hyperframes skills    # install HyperFrames skills for AI coding tools

One-time setup that adds the HyperFrames skill pack (hyperframes-core, -creative, -animation, -cli, -registry, -media, plus the product-launch-video and hyperframes orchestrators) to the local AI coding environment so agents follow the framework conventions. Re-run after major HyperFrames upgrades.

lambda — Cloud Rendering on AWS Lambda

Deploy HyperFrames distributed rendering to AWS Lambda and drive renders from your laptop or CI. Wraps @hyperframes/aws-lambda SDK plus AWS SAM. End-to-end is three commands:

npx hyperframes lambda deploy
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy

When to Use Lambda vs Local Render

• Local `render` — dev-loop iteration, single host, anything under a few minutes at 1080p.
• `lambda render` — long videos, 4K, large parallel batches, or anything where local Chrome would time out / exhaust RAM. Pay-per-invocation, no idle cost.

For one-off short renders Lambda is not worth the deploy overhead.

Prerequisites

• AWS credentials configured (env vars, ~/.aws/credentials, SSO, or IMDS).
• AWS SAM CLI on PATH.
• bun on PATH (builds the Lambda handler ZIP).

Subcommands

deploy

npx hyperframes lambda deploy \
  --stack-name=hyperframes-prod \
  --region=us-east-1 \
  --concurrency=8 \
  --memory=10240

Builds packages/aws-lambda/dist/handler.zip and SAM-deploys the stack (Lambda + Step Functions + S3 + IAM). Idempotent — re-running on the same --stack-name is a no-op when nothing changed. Writes <cwd>/.hyperframes/lambda-stack-<name>.json so later subcommands don't need to call describe-stacks.

sites create

npx hyperframes lambda sites create ./my-project
# → siteId: abc1234deadbeef0  (stable across re-runs of the same tree)

npx hyperframes lambda render ./my-project --site-id=abc1234deadbeef0 ...

Tars + uploads <projectDir> to S3 with a content-addressed key. Returns a stable siteId you can reuse — re-renders of the same tree skip the upload.

render

npx hyperframes lambda render ./my-project \
  --width 1920 --height 1080 --fps 30 --format mp4 \
  --chunk-size 240 --max-parallel-chunks 16 \
  --wait

Starts a Step Functions execution. Returns immediately with a renderId unless --wait is set, in which case the CLI blocks until completion and streams per-chunk progress lines. Add --json for machine-parseable output.

`--width` / `--height` footgun. Setting --width 3840 --height 2160 against a composition whose data-width="1920" silently produces 1080p — the runtime lays out the page at the composition's authored dimensions and the CLI flags are ignored for layout. To actually output at 4K, use --output-resolution 4k (supersamples via deviceScaleFactor). The CLI now prints a warning when CLI dimensions disagree with the composition's data-width / data-height and --output-resolution is not set; the warning is suppressed when --json is on or index.html isn't on disk (--site-id flows).

progress

npx hyperframes lambda progress hf-render-abcd1234
npx hyperframes lambda progress arn:aws:states:us-east-1:...:execution:...

Prints one snapshot — overall percent, frames rendered, Lambda invocations, accrued cost, and any errors. Accepts a bare renderId (resolved against the stack's state-machine ARN) or a full SFN execution ARN.

destroy

npx hyperframes lambda destroy

Calls sam delete --no-prompts and drops the local state file. The render S3 bucket is configured `Retain` so it survives stack destruction — empty + delete it via the AWS console / CLI if you want the storage back.

Non-retryable errors

A subset of failures the Step Functions state machine short-circuits instead of running through its 4× 15-min retry budget. progress surfaces these immediately with the error class name; do not re-issue lambda render blindly when you see one.

• `ChromeBinaryUnavailableError` — @sparticuz/chromium returned an empty/missing executable path. A prior chunk hit Sandbox.Timedout mid-extraction and the warm instance is wedged until the execution environment recycles. Remedy: bump a Lambda env var (forces a new exec env) or lambda deploy again. Not a transient render failure; retries will burn budget on the same wedged instance.
• `FFMPEG_VERSION_MISMATCH` / `PLAN_HASH_MISMATCH` — planner / executor version drift. Re-deploy.

policies

Print or validate the minimum IAM permissions the CLI needs.

npx hyperframes lambda policies user                                  # inline policy for an IAM user
npx hyperframes lambda policies role --principal=cloudformation       # { TrustRelationship, InlinePolicy }
npx hyperframes lambda policies validate ./infra/iam/hf-deploy.json   # CI gate

validate reads a JSON policy doc and checks the union of its Effect: Allow actions (expanding s3:* / s3:Get* / * wildcards) against the CLI's required action set. Missing actions print to stderr; the command exits non-zero. Wire it into CI to catch policy drift before the next deploy fails.

The default action set is deliberately broad (Resource: "*") because CloudFormation creates new ARNs on every adopter's first deploy. Tighten Resource after that first run if security posture requires it.

State Files

hyperframes lambda stores per-stack metadata under <cwd>/.hyperframes/lambda-stack-<name>.json (bucket name, state-machine ARN, region). Not secret, but AWS-account-identifying. Commit it to a repo or .gitignore it per your workflow.

Cost and Cleanup

• lambda destroy removes the SAM stack but leaves the S3 bucket (Retain). Delete it manually if you want the storage back.
• Lambda billing is per-invocation + duration. progress reports the accrued cost.
• --concurrency caps parallel Lambda invocations — keep it aligned with your account quota.
• --chunk-size and --max-parallel-chunks trade off per-chunk overhead against parallelism; larger chunks reduce coordinator overhead, smaller chunks parallelize more aggressively.

lint, validate, inspect, snapshot

The correctness pipeline. Run in this order: lint (static, fast) → validate (runtime, headless Chrome) → inspect (layout sweep). snapshot is a separate utility for capturing still frames.

Discipline (motion-heavy work)

When the composition is animation-driven, run the checks before you reach for preview or render:

• Run lint after the first HTML pass — earlier, not later.
• Capture snapshot at meaningful timeline states; look at the PNGs.
• Inspect snapshots _before_ tuning automated warnings — your eye catches what the auditor misses.
• Treat layout warnings as defects unless a snapshot proves the overflow is intentional, in which case mark it with data-layout-allow-overflow.
• State motion intent in a *.motion.json sidecar so inspect checks it automatically — entrances firing under seek, stagger order, in-frame, liveness. This is the closest automated proxy for "watch the MP4" and catches render-≠-preview bugs the eye misses (see Motion verification below).

lint

npx hyperframes lint                  # current directory
npx hyperframes lint ./my-project     # specific project
npx hyperframes lint --verbose        # info-level findings
npx hyperframes lint --json           # machine-readable

Lints index.html and all files in compositions/. Reports errors (must fix), warnings (should fix), and info (with --verbose). Catches missing data-composition-id, overlapping tracks on the same data-track-index, and unregistered timelines.

Blind spot — media inside a sub-composition (not yet a lint rule). A <video>/<audio> inside a compositions/*.html <template> (or nested in a wrapper <div> anywhere) is never seeked/decoded and renders blank/black; lint/validate/inspect all pass. Media must be a direct child of the host root (index.html) — see hyperframes-core → variables-and-media.md. Until a rule exists, check manually before render:

grep -nE '<(video|audio)\b' compositions/*.html   # expect NO matches; media belongs in index.html

A non-empty result is a defect. Then snapshot each scene that has a video and confirm the panel actually shows footage (a blank/black panel where a clip should play is a bug, not a placeholder — treat it as render-blocking).

validate

npx hyperframes validate              # current directory
npx hyperframes validate ./my-project # specific project
npx hyperframes validate --json       # agent-readable findings
npx hyperframes validate --timeout 5000  # ms to wait for scripts (default 3000)
npx hyperframes validate --no-contrast   # skip WCAG contrast audit while iterating

Static lint is fast but blind to runtime failures. validate loads the composition in headless Chrome, plays through it, and reports:

• JavaScript console errors and unhandled exceptions
• Failed network requests (media-file ERR_ABORTED filtered out)
• WCAG AA contrast violations on visible text — sampled at 5 timestamps across the timeline. Disable with --no-contrast.

Fixing contrast warnings — thresholds are 4.5:1 for normal text, 3:1 for large text (24px+, or 19px+ bold):

• On dark backgrounds, brighten the failing color until it clears the threshold; on light backgrounds, darken it.
• Stay within the palette family — don't invent a new color, adjust the existing one.
• Re-run validate until clean.

Run validate before inspect when an animation has scripts, fetched data, or theming. Combine with render --strict in CI.

inspect

npx hyperframes inspect                 # inspect rendered layout over the timeline
npx hyperframes inspect ./my-project    # specific project
npx hyperframes inspect --json          # agent-readable findings (schemaVersion, samples, issues, bboxes)
npx hyperframes inspect --samples 15    # denser timeline sweep (default 9)
npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps
npx hyperframes inspect --tolerance 4   # allowed overflow in px before reporting (default 2)
npx hyperframes inspect --strict        # exit non-zero on warnings too (default: only errors)

Use this after lint and validate, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:

• Text extending outside the nearest visual container or bubble
• Text clipped by its own fixed-width/fixed-height box
• Text extending outside the composition canvas
• Children escaping clipping containers

Errors should be fixed before rendering. Warnings are surfaced for agent review; add --strict to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows.

Escape hatches:

• data-layout-allow-overflow — mark an element or ancestor when overflow is intentional for an entrance/exit animation.
• data-layout-ignore — mark a decorative element that should never be audited.

npx hyperframes layout remains available as a compatibility alias for the same visual inspection pass.

Motion verification (*.motion.json sidecar)

inspect also checks motion intent against the same seeked timeline the renderer uses — the closest automated proxy for "render the MP4 and watch it". It catches render-≠-preview bugs layout sampling can't: an entrance reveal the seek lands past, a broken stagger order, an element drifting off-frame mid-tween, a frozen shot.

Drop a *.motion.json sidecar next to the composition (matching the html basename when several compositions share a dir). inspect discovers it automatically — no flag, no authoring-framework changes. With no sidecar, inspect behaves exactly as before.

{
  "duration": 6,
  "assertions": [
    { "kind": "appearsBy", "selector": "#headline", "bySec": 0.5 },
    { "kind": "before", "a": "#headline", "b": "#cta" },
    { "kind": "staysInFrame", "selector": ".card" },
    { "kind": "keepsMoving", "withinSelector": ".scene" }
  ]
}

duration, withinSelector, and maxStaticSec are optional. Findings are errors by default (a failed assertion fails the run, like a layout error — --strict still gates warnings) and appear in the same human and --json output as layout findings. A selector that matches nothing is reported as motion_selector_missing rather than silently passing — so a typo'd selector fails loudly. Use this in the feedback loop instead of eyeballing the render: assert what the motion is supposed to do, and let inspect tell you when the seek diverges from intent.

snapshot

npx hyperframes snapshot                       # 5 key frames as PNG
npx hyperframes snapshot ./my-project          # specific project
npx hyperframes snapshot --frames 10           # evenly-spaced N frames

Captures still PNGs from the composition for visual diffing, thumbnails, or attaching to a PR. Faster than rendering a video when you only need a few hero frames. Output lands in the project's snapshots directory.

preview, play, render, publish

Serve, render, and share commands.

preview

npx hyperframes preview                   # serve current directory
npx hyperframes preview --port 4567       # custom port (default 3002)
npx hyperframes preview --selection --json # print the current Studio selection and exit
npx hyperframes preview --context --json  # print compact agent context from Studio

Hot-reloads on file changes. Opens Studio in the browser automatically — the full timeline editor, where the user can play the video and edit anything by hand before rendering. This is the review surface, not just a viewer.

When handing a project back to the user, use the Studio project URL, not the source index.html path:

http://localhost:<port>/#project/<project-name>

Use the actual port and project directory name; treat index.html as source-code context, not the preview surface. For example, after npx hyperframes preview --port 3017 in codex-openai-video, report http://localhost:3017/#project/codex-openai-video.

Agent context from Studio selection

preview --context and preview --selection are the agent bridge into a running Studio session. They do not start a new server; they find the active preview server for the current project, read agent-useful state from Studio, print it, and exit.

Use it when the user gives deictic edit instructions like "change this", "move the selected element", "make the card I clicked bigger", or "fix the current selection":

npx hyperframes preview --context --json --context-fields selection

The compact context payload includes the selected element's source file, composition path, current timeline time, data-hf-id / selector target, bounding box, text content, and a thumbnail URL for the selected element. Prefer selection.target.hfId when present; fall back to selection.target.selector only when no stable data-hf-id exists. If selection is null, inspect errors.selection.code (for example, no-selection).

Keep agent context small by asking only for the slices you need:

npx hyperframes preview --context --json --context-fields selection
npx hyperframes preview --context --json --context-fields lint
npx hyperframes preview --context --json --context-fields selection,lint

Use --context-detail full only when the edit genuinely needs heavy selection fields such as computedStyles, inlineStyles, dataAttributes, or editable text-field metadata:

npx hyperframes preview --context --json --context-fields selection --context-detail full

preview --selection --json remains available when you explicitly want the full selected-element payload and do not need lint/server context.

Failure modes:

If there is no selection, ask the user to click the target element in Studio and rerun the command. If the server error lists candidate ports, rerun the same command with --port <candidate>. Do not infer the target from a screenshot when the CLI can give a stable element target.

play (lightweight player)

npx hyperframes play                  # current project, port 3003
npx hyperframes play ./my-video       # specific project
npx hyperframes play --port 8080      # custom port

play serves the composition through the embeddable <hyperframes-player> web component instead of the full Studio UI. Use it when sharing a preview link or when Studio is heavier than needed (no editor, no panels). play reports the plain http://localhost:<port> URL — no #project/<name> fragment (that's a Studio routing convention only preview uses).

The player's playback-rate attribute (preview speed control, drives the timeline's timeScale) is clamped to [0.1, 5]; values ≤ 0 or non-finite fall back to 1. This is a preview/playback knob, not a composition data-* attribute — authored motion still renders at 1×.

Launching with an external browser (preview + play)

Both preview and play can open inside an explicit Chromium-compatible browser instead of the OS default. Two use cases: isolated Chromium profile, or external CDP attach (DevTools / Playwright / Puppeteer / browser-MCP). HyperFrames itself does not own CDP automation — this only exposes the endpoint; whatever connects to it is your problem. Not to be confused with --browser-gpu (a render flag controlling Chrome GPU access during capture).

# Open preview in an isolated Chromium profile
npx hyperframes preview --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile

# Same plus a CDP endpoint on :9222 (attach DevTools / Playwright / etc.)
npx hyperframes play --browser-path /usr/bin/chromium --user-data-dir /tmp/hf-profile --remote-debugging-port 9222

Validation runs before any server boots, so an invalid value exits cleanly without leaving a listening socket behind.

render

Render only after the user has reviewed in preview and approved. Don't auto-render when the checks pass.

npx hyperframes render                                # standard MP4 from cwd
npx hyperframes render ./my-video --output ./out.mp4  # render from outside the project dir
npx hyperframes render --output final.mp4             # named output (no timestamp)
npx hyperframes render -c compositions/intro.html -o intro.mp4  # render a specific sub-composition file
npx hyperframes render --quality draft                # fast iteration
npx hyperframes render --fps 60 --quality high        # final delivery
npx hyperframes render --format webm                  # transparent WebM
npx hyperframes render --docker                       # byte-identical

Default --output is renders/<project-name>_<YYYY-MM-DD>_<HH-MM-SS>.<ext> — timestamped per render so successive runs don't clobber each other. Pass --output to get a stable name.

Quality guidance: draft while iterating, standard for review, high for final delivery.

Parametrized renders: the composition declares its variables on the <html> root with `data-composition-variables` — a JSON array of declarations ({id, type, label, default} per entry) that defines the schema. Scripts inside read the resolved values via window.__hyperframes.getVariables(). The CLI --variables '{"title":"Q4 Report"}' is a JSON object keyed by id that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. Sub-comp hosts can also override per-instance with data-variable-values. See the hyperframes-core skill for the full pattern.

publish

npx hyperframes publish              # upload current project, return public URL
npx hyperframes publish ./my-video   # specific project
npx hyperframes publish --yes        # skip the confirmation prompt (scripts/CI)

Uploads the project's source (HTML + assets) and returns a stable public URL that renders in the browser. Use this for sharing a draft for review before rendering MP4, or for embedding the composition elsewhere. Lint findings are surfaced before upload but do not block.

info, upgrade, compositions, docs, benchmark, telemetry, asset preprocessing

Catch-all reference for commands that don't fit the main dev loop.

info

npx hyperframes info                   # project metadata
npx hyperframes info ./my-video        # specific project
npx hyperframes info --json

Prints project metadata: name, resolution, duration, element counts by type, track count, and total project size. Project-level — not environment. For environment health use doctor.

upgrade

npx hyperframes upgrade                # check + interactive prompt
npx hyperframes upgrade --check        # check and exit, no prompt (agent-friendly)
npx hyperframes upgrade --check --json # machine-readable: current / latest / updateAvailable
npx hyperframes upgrade --yes          # print upgrade commands without prompting

Compares the installed CLI version against npm latest.

compositions, docs

npx hyperframes compositions           # list compositions in project
npx hyperframes compositions --json
npx hyperframes docs                   # list available topics
npx hyperframes docs rendering         # print one topic inline in the terminal

compositions lists every data-composition-id in the project (including sub-comps) with duration, resolution, and element count.

docs prints inline documentation in the terminal — it does not open a browser. Topics: data-attributes, examples, rendering, gsap, troubleshooting, compositions. Run without a topic to see the list.

benchmark

npx hyperframes benchmark              # run the preset matrix in current project
npx hyperframes benchmark ./my-video   # specific project
npx hyperframes benchmark --runs 5     # repeat each config N times (default 3)
npx hyperframes benchmark --json

Renders the project with 5 preset configurations — 30fps draft 2w, 30fps standard 2w, 30fps high 2w, 30fps standard 4w, 60fps standard 4w — and prints a comparison of render speed and output file size. Use it to find the fastest acceptable preset for your machine. Not a single-render-with-stage-breakdown.

telemetry

npx hyperframes telemetry status      # show telemetry state
npx hyperframes telemetry disable     # disable anonymous usage telemetry
npx hyperframes telemetry enable      # re-enable telemetry

Telemetry is anonymous usage counters only. Disable globally with HYPERFRAMES_NO_TELEMETRY=1 if env-var control is preferred over the subcommand.

Events include two fingerprint properties used to distinguish managed-sandbox runs from real laptops — no PII, no env-var values, only existence checks:

• `sandbox_runtime`: gvisor / firecracker / docker / kvm / wsl / null. gVisor via kernel string + /proc/version. Firecracker via /dev/vsock + DMI sys_vendor. Docker via /.dockerenv + cgroup.
• `agent_runtime`: claude_code / codex / cursor / copilot_agent / jules / replit / devin / aider / gemini_cli / hermes / openclaw / null. Detected by the existence of well-known vendor env vars; the values themselves are never read.

Asset Preprocessing

npx hyperframes tts
npx hyperframes transcribe
npx hyperframes remove-background

These produce assets (narration audio, word-level transcripts, transparent video) that get dropped into a composition. Each may download its own model on first run.

For voice selection, Whisper model rules, output format choice, and the TTS → transcript → captions chain, invoke the hyperframes-media skill. This skill stays focused on the dev loop.