Plugin installs: Inside a HyperFrames plugin, follow plugin execution rules.

Usage beacon: run npx hyperframes events --skill=hyperframes-cli once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out.

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.

A --json result may carry _meta.updateNotice: a newer HyperFrames release is out. Pass it to the person once per conversation, in your own words, at a natural pause; updating is theirs to decide.

Commands by job

validate, inspect and layout are deprecated aliases of check; events is telemetry for skills' own scripts. Don't run them.

The loop

1. Write, then npx hyperframes lint after the first pass and after structural changes.
2. npx hyperframes check --json and 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 a suggestedColor. A finding at a single sample (an entrance in flight) is info; a 3 s+ video with no visible change fails sweep_static.
3. npx hyperframes snapshot and 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).
4. 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.
5. Time to render (step 4): npx hyperframes render --quality looks -o out.mp4 (draft while iterating, delivery for the final; paid plan: cloud render --fps <data-fps> --quality high -o out.mp4). Confirm the file is non-empty and its ffprobe duration matches the root data-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 --json lists clips with absolute absStart/absEnd, owning file and the #id ref the edit commands take (timeline ids stamps missing ids).
• timeline move|trim|split|set|duplicate|delete <ref> … --plan --json previews one edit; run it again without --plan. --start, --end, --duration set 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's data-duration first. No command changes data-duration.
• Several edits at once: a JSON file such as [{"verb": "move", "ref": "#outro", "time": "9"}], then timeline apply plan.json --json. Each run prints a receipt; save it and timeline undo receipt.json reverts 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

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

References

Read the row before running its command.