hyperframes/docs/packages/cli.mdx

---
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 <command>
```

## 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)

<Tip>
  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.
</Tip>

## 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.

<Tabs>
  <Tab title="Agent mode (default)">
    ```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
    ```
  </Tab>
  <Tab title="Human mode">
    ```bash
    # Interactive prompts, spinners, and selection menus
    npx hyperframes init --human-friendly
    npx hyperframes upgrade
    ```
  </Tab>
</Tabs>

### 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

<Steps>
  <Step title="Create a project">
    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.
  </Step>
  <Step title="Preview in browser">
    Start the development server with live hot reload:
    ```bash
    cd my-video
    npx hyperframes preview
    ```
    The Hyperframes Studio opens in your browser. Edit `index.html` and the preview updates instantly.
  </Step>
  <Step title="Lint your composition">
    Check for structural issues before rendering:
    ```bash
    npx hyperframes lint
    ```
    ```
    ◆  Linting my-project/index.html

    ◇  0 errors, 0 warnings
    ```
  </Step>
  <Step title="Render to MP4">
    Produce the final video:
    ```bash
    npx hyperframes render --output output.mp4
    ```
    For deterministic output, add `--docker`:
    ```bash
    npx hyperframes render --docker --output output.mp4
    ```
  </Step>
</Steps>

## Commands

<Tabs>
  <Tab title="Create">
    ### `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 |
    | `--model` | Whisper model for transcription (e.g. `small.en`, `medium.en`, `large-v3`) |
    | `--language` | Language code for transcription (e.g. `en`, `es`, `ja`). Filters non-target speech. |
    | `--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.

    ### `transcribe`

    Transcribe audio/video to word-level timestamps, or import an existing transcript:

    ```bash
    # 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
    ```

    | Flag | Description |
    |------|-------------|
    | `--dir, -d` | Project directory (default: current directory) |
    | `--model, -m` | Whisper model (default: `small.en`). Options: `tiny.en`, `base.en`, `small.en`, `medium.en`, `large-v3` |
    | `--language, -l` | Language code (e.g. `en`, `es`, `ja`). Filters out non-target language speech. |
    | `--json` | Output 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:**

    | Format | Source |
    |--------|--------|
    | whisper.cpp JSON | `hyperframes init --video`, `hyperframes transcribe` |
    | OpenAI Whisper API JSON | `openai.audio.transcriptions.create()` with word timestamps |
    | SRT subtitles | Video editors, YouTube, subtitle tools |
    | VTT subtitles | Web 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.

    <Tip>
      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.
    </Tip>
  </Tab>
  <Tab title="Preview">
    ### `preview`

    Start a live preview server with hot reload:

    ```bash
    npx hyperframes preview [dir]
    npx hyperframes preview --port 4567
    ```

    | Flag | Description |
    |------|-------------|
    | `--port` | Port to run the preview 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 preview 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]
    npx hyperframes lint [dir] --verbose   # include info-level findings
    npx hyperframes lint [dir] --json      # machine-readable JSON output
    ```
    ```
    ◆  Linting my-project/index.html

      ✗ missing_gsap_script: Composition uses GSAP but no GSAP script is loaded.
      ⚠ unmuted-video [clip-1]: Video should have the 'muted' attribute for reliable autoplay.

    ◇  1 error(s), 1 warning(s)
    ```

    By default only **errors** and **warnings** are printed. Info-level findings (e.g., external script dependency notices) are hidden to keep output clean for agents and CI. Use `--verbose` to include them.

    | Flag | Description |
    |------|-------------|
    | `--json` | Output findings as JSON (includes `errorCount`, `warningCount`, `infoCount`, and `findings` array) |
    | `--verbose` | Include info-level findings in output (hidden by default) |

    **Severity levels:**
    - **Error** (`✗`) — must fix before rendering (e.g., missing adapter library, invalid attributes)
    - **Warning** (`⚠`) — likely issues that may cause unexpected behavior
    - **Info** (`ℹ`) — informational notices, shown only with `--verbose`

    The linter detects missing attributes, missing adapter libraries (GSAP, Lottie, Three.js), structural problems, and more. See [Common Mistakes](/guides/common-mistakes) for details on each rule.
  </Tab>
  <Tab title="Build">
    ### `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/<name>.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
    ```

    <Tip>
      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.
    </Tip>

    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.
  </Tab>
  <Tab title="Utilities">
    ### `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.
  </Tab>
</Tabs>

## Related Packages

<CardGroup cols={2}>
  <Card title="Producer" icon="film" href="/packages/producer">
    The rendering pipeline the CLI calls under the hood. Use directly for programmatic rendering.
  </Card>
  <Card title="Studio" icon="palette" href="/packages/studio">
    The editor UI that powers `hyperframes preview`. Use directly to embed in your own app.
  </Card>
  <Card title="Core" icon="cube" href="/packages/core">
    Types, linter, and runtime. Use directly for custom tooling and integrations.
  </Card>
  <Card title="Engine" icon="gear" href="/packages/engine">
    The capture engine. Use directly for custom frame capture pipelines.
  </Card>
</CardGroup>