Skip to content
HyperFrames CLI

HyperFrames CLI Skill

HeyGen's official skill for driving the HyperFrames CLI: scaffold a video project, lint and check compositions, snapshot frames, edit the timeline, preview and render HTML compositions to MP4 locally, in Docker or in the cloud.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from heygen-com/hyperframes.

$ npx skills add heygen-com/hyperframes --skill hyperframes-cli

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/hyperframes-cli/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/heygen-com/hyperframes.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/hyperframes-cli ~/.claude/skills/hyperframes-cli

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/hyperframes-cli/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • Commands grouped by job: start, read, check, look, edit, reuse, media, ship and upkeep
  • Fixed loop: lint, check --json, read snapshots, preview, then render
  • Timeline edits with --plan previews, JSON batches and undo receipts
  • Render targets: local, Docker, batch variables, HeyGen cloud, AWS Lambda, Cloud Run
  • Troubleshooting table for Chrome, timeouts, codecs and slow Linux renders
  • Requires Node.js 22+ and FFmpeg

HyperFrames CLI is HeyGen's companion skill to the HyperFrames entry skill. Where the main skill teaches an agent how to write an HTML composition that renders to video, this one teaches it to operate the npx hyperframes command line around that composition, so the agent can build, check and ship a video without a person running the commands.

The skill groups the CLI by job rather than alphabetically: starting a project (init, capture <url>), reading one (info, compositions, timeline --json), checking it (lint while writing, check --json as the gate for lint, runtime, layout and contrast), looking at it (snapshot, keyframes, compare), editing the timeline, adding registry blocks, media and audio work (text to speech, transcription, background removal, beat detection) and finally previewing, rendering and sharing.

It prescribes a fixed working loop: lint after the first pass, fix every error check --json reports, read the snapshot PNGs to actually see the frames, start a background preview and hand the URL to the person, and only then render, with draft, looks and delivery quality tiers. Timeline edits (move, trim, split, set, duplicate, delete) can be previewed with --plan, batched from a JSON file and reverted from the receipt each run prints, and a project history lets the agent see what the person changed between turns.

Rendering can run locally, in a reproducible Docker container, in batches from a variables file, on HeyGen's hosted cloud renderer (paid plan) or on your own AWS Lambda or Google Cloud Run. A troubleshooting table covers missing Chrome, slow Linux renders, failed captures and disk cleanup.

Requirements and caveats: Node.js 22 or later and FFmpeg. The skill asks the agent to run a usage beacon (npx hyperframes events) when it starts, which sends the skill name with the CLI's normal telemetry and honours the CLI's opt-out, and to send a feedback rating after a verified render. Licensed Apache-2.0 as part of the HyperFrames repository.

SKILL.md

The instructions your agent loads, as published by HeyGen.

SKILL.md
name
hyperframes-cli
description
HyperFrames CLI - scaffold, check frames, edit timelines, preview, render, share and project history; read JSON and recover from failures.

Plugin installs: Inside a HyperFrames plugin, follow [plugin execution rules](../hyperframes/references/plugin-installation.md).

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
JobCommands
Startinit <dir> --skip-skills (blank; --example <name> only when asked), capture <url>
Read a projectinfo, compositions, timeline --json, docs <topic>
Check itlint while writing; check --json as the gate (lint, runtime, layout, contrast)
Look at itsnapshot (--at <t,…>, --range START,END, --composition <id>, --zoom, --angle, --against <video>), keyframes, compare, audio
Edit the timelinetimeline with move, trim, split, set, duplicate, delete, apply, undo, ids
Reusecatalog, add (/hyperframes-registry)
Media and soundmedia-treatment, grade-compare, remove-background, tts, transcribe, beats, normalize-audio (/media-use)
Show and shippreview, present (/slideshow), render, share, publish (legacy), cloud, lambda, cloudrun
Desktop appopen, catch-up
Upkeepdoctor, browser, upgrade, usage, clean, feedback

captions is not a command: run transcribe, then read ../hyperframes/references/captions.md.

validate, inspect and layout are deprecated aliases of check; events is skills' own telemetry. 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.

<!-- history (trial): remove this block together with the command -->

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.

<!-- /history (trial) -->

Render where
NeedCommand
Localrender --quality looks -o out.mp4 (draft, delivery)
Reproducible containerrender --docker --strict -o out.mp4
Batch from variablesrender --batch rows.json -o "renders/{name}.mp4"
Hosted, no local Chrome or FFmpegcloud render (references/cloud.md)
Your own AWS or GCPlambda 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
SymptomFix
Chrome missing or won't startnpx hyperframes browser ensure; doctor --json always exits 0, gate on .ok
A heavy page isn't ready in timeRaise --timeout on check or snapshot
Unusual codec looks blankKeep --proxy on (the default)
Render slow on LinuxThe summary's second line says screenshot + software gpu: the slow path
capture fails or writes BLOCKED.mdTake nothing from its partial files; retry into a new -o folder
Disk tightclean --dry-run, then clean; never delete .hyperframes (it holds history)
References

Read the row before running its command.

CommandsRead
init, capture, skillsreferences/init-and-scaffold.md
lint, check, motion sidecars, snapshotreferences/lint-validate-inspect.md
compare, grade-compare, render --batchreferences/compare-and-batch.md
beatsreferences/beats.md
preview, play, render, share, publish (legacy), Studio contextreferences/preview-render.md
doctor, browserreferences/doctor-browser.md
auth, cloud, template variablesreferences/cloud.md
lambda, cloudrunreferences/lambda.md, references/cloudrun.md
info, upgrade, compositions, timeline, docs, usage, telemetryreferences/upgrade-info-misc.md
--strict flags, run ids, clean, shader lint, JSON pathsreferences/conventions.md
keyframes../hyperframes/references/motion.md (Seeing motion)
Install
New

HeyGen's entry skill for HyperFrames, which renders HTML compositions to video frame by frame: the render contract, the editing loop and per-genre guides for launch films, explainers, data videos, captions and more.

New

Remotion's official skill for exporting a Remotion video: npx remotion render and still, input props, license keys and free-license renders, frame sequences and transparent video output.

New

Remotion's official skill for writing the React markup of a video: frame-driven animation with interpolate(), Studio-editable timing, media components, built-in visual effects, transitions, captions and fonts.

Browse all skills →