ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-01 19:42:03 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
db892f4e8f7a55f19d11aba3082800dfd47b437a
hyperframes/docs/packages/cli.mdx
T
JamesandClaude Opus 4.6 db892f4e8f docs: audit and fix all documentation against actual codebase 
Comprehensive audit of every documentation page against the actual source
code, fixing incorrect APIs, wrong CLI flags, nonexistent templates, and
missing public exports. Also documents the new agent-friendly CLI design.

Key fixes:
- Quickstart: `npx create-hyperframe` → `npx hyperframes init`, Node 20→22
- Templates: replaced nonexistent blank/title-card/video-edit with actual
  templates (blank, warm-grain, play-mode, swiss-grid, vignelli)
- CLI: removed nonexistent short flags (-o/-f/-q/-w), added missing
  commands (browser, docs, telemetry, skills), documented agent-friendly
  non-interactive default and --human-friendly flag
- Producer: replaced nonexistent `render()` API with actual
  `createRenderJob()`/`executeRenderJob()`, added server API docs
- Engine: replaced nonexistent `createEngine()` with actual session-based
  API, added HfProtocol, encoding, streaming, parallel rendering docs
- Core: fixed wrong type names (Composition/Clip→TimelineElement), wrong
  function names (parseHyperframeHtml→parseHtml), documented all 4 entry
  points (main, /lint, /compiler, /runtime)
- Studio: added all missing exports (NLELayout, SourceEditor,
  PropertyPanel, FileTree, StudioApp, hooks, Tailwind preset)
- All pages: --output not -o, Node 22+ not 20+

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 18:23:32 +00:00

369 lines
12 KiB
Plaintext
Raw Blame History

---
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
```
</Tab>
<Tab title="Human mode">
```bash
# Interactive prompts, spinners, and selection menus
npx hyperframes init --human-friendly
npx hyperframes upgrade
```
</Tab>
</Tabs>
## 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]
```
Opens your composition in the Hyperframes Studio with live preview. Edits to `index.html` and any referenced sub-compositions are reflected instantly. The preview uses the same Hyperframes runtime as production rendering, so what you see is what you get.
### `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
```
```
Checking environment...
✓ Node.js v22.x
✓ FFmpeg 7.x
✓ FFprobe 7.x
✓ Chrome (bundled)
✓ Docker 24.x
✓ Docker running
All checks passed.
```
Verifies Node.js version, FFmpeg, FFprobe, Chrome, and Docker availability.
### `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 --yes # show upgrade commands without prompting
```
| Flag | Description |
|------|-------------|
| `--check` | Check for updates and exit (no prompt, agent-friendly) |
| `--yes, -y` | Show upgrade commands without prompting |
Compares your installed version against the latest on npm and provides upgrade commands.
### `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>
Reference in New Issue View Git Blame Copy Permalink