Skip to main content
The hyperframes CLI is the primary way to work with Hyperframes. It handles project creation, live preview, rendering, linting, and diagnostics — all from your terminal. 
npm install -g hyperframes
# or use directly with npx
npx hyperframes <command>

​
When to Use

Use the CLI when you want to:
  • Create a new composition project from an example
  • Preview compositions with live hot reload during development
  • Render compositions to MP4 (locally or in Docker)
  • Lint compositions for structural issues
  • Check your environment for missing dependencies
Use a different package if you want to:
  • Render programmatically from Node.js code — use the producer
  • Build a custom frame capture pipeline — use the engine
  • Embed a composition editor in your own web app — use the studio
  • Parse or generate composition HTML in code — use core
The CLI is the recommended starting point for all Hyperframes users. It wraps the producer, engine, and studio packages so you do not need to install them separately.

​
Agent-Friendly by Default

The CLI is non-interactive by default — designed so AI agents (Claude Code, Gemini CLI, Codex, Cursor) can drive every command without prompts or interactive UI.
  • All inputs are passed via flags (e.g., --example, --video, --output)
  • Missing required flags fail fast with a clear error and usage example
  • Output is plain text suitable for parsing
  • No interactive prompts, spinners, or selection menus
Add --human-friendly to any command to enable the interactive terminal UI with prompts, spinners, and selection menus. 
# Fully non-interactive — all inputs from flags
npx hyperframes init my-video --example blank --video video.mp4
npx hyperframes render --output output.mp4 --fps 30 --quality standard
npx hyperframes upgrade --check --json

​
JSON Output and _meta Envelope

All commands that support --json wrap their output with a _meta field containing version check info: 
{
  "name": "my-video",
  "duration": 10.5,
  "_meta": {
    "version": "0.1.4",
    "latestVersion": "0.1.5",
    "updateAvailable": true
  }
}
This allows agents to detect outdated versions from any command’s output without running a separate upgrade check. The version data comes from a 24-hour cache — no network request is made during --json output.

​
Passive Update Notices

The CLI checks npm for newer versions in the background (cached 24 hours). If an update is available, a notice appears on stderr after command completion: 
  Update available: 0.1.4 → 0.1.5
  Run: npx hyperframes@latest
This is suppressed in CI environments, non-TTY shells, and when HYPERFRAMES_NO_UPDATE_CHECK=1 is set.

​
Getting Started

1

Create a project

Scaffold a new composition from an example:
npx hyperframes init --example warm-grain
You will be prompted for a project name, or pass it as an argument:
npx hyperframes init my-video --example warm-grain
See Examples for all available examples.
2

Preview in browser

Start the development server with live hot reload:
cd my-video
npx hyperframes preview
The Hyperframes Studio opens in your browser. Edit index.html and the preview updates instantly.
3

Lint your composition

Check for structural issues before rendering:
npx hyperframes lint

◆  Linting my-project/index.html

◇  0 errors, 0 warnings
4

Render to MP4

Produce the final video:
npx hyperframes render --output output.mp4
For deterministic output, add --docker:
npx hyperframes render --docker --output output.mp4

​
Commands

​
init

Create a new composition project from an example:
# Agent mode (default) — --example is required
npx hyperframes init my-video --example blank --video video.mp4

# Human mode — interactive prompts
npx hyperframes init --human-friendly
FlagDescription
--example, -eExample to scaffold (required in default mode, interactive in --human-friendly)
--video, -VPath to a video file (MP4, WebM, MOV)
--audio, -aPath to an audio file (MP3, WAV, M4A)
--skip-skillsSkip AI coding skills installation
--skip-transcribeSkip automatic whisper transcription
--modelWhisper model for transcription (e.g. small.en, medium.en, large-v3)
--languageLanguage code for transcription (e.g. en, es, ja). Filters non-target speech.
--human-friendlyEnable interactive terminal UI with prompts
ExampleDescription
blankEmpty composition — just the scaffolding
warm-grainCream aesthetic with grain texture
play-modePlayful elastic animations
swiss-gridStructured grid layout
vignelliBold typography with red accents
In default (agent) mode, --example is required — the CLI errors with a usage example if missing. In --human-friendly mode, you choose interactively. When --video or --audio is provided, the CLI automatically transcribes the audio with Whisper and patches captions into the composition (use --skip-transcribe to disable).After scaffolding, the CLI installs AI coding skills for Claude Code, Gemini CLI, and Codex CLI (use --skip-skills to disable). See skills command.See Examples for full details.

​
add

Install a block or component from the registry into an existing project. Examples (full projects) are scaffolded with init; blocks and components are smaller units you add to a composition you already have.
# Add a block (sub-composition scene)
npx hyperframes add claude-code-window

# Add a component (effect / snippet)
npx hyperframes add shader-wipe

# Target a different project dir
npx hyperframes add shader-wipe --dir ./my-video

# Headless / CI (skip clipboard; also: --json for a machine-readable result)
npx hyperframes add shader-wipe --no-clipboard --json
FlagDescription
<name> (positional)Registry item name (e.g. claude-code-window, shader-wipe)
--dirProject directory (defaults to the current working directory)
--no-clipboardSkip copying the include snippet to the clipboard
--jsonPrint a machine-readable summary (written files + snippet) to stdout
add reads hyperframes.json at the project root to know which registry to pull from and where to drop files. If the file is missing but the directory looks like a Hyperframes project (has index.html), a default hyperframes.json is written the first time you run add.Output for a block or component is a set of files plus a paste snippet — the <iframe> tag (for blocks) or the fragment path (for components) to include in your host composition. The snippet is copied to the clipboard by default; add --no-clipboard for CI or headless environments.Trying add with an example’s name (e.g. hyperframes add warm-grain) emits a clear error pointing you at init --example.

​
catalog

Browse the registry — list available blocks and components with optional filters:
# List everything (default: table output)
npx hyperframes catalog

# Filter by type or tag
npx hyperframes catalog --type block
npx hyperframes catalog --type block --tag social

# Machine-readable JSON
npx hyperframes catalog --json

# Interactive picker — select to install
npx hyperframes catalog --human-friendly
FlagDescription
--typeFilter by block or component
--tagFilter by tag (e.g. social, transition, text)
--jsonPrint matching items as JSON (non-interactive)
--human-friendlyInteractive picker — select an item to install it
Default output is a table listing name, type, description, and tags — designed for agents to parse. --json produces structured output. --human-friendly opens an interactive picker that runs add on selection.

​
compositions

List all compositions in the current project:
npx hyperframes compositions
FlagDescription
--jsonOutput as JSON
Shows each composition’s ID, duration, resolution, and element count.

​
transcribe

Transcribe audio/video to word-level timestamps, or import an existing transcript:
# Transcribe audio/video with local whisper.cpp
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en

# Import existing transcripts from other tools
npx hyperframes transcribe subtitles.srt
npx hyperframes transcribe captions.vtt
npx hyperframes transcribe openai-response.json
FlagDescription
--dir, -dProject directory (default: current directory)
--model, -mWhisper model (default: small.en). Options: tiny.en, base.en, small.en, medium.en, large-v3
--language, -lLanguage code (e.g. en, es, ja). Filters out non-target language speech.
--jsonOutput result as JSON
The command auto-detects the input type. Audio/video files are transcribed with whisper.cpp. Transcript files (.json, .srt, .vtt) are normalized and imported.Supported transcript formats:
FormatSource
whisper.cpp JSONhyperframes init --video, hyperframes transcribe
OpenAI Whisper API JSONopenai.audio.transcriptions.create() with word timestamps
SRT subtitlesVideo editors, YouTube, subtitle tools
VTT subtitlesWeb players, YouTube, transcription services
All formats are normalized to a standard [{text, start, end}] word array and saved as transcript.json. If the project has caption HTML files, they are automatically patched with the transcript data.
For music or noisy audio, use --model medium.en for better accuracy. For the best results with production content, transcribe via the OpenAI or Groq Whisper API and import the JSON.

​
tts

Generate speech audio from text using a local AI model (Kokoro-82M). No API key required — runs entirely on-device.
# Generate speech from text
npx hyperframes tts "Welcome to HyperFrames"

# Choose a voice
npx hyperframes tts "Hello world" --voice am_adam

# Save to a specific file
npx hyperframes tts "Intro" --voice bf_emma --output narration.wav

# Adjust speech speed
npx hyperframes tts "Slow and clear" --speed 0.8

# Read text from a file
npx hyperframes tts script.txt

# List available voices
npx hyperframes tts --list
FlagDescription
--output, -oOutput file path (default: speech.wav in current directory)
--voice, -vVoice ID (run --list to see options)
--speed, -sSpeech speed multiplier (default: 1.0)
--listList available voices and exit
--jsonOutput result as JSON
Combine tts with transcribe to generate narration and word-level timestamps for captions in a single workflow: generate the audio with tts, then transcribe the output with transcribe to get word-level timing.

​
hyperframes.json

hyperframes init writes a hyperframes.json file at the root of every new project. hyperframes add reads it to know which registry to pull items from and where to drop them. Edit the file (or delete it to fall back to defaults) to reshape your project layout or point at a custom registry. 
{
  "$schema": "https://hyperframes.heygen.com/schema/hyperframes.json",
  "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
  "paths": {
    "blocks": "compositions",
    "components": "compositions/components",
    "assets": "assets"
  }
}
FieldDescription
registryBase URL of the registry add pulls from. Defaults to the public Hyperframes registry.
paths.blocksWhere block .html files land (relative to project root).
paths.componentsWhere component files land (relative to project root).
paths.assetsWhere referenced asset files (images, fonts) land.
Missing fields are filled with defaults — you only need to specify what you want to override.

Producer

The rendering pipeline the CLI calls under the hood. Use directly for programmatic rendering.

Studio

The editor UI that powers hyperframes preview. Use directly to embed in your own app.

Core

Types, linter, and runtime. Use directly for custom tooling and integrations.

Engine

The capture engine. Use directly for custom frame capture pipelines.