--- title: CLI description: "Create, preview, and render HTML video compositions from the command line." --- 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. ```bash npm install -g hyperframes # or use directly with npx npx hyperframes ``` ## When to Use **Use the CLI when you want to:** - Create a new composition project from a template - 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](/packages/producer) - Build a custom frame capture pipeline — use the [engine](/packages/engine) - Embed a composition editor in your own web app — use the [studio](/packages/studio) - Parse or generate composition HTML in code — use [core](/packages/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., `--template`, `--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. ```bash # Fully non-interactive — all inputs from flags npx hyperframes init my-video --template blank --video video.mp4 npx hyperframes render --output output.mp4 --fps 30 --quality standard npx hyperframes upgrade --check --json ``` ```bash # Interactive prompts, spinners, and selection menus npx hyperframes init --human-friendly npx hyperframes upgrade ``` ### JSON Output and `_meta` Envelope All commands that support `--json` wrap their output with a `_meta` field containing version check info: ```json { "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 Scaffold a new composition from a template: ```bash npx hyperframes init --template warm-grain ``` You will be prompted for a project name, or pass it as an argument: ```bash npx hyperframes init my-video --template warm-grain ``` See [Templates](/guides/templates) for all available templates. Start the development server with live hot reload: ```bash cd my-video npx hyperframes dev ``` The Hyperframes Studio opens in your browser. Edit `index.html` and the preview updates instantly. Check for structural issues before rendering: ```bash npx hyperframes lint ``` ``` Linting index.html... No issues found. ``` Produce the final video: ```bash npx hyperframes render --output output.mp4 ``` For deterministic output, add `--docker`: ```bash npx hyperframes render --docker --output output.mp4 ``` ## Commands ### `init` Create a new composition project from a template: ```bash # Agent mode (default) — --template is required npx hyperframes init my-video --template blank --video video.mp4 # Human mode — interactive prompts npx hyperframes init --human-friendly ``` | Flag | Description | |------|-------------| | `--template, -t` | Template to use (required in default mode, interactive in `--human-friendly`) | | `--video, -V` | Path to a video file (MP4, WebM, MOV) | | `--audio, -a` | Path to an audio file (MP3, WAV, M4A) | | `--skip-skills` | Skip AI coding skills installation | | `--skip-transcribe` | Skip automatic whisper transcription | | `--human-friendly` | Enable interactive terminal UI with prompts | | Template | Description | |----------|-------------| | `blank` | Empty composition — just the scaffolding | | `warm-grain` | Cream aesthetic with grain texture | | `play-mode` | Playful elastic animations | | `swiss-grid` | Structured grid layout | | `vignelli` | Bold typography with red accents | In default (agent) mode, `--template` 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`](#skills) command. See [Templates](/guides/templates) for full details. ### `compositions` List all compositions in the current project: ```bash npx hyperframes compositions ``` | Flag | Description | |------|-------------| | `--json` | Output as JSON | Shows each composition's ID, duration, resolution, and element count. ### `dev` Start a live preview server with hot reload: ```bash npx hyperframes dev [dir] npx hyperframes dev --port 4567 ``` | Flag | Description | |------|-------------| | `--port` | Port to run the dev server on (default: 3002) | Opens your composition in the Hyperframes Studio with live preview. Edits to `index.html` and any referenced sub-compositions are reflected automatically. The preview uses the same Hyperframes runtime as production rendering, so what you see is what you get. The dev server runs in three modes, auto-detected: 1. **Embedded mode** (default for `npx`) — runs a standalone server with the studio bundled in the CLI. Zero extra dependencies. 2. **Local studio mode** — if `@hyperframes/studio` is installed in your project's `node_modules`, spawns Vite with full HMR for faster iteration. 3. **Monorepo mode** — if running from the Hyperframes source repo, spawns the studio dev server directly. ### `lint` Check a composition for common issues: ```bash npx hyperframes lint [dir] ``` ``` Linting index.html... WARNING unmuted-video Video element 'clip-1' should have the 'muted' attribute for reliable autoplay. at index.html:5 1 issue found (0 errors, 1 warning) ``` | Flag | Description | |------|-------------| | `--json` | Output findings as JSON | The linter detects missing attributes, deprecated names, structural problems, and more. See [Common Mistakes](/guides/common-mistakes) for details on each rule. ### `render` Render a composition to MP4 or WebM: ```bash # Local mode (fast iteration) npx hyperframes render --output output.mp4 # Docker mode (deterministic output) npx hyperframes render --docker --output output.mp4 # WebM with transparency (for overlays, captions, lower thirds) npx hyperframes render --format webm --output overlay.webm # With options npx hyperframes render --output output.mp4 --fps 60 --quality high ``` | Flag | Values | Default | Description | |------|--------|---------|-------------| | `--output` | path | `renders/.mp4` | Output file path | | `--format` | mp4, webm | mp4 | Output format (WebM renders with transparency) | | `--fps` | 24, 30, 60 | 30 | Frames per second | | `--quality` | draft, standard, high | standard | Encoding quality preset | | `--workers` | 1-8 | 4 | Parallel render workers | | `--gpu` | — | off | GPU encoding (NVENC, VideoToolbox, VAAPI) | | `--docker` | — | off | Use Docker for [deterministic rendering](/concepts/determinism) | | `--quiet` | — | off | Suppress verbose output | #### WebM with Transparency Use `--format webm` to render compositions with a transparent background. This produces VP9 video with alpha channel in a WebM container — the standard format for overlayable video. ```bash # Render a caption overlay with transparent background npx hyperframes render --format webm --output captions.webm # Overlay on another video with FFmpeg ffmpeg -c:v libvpx-vp9 -i captions.webm -i background.mp4 \ -filter_complex "[1:v][0:v]overlay=0:0" -y composited.mp4 ``` For transparency to work, your composition's HTML should use `background: transparent` on the root elements. WebM renders use PNG frame capture (instead of JPEG) to preserve the alpha channel. See [Rendering](/guides/rendering) for all options and modes. ### `benchmark` Find optimal render settings for your system: ```bash npx hyperframes benchmark [dir] ``` | Flag | Values | Default | Description | |------|--------|---------|-------------| | `--runs` | 1-20 | 3 | Number of runs per configuration | | `--json` | — | off | Output results as JSON | Runs multiple render configurations (varying fps, quality, and worker count) and compares timing and file size for each. ### `doctor` Check your environment for required dependencies: ```bash npx hyperframes doctor ``` ``` hyperframes doctor ✓ Version 0.1.4 (latest) ✓ Node.js v22.x (linux x64) ✓ FFmpeg 7.x ✓ FFprobe 7.x ✓ Chrome (system or cached) ✓ Docker 24.x ✓ Docker running Running ◇ All checks passed ``` Verifies CLI version, Node.js, FFmpeg, FFprobe, Chrome, and Docker availability. If a newer CLI version is available, the version row shows an upgrade hint. ### `info` Display project metadata: ```bash npx hyperframes info [dir] ``` | Flag | Description | |------|-------------| | `--json` | Output as JSON | Shows project name, resolution, duration, element counts by type, track count, and total project size. ### `upgrade` Check for updates and show upgrade instructions: ```bash npx hyperframes upgrade npx hyperframes upgrade --check # check and exit (no prompt) npx hyperframes upgrade --check --json # machine-readable for agents npx hyperframes upgrade --yes # show upgrade commands without prompting ``` | Flag | Description | |------|-------------| | `--check` | Check for updates and exit (no prompt, agent-friendly) | | `--json` | Output as JSON (includes `_meta` envelope) | | `--yes, -y` | Show upgrade commands without prompting | Compares your installed version against the latest on npm. With `--check --json`, returns: ```json { "current": "0.1.4", "latest": "0.1.5", "updateAvailable": true, "_meta": { "version": "0.1.4", "latestVersion": "0.1.5", "updateAvailable": true } } ``` ### `browser` Manage the Chrome browser used for rendering: ```bash # Find or download Chrome for rendering npx hyperframes browser ensure # Print the browser executable path (for scripting) npx hyperframes browser path # Remove cached Chrome download npx hyperframes browser clear ``` The `path` subcommand outputs only the path, useful in scripts: `$(npx hyperframes browser path)`. ### `docs` View inline documentation in the terminal: ```bash npx hyperframes docs [topic] ``` Available topics: `data-attributes`, `templates`, `rendering`, `gsap`, `troubleshooting`, `compositions`. Run without a topic to see the full list. ### `telemetry` Manage anonymous usage telemetry: ```bash npx hyperframes telemetry enable npx hyperframes telemetry disable npx hyperframes telemetry status ``` Telemetry collects command names, render performance, template choices, and system info. It does **not** collect file paths, project names, video content, or personally identifiable information. Disable with `HYPERFRAMES_NO_TELEMETRY=1` or the command above. ### `skills` Install HyperFrames and GSAP skills for AI coding tools: ```bash # Install to all default targets (Claude Code, Gemini CLI, Codex CLI) npx hyperframes skills # Install to specific tools npx hyperframes skills --claude npx hyperframes skills --cursor npx hyperframes skills --claude --gemini ``` | Flag | Description | |------|-------------| | `--claude` | Install to Claude Code (`~/.claude/skills/`) | | `--gemini` | Install to Gemini CLI (`~/.gemini/skills/`) | | `--codex` | Install to Codex CLI (`~/.codex/skills/`) | | `--cursor` | Install to Cursor (`.cursor/skills/` in current project) | Skills are fetched from GitHub and include composition authoring, GSAP animation patterns, and other domain-specific knowledge. The `init` command also offers to install skills automatically after scaffolding a project. ## Related Packages The rendering pipeline the CLI calls under the hood. Use directly for programmatic rendering. The editor UI that powers `hyperframes dev`. Use directly to embed in your own app. Types, linter, and runtime. Use directly for custom tooling and integrations. The capture engine. Use directly for custom frame capture pipelines.