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 dev
    ```
    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 index.html...
    No issues found.
    ```
  </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 |
    | `--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.
  </Tab>
  <Tab title="Develop">
    ### `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.
  </Tab>
  <Tab title="Build">
    ### `render`

    Render a composition to MP4:

    ```bash
    # Local mode (fast iteration)
    npx hyperframes render --output output.mp4

    # Docker mode (deterministic output)
    npx hyperframes render --docker --output output.mp4

    # With options
    npx hyperframes render --output output.mp4 --fps 60 --quality high
    ```

    | Flag | Values | Default | Description |
    |------|--------|---------|-------------|
    | `--output` | path | `renders/<name>.mp4` | Output file path |
    | `--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 |

    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 dev`. 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>