The HyperFrames CLI Skill helps an agent move an HTML video project through setup, checks, preview and export. It suits developers who want code-level control over title cards and product explainers. The Skill is instruction material; the CLI, browser and FFmpeg perform the work.
Start with a five-second title card before attempting a complex film. This is a designed exercise based on CLI 0.8.159, not a recorded test. You need Node.js 22+, npm/npx, FFmpeg including ffprobe, and an agent capable of running local commands.
Choose one installation mode
If you already use the official HyperFrames plugin, use its bundled Skills and CLI launcher. Do not run standalone skills update or npx skills add within that workflow. The agent should call the plugin's skills/hyperframes/scripts/plugin-cli.mjs from your project directory. The plugin determines its CLI version; do not replace it with the npm-pinned commands below.
All commands below are for standalone installation. In your project terminal, install the official CLI Skill:
npx skills add heygen-com/hyperframes --skill hyperframes-cli
Choose your actual client, such as Claude Code or Codex, in the picker, then start a fresh session. The CLI Skill covers setup, checks, preview and export. Creating a complete new film additionally needs the hyperframes router and its selected creation workflow. A CLI-only installation is not the entire creative system.
The title-card edit also needs the core composition instructions. For standalone installation, install the official core set from the terminal before starting a fresh agent session:
npx hyperframes@0.8.159 skills update
Do not use this command in plugin mode. It fetches the core set from current main, including the router and domain Skills. Installing only hyperframes-cli is not proof that the core set is available.
1. Check the machine and create a project
In the terminal:
node --version
ffmpeg -version
ffprobe -version
npx hyperframes@0.8.159 doctor --json
Inspect the JSON ok field and individual checks. Do not rely on the exit code alone: doctor exits 0 when the command ran successfully, even when it found environment problems. Resolve Node, FFmpeg and Chrome issues first. This exercise uses local export, not Docker or cloud rendering. If Chrome is missing, the documented browser manager can locate or download a rendering browser:
npx hyperframes@0.8.159 browser ensure
Documentation's sample diagnostic output is not your machine's result. Memory and free disk matter too; begin with one worker rather than many concurrent browsers.
From the parent directory of a new practice project:
npx hyperframes@0.8.159 init title-card --non-interactive
cd title-card
This creates the default centered blank. Confirm that index.html and project configuration exist before opening the agent session. Standalone init maintains core Skills from the current GitHub source. Pinning the CLI therefore does not pin every Skill or external asset. ClawHub's Skill version is a separate identifier from the npm CLI version.
2. Give the agent a checkable edit
This is a limited edit to a scaffolded project, rather than a request to plan a new film. In a session with the Skill available, try:
Use hyperframes-cli and refer to hyperframes-core to edit this title-card project.
Turn the existing blank template into a five-second 1920×1080 title card.
Title: Release Atlas. Subtitle: A small update, clearly explained.
Use text, a solid background and a simple fade-in only. No music, external images or cloud services.
Keep text inside a safe area. Use a seekable timeline, without random values or a real-time clock.
Run check, inspect findings and start preview. Do not export yet; I will review the preview first.
Preserve the project contract. A top-level index.html composition root belongs directly in body, without a template wrapper; templates are for sub-compositions. Root data-width and data-height set canvas size. Root data-duration sets film length: an earlier-ending animation can hold its last frame, while a longer animation is cut off.
With GSAP, register a paused timeline under the matching composition ID. An effect that auto-plays on a normal web page may not work under frame-by-frame seeking. Correct the composition contract before adding decoration.
3. Check and preview
From title-card:
npx hyperframes@0.8.159 check --json
npx hyperframes@0.8.159 check --snapshots
npx hyperframes@0.8.159 preview --background
Use the first command to inspect structured results and the second when you need audited frames; there is no requirement to repeat both on every change. Check already runs lint, so do not mechanically prepend another lint to the final gate. Legacy validate, inspect and layout commands are compatibility aliases; this guide uses check.
Read ok, errors, warnings and browserSkipped. Empty layout, motion and contrast sections are not a clean result when the browser never ran. Snapshots are written under .hyperframes/artifacts/snapshots/. Audits sample the timeline; passing them does not guarantee that every frame is correct.
Open the actual URL returned by preview rather than assuming a port. Inspect the start, roughly 2.5 seconds and the end near five seconds. Verify that the title is complete, the subtitle readable and the settled frame stable, without blank output or clipping. Recheck after edits and confirm that the preview changed.
4. Export after approving the preview
In the same project directory:
npx hyperframes@0.8.159 render --output title-card.mp4 --fps 30 --quality draft --workers 1
ffprobe -v error -show_format -show_streams title-card.mp4
Check that the draft file is nonempty and playable, contains a video stream, has 1920×1080 dimensions and lasts approximately five seconds. Inspect its beginning, middle and end in a player. ffprobe reports media structure; it cannot judge typography. Five seconds at 30 fps suggests roughly 150 frames as a debugging reference, not a fabricated promise of exact output.
After reviewing the draft, choose final quality and a separate output name:
npx hyperframes@0.8.159 render --output title-card-final.mp4 --fps 30 --quality delivery --workers 1
npx hyperframes@0.8.159 preview --stop
Draft is for iteration, looks is the default quality and delivery is a final-export option. This exercise has no audio, so silence is expected. Stop this project's background preview when finished; avoid kill-all, which stops other projects too.
Troubleshoot by layer
| Problem | Check first |
|---|---|
| Doctor exits 0 but render fails | Inspect JSON ok and individual environment checks; distinguish browser, FFmpeg, disk and memory problems. |
| Black or entirely missing content | Check whether a standalone root was wrapped in template and whether composition and registered timeline IDs match. |
| Animation ends too soon | Compare root data-duration with animation timing, not just GSAP timeline length. |
| Preview works but export loses fonts or images | Check network-dependent assets, failed requests and readiness at the sampled times. |
| No findings but no proof of success | Inspect browserSkipped and sampling coverage. |
| High rendering memory | Keep workers at 1, start with a short film and small assets; more workers launch more Chrome instances. |
| Plugin commands differ | Follow the plugin launcher and update system instead of mixing standalone commands. |
Apply the workflow to real work
Use this loop for release cards, feature explainers and localized title variants. Supply accurate copy, canvas and duration before discussing scenes or assets. For a complete new film, ask the hyperframes router to select a creation workflow. The CLI exercise does not replace storyboarding or asset rights.
Fonts, CDNs and media may need network access. Your agent's model provider may receive copy or project context, so local rendering does not imply an entirely offline process. The official CLI supports disabling anonymous telemetry:
npx hyperframes@0.8.159 telemetry disable
This does not disable your agent or model provider's own data processing. Cloud rendering and external media services are separate workflows that may need accounts, permissions and payment; this exercise requires none of them. If your team already works with React video projects, see the Remotion Skill guide, keeping their composition contracts and CLI commands separate.