This page is based on the version from Oct 25, 2026. The skill has been updated upstream.
HyperFrames CLI
Create, check, preview, edit, and render HyperFrames video projects using command-line tools.
What this skill does
Guides agents through the HyperFrames CLI, from scaffolding projects and inspecting compositions to editing timelines, previewing videos, rendering, and publishing. It explains machine-readable output, reversible timeline edits, project history, and recovery from command failures. The workflow combines linting and runtime, layout, and contrast checks with snapshot inspection and preview review. It also covers visual comparisons, variable-driven batch renders, and rendering locally, on HeyGen’s managed cloud, or on self-managed AWS or Google Cloud infrastructure.
Try it with a task
Example request to give your agent after installation.
Check my HyperFrames project, fix reported errors, inspect snapshots of each scene, and render a final MP4 after I approve the preview.
Before you start
The CLI specifies Node.js 22+ and FFmpeg, with commands run through npx or a project wrapper. Local rendering uses Chrome; hosted rendering supplies Chromium and FFmpeg remotely. HeyGen cloud rendering requires a HeyGen credential and uses paid credits. Optional self-managed Google Cloud rendering requires authenticated gcloud, a billing-enabled project, Terraform 1.5+, and Docker or permission to use Cloud Build. Related tasks reference the hyperframes-registry, media-use, slideshow, and hyperframes skills.
Original SKILL.md
Show the original · Version 5ee3234b · fetched Oct 25, 2026 · Apache-2.0
- name
- hyperframes-cli
- description
- The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.
Plugin installs: Before setup or freshness commands, follow plugin execution rules when this skill is inside a HyperFrames plugin.
HyperFrames CLI
Run npx hyperframes <command> unless the project gives a wrapper; then use the wrapper. It needs Node.js 22+ and FFmpeg. Every command has --help; most take --json, and a failure prints ✗ …, a Fix: line and exits non-zero.
Commands by job
| Job | Commands |
|---|---|
| Start | init <dir> (blank; --example <name> only when asked), capture <url> |
| Read a project | info, compositions, timeline --json, docs <topic> |
| Check it | lint while writing; check --json as the gate (lint, runtime, layout, contrast) |
| Look at it | snapshot (--at <t,…>, --range START,END, --composition <id>, --zoom, --angle, --against <video>), keyframes, compare, audio |
| Edit the timeline | timeline with move, trim, split, set, duplicate, delete, apply, undo, ids |
| Reuse | catalog, add (/hyperframes-registry) |
| Media and sound | media-treatment, grade-compare, remove-background, tts, transcribe, beats, normalize-audio (/media-use) |
| Show and ship | preview, present (/slideshow), render, publish, cloud, lambda, cloudrun |
| Desktop app | open, catch-up |
| Upkeep | doctor, browser, upgrade, skills, usage, clean, feedback |
validate, inspect and layout are deprecated aliases of check; events is telemetry for skills' own scripts. Don't run them.
The loop
- Write, then
npx hyperframes lintafter the first pass and after structural changes. npx hyperframes check --jsonand fix every error. While a lint error remains the layout and contrast audits don't run; "0 samples" means nothing was checked. Contrast failures carry asuggestedColor. A finding at a single sample (an entrance in flight) is info; a 3 s+ video with no visible change failssweep_static.npx hyperframes snapshotand read the PNGs (under.hyperframes/artifacts/snapshots/): that is how you see the video. With sub-compositions, snapshot a midpoint of every scene; tiny unstyled content or a missing hero is a mount defect (../hyperframes/references/format.md).npx hyperframes preview --background, check the URL answers 200, give the person the project URL and wait, unless they asked for the file or for no stops. Passing checks alone is not a reason to render.- When it is time to render (step 4):
npx hyperframes render --quality looks --output out.mp4(draftwhile iterating,deliveryfor the final). Confirm the file is non-empty and itsffprobeduration matches the rootdata-duration, then look at decoded frames.
"This element" or the current selection: npx hyperframes preview --context --json --context-fields selection; no-selection means ask them to click it.
Edit the timeline
These are the edits Studio itself makes, so the result stays in Studio's shape.
timeline --jsonlists clips with absoluteabsStart/absEnd, owningfileand the#idref the edit commands take (timeline idsstamps missing ids).timeline move|trim|split|set|duplicate|delete <ref> … --plan --jsonpreviews one edit; run it again without--plan.--start,--end,--durationset one edge or the length.- An edit is refused when the clip would overlap a neighbour (
--overwrite, or move the neighbour first) or end past its composition: raise the root'sdata-durationfirst. No command changesdata-duration. - Several edits at once: a JSON file such as
[{"verb": "move", "ref": "#outro", "time": "9"}], thentimeline apply plan.json --json. Each run prints areceipt; save it andtimeline undo receipt.jsonreverts it.
Project history
Every write is kept and can be undone. At the start of a turn, npx hyperframes history begin --who <you> --label "<plan>", then history --since mine --who <you> to see what the person changed; build on their edits. A check failed or they say it got worse: history undo --who <you>, never hand-edit back. End the turn with history end.
Render where
| Need | Command |
|---|---|
| Local | render --quality looks --output out.mp4 (draft, delivery) |
| Reproducible container | render --docker --strict --output out.mp4 |
| Batch from variables | render --batch rows.json --output "renders/{name}.mp4" |
| Hosted, no local Chrome or FFmpeg | cloud render (references/cloud.md) |
| Your own AWS or GCP | lambda render, cloudrun render (references/lambda.md, references/cloudrun.md) |
A 30 s film renders in a minute or two: run it in the foreground. Detach only a render longer than your tool's timeout (HYPERFRAMES_RENDER_DETACHED=1, its own group, output to a log) and wait with until grep -qE 'Render (complete|failed)' render.log; do sleep 5; done, never pgrep -f, which matches its own loop and waits until the tool times out.
After a verified render, send one feedback --rating, plus a report for anything the person asked for that HyperFrames can't do, unless telemetry is off: references/feedback.md.
When a command fails
| Symptom | Fix |
|---|---|
| Chrome missing or won't start | npx hyperframes browser ensure; doctor --json always exits 0, gate on .ok |
| A heavy page isn't ready in time | Raise --timeout on check or snapshot |
| Unusual codec looks blank | Keep --proxy on (the default) |
| Render slow on Linux | The summary's second line says screenshot + software gpu: the slow path |
capture fails or writes BLOCKED.md | Take nothing from its partial files; retry into a new -o folder |
| Disk tight | clean --dry-run, then clean; never delete .hyperframes (it holds history) |
References
Read the row before running its command.
| Commands | Read |
|---|---|
init, capture, skills | references/init-and-scaffold.md |
lint, check, motion sidecars, snapshot | references/lint-validate-inspect.md |
compare, grade-compare, render --batch | references/compare-and-batch.md |
beats | references/beats.md |
preview, play, render, publish, Studio context | references/preview-render.md |
doctor, browser | references/doctor-browser.md |
auth, cloud, template variables | references/cloud.md |
lambda, cloudrun | references/lambda.md, references/cloudrun.md |
info, upgrade, compositions, timeline, docs, usage, telemetry | references/upgrade-info-misc.md |
--strict flags, run ids, clean, shader lint, JSON paths | references/conventions.md |
keyframes | ../hyperframes/references/motion.md (Seeing motion) |
Files
- SKILL.md
- references/conventions.md
- references/beats.md
- references/init-and-scaffold.md
- references/compare-and-batch.md
- references/cloudrun.md
- references/doctor-browser.md
- references/feedback.md
- references/cloud.md
- references/lambda.md
- references/lint-validate-inspect.md
- references/preview-render.md
- references/upgrade-info-misc.md