back
loading skill details...
HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, br...
---
name: hyperframes-cli
description: HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.
---
# HyperFrames CLI
Everything runs through `npx hyperframes`. Requires Node.js >= 22 and FFmpeg.
## Workflow
1. **Scaffold** — `npx hyperframes init my-video`
2. **Write** — author HTML composition (see the `hyperframes` skill)
3. **Lint** — `npx hyperframes lint`
4. **Visual inspect** — `npx hyperframes inspect`
5. **Preview** — `npx hyperframes preview`
6. **Render** — `npx hyperframes render`
Lint and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `inspect` opens the rendered composition in headless Chrome, seeks through the timeline, and reports text spilling out of bubbles/containers or off the canvas.
## Scaffolding
```bash
npx hyperframes init my-video # interactive wizard
npx hyperframes init my-video --example warm-grain # pick an example
npx hyperframes init my-video --video clip.mp4 # with video file
npx hyperframes init my-video --audio track.mp3 # with audio file
npx hyperframes init my-video --example blank --tailwind # with Tailwind v4 browser runtime
npx hyperframes init my-video --non-interactive # skip prompts (CI/agents)
```
Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`.
`init` creates the right file structure, copies media, transcribes audio with Whisper, and installs AI coding skills. Use it instead of creating files by hand.
When using `--tailwind`, invoke the `tailwind` skill before editing classes or theme tokens. The scaffold uses Tailwind v4.2 via the browser runtime, not Studio's Tailwind v3 setup.
## Linting
```bash
npx hyperframes lint # current directory
npx hyperframes lint ./my-project # specific project
npx hyperframes lint --verbose # info-level findings
npx hyperframes lint --json # machine-readable
```
Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (with `--verbose`).
## Visual Inspect
```bash
npx hyperframes inspect # inspect rendered layout over the timeline
npx hyperframes inspect ./my-project # specific project
npx hyperframes inspect --json # agent-readable findings
npx hyperframes inspect --samples 15 # denser timeline sweep
npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps
```
Use this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. It reports:
- Text extending outside the nearest visual container or bubble
- Text clipped by its own fixed-width/fixed-height box
- Text extending outside the composition canvas
- Children escaping clipping containers
Errors should be fixed before rendering. Warnings are surfaced for agent review; add `--strict` to fail on warnings too. Repeated static issues are collapsed by default so JSON output stays compact for LLM context windows. If overflow is intentional for an entrance/exit animation, mark the element or ancestor with `data-layout-allow-overflow`. If a decorative element should never be audited, mark it with `data-layout-ignore`.
`npx hyperframes layout` remains available as a compatibility alias for the same visual inspection pass.
## Previewing
```bash
npx hyperframes preview # serve current directory
npx hyperframes preview --port 4567 # custom port (default 3002)
```
Hot-reloads on file changes. Opens the studio in your browser automatically.
When handing a project back to the user, use the Studio project URL, not the
source `index.html` path:
```text
http://localhost:<port>/#project/<project-name>
```
Use the actual port from the preview output and the project directory name. For
example, after `npx hyperframes preview --port 3017` in `codex-openai-video`,
report `http://localhost:3017/#project/codex-openai-video`.
Treat `index.html` as source-code context only. It is fine to link it as an
implementation file, but do not label it as the project or preview surface.
## Rendering
```bash
npx hyperframes render # standard MP4
npx hyperframes render --output final.mp4 # named output
npx hyperframes render --quality draft # fast iteration
npx hyperframes render --fps 60 --quality high # final delivery
npx hyperframes render --format webm # transparent WebM
npx hyperframes render --docker # byte-identical
```
| Flag | Options | Default | Notes |
| -------------------- | --------------------- | -------------------------- | ------------------------------------------------------------------ |
| `--output` | path | renders/name_timestamp.mp4 | Output path |
| `--fps` | 24, 30, 60 | 30 | 60fps doubles render time |
| `--quality` | draft, standard, high | standard | draft for iterating |
| `--format` | mp4, webm | mp4 | WebM supports transparency |
| `--workers` | 1-8 or auto | auto | Each spawns Chrome |
| `--docker` | flag | off | Reproducible output |
| `--gpu` | flag | off | GPU-accelerated encoding |
| `--strict` | flag | off | Fail on lint errors |
| `--strict-all` | flag | off | Fail on errors AND warnings |
| `--variables` | JSON object | — | Override variable values declared in `data-composition-variables` |
| `--variables-file` | path | — | JSON file with variable values (alternative to `--variables`) |
| `--strict-variables` | flag | off | Fail render on undeclared keys or type mismatches in `--variables` |
**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.
**Parametrized renders:** the composition declares its variables on the `<html>` root with **`data-composition-variables`** — a JSON **array of declarations** (`{id, type, label, default}` per entry) that defines the schema. Scripts inside read the resolved values via `window.__hyperframes.getVariables()`. The CLI **`--variables '{"title":"Q4 Report"}'`** is a JSON **object keyed by id** that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. (Sub-comp hosts can also override per-instance with **`data-variable-values`** — same object shape, scoped to one mount of the sub-composition. See the `hyperframes` skill for the full pattern.)
## Asset Preprocessing
`npx hyperframes tts`, `transcribe`, and `remove-background` produce assets (narration audio, word-level transcripts, transparent video) that get dropped into a composition. Each downloads its own model on first run. For voice selection, whisper model rules (the `.en`-translates-non-English gotcha), output format choice (VP9 alpha WebM vs ProRes), and the TTS → transcribe → captions chain, invoke the `hyperframes-media` skill.
## Troubleshooting
```bash
npx hyperframes doctor # check environment (Chrome, FFmpeg, Node, memory)
npx hyperframes browser # manage bundled Chrome
npx hyperframes info # version and environment details
npx hyperframes upgrade # check for updates
```
Run `doctor` first if rendering fails. Common issues: missing FFmpeg, missing Chrome, low memory.
## Other
```bash
npx hyperframes compositions # list compositions in project
npx hyperframes docs # open documentation
npx hyperframes benchmark . # benchmark render performance
```
don't have the plugin yet? install it then click "run inline in claude" again.
added explicit inputs (Node.js, FFmpeg, network, disk/memory requirements), expanded procedure into six discrete steps (scaffold, lint, inspect, preview, render, troubleshoot) with detailed input/output per step, articulated decision points for template selection, error handling, Tailwind, Docker, format choice, and variable parameterization, and clarified output contract and outcome signal for each command.
the hyperframes CLI is your dev loop for building, validating, previewing, and rendering video compositions. use this skill whenever you run npx hyperframes commands, scaffold new projects with init, validate compositions with lint and inspect, hot-reload changes with preview, render final video with render, or troubleshoot your environment with doctor, browser, info, and upgrade. skip this skill and invoke hyperframes-media instead if you're doing asset preprocessing (tts, transcribe, remove-background).
node --version)ffmpeg -version)npx hyperframes browser or system-installed (required for preview and inspect)index.html, compositions/ folder, and optional media files (video, audio)init (Whisper transcription), upgrade (version check), and Tailwind runtime download--workers > 1input: desired project name, optional template, optional media files
steps:
a. run npx hyperframes init <project-name> (interactive wizard) or npx hyperframes init <project-name> --non-interactive (CI/automation)
b. optionally supply --example <template> (blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph)
c. optionally supply --video <file> or --audio <file> to embed existing media
d. optionally supply --tailwind for Tailwind v4.2 browser runtime support (invoke tailwind skill before editing Tailwind classes)
e. wait for file structure creation, media copy, audio transcription (if applicable), and AI skill installation
output: initialized project directory with index.html, compositions/ subfolder, package.json, and media assets copied to assets/
input: project directory (current dir if omitted), optional flags --verbose, --json
steps:
a. run npx hyperframes lint or npx hyperframes lint ./path/to/project
b. review error-level findings (must fix before render): missing data-composition-id, overlapping tracks, unregistered timelines, structural violations
c. review warning-level findings (should fix): unused assets, deprecated patterns, minor hygiene issues
d. if using --verbose, review info-level findings for optimization hints
e. if using --json, parse machine-readable output for agent integration
output: lint report (human text or JSON) listing errors, warnings, and info items with file/line references
input: project directory, optional flags --samples <count>, --at <timestamps>, --strict, --json
steps:
a. run npx hyperframes inspect or npx hyperframes inspect ./path/to/project after linting
b. optionally use --samples 15 (or higher) to increase timeline sweep density and catch edge-case text overflow at more frames
c. optionally use --at 1.5,4,7.25 to audit specific hero-frame timestamps instead of auto-sampling
d. optionally use --strict to fail the pass on warnings (default: warnings are surfaced but pass succeeds)
e. review findings: text extending outside containers/bubbles, text clipped by fixed dimensions, text off-canvas, children escaping clipping containers
f. fix errors before render; if overflow is intentional (entrance/exit animation), mark element with data-layout-allow-overflow; if a decorative element should never audit, mark with data-layout-ignore
g. for compact JSON output suitable for LLM context, repeated static issues collapse automatically
output: inspection report (human text or JSON) listing layout violations with severity and coordinates
input: project directory, optional --port <number> (default 3002)
steps:
a. run npx hyperframes preview or npx hyperframes preview --port 4567
b. wait for server to start; browser opens automatically to the studio interface
c. edit index.html or composition files; changes hot-reload without restart
d. navigate the studio using the URL pattern http://localhost:<port>/#project/<project-name>
e. when handing the project to the user, share the studio URL, not the source index.html path
output: local dev server running on specified port; browser tab with HyperFrames Studio open
input: project directory, optional flags (--output, --fps, --quality, --format, --workers, --docker, --gpu, --strict, --strict-all, --variables, --variables-file, --strict-variables)
steps:
a. run npx hyperframes render (standard MP4, 30fps, standard quality) or customize with flags
b. for iteration, use --quality draft (fastest, lower visual fidelity)
c. for review, use default or --quality standard
d. for final delivery, use --quality high --fps 60 (doubles render time)
e. to output WebM with transparency, use --format webm
f. to parallelize rendering across multiple Chrome processes, use --workers 4 (each worker spawns a headless Chrome; default auto scales to CPU count)
g. if byte-identical output is critical (CI reproducibility), use --docker (runs in container)
h. if GPU hardware available, use --gpu for hardware-accelerated video encoding
i. to parameterize the render, supply --variables '{"title":"Q4 Report","color":"red"}' (JSON object keyed by composition variable id) or --variables-file ./vars.json
j. if parameterization declared in composition via data-composition-variables, missing keys fall through to declared defaults
k. to fail the render if composition declares variables but --variables omits keys or supplies wrong types, use --strict-variables
l. wait for render to complete; output file written to renders/ directory with timestamp suffix (or custom path via --output)
output: MP4 or WebM video file at specified or default path
input: (none required; diagnostics run standalone)
steps:
a. run npx hyperframes doctor if rendering fails or preview doesn't start
b. review environment report: Node.js version, Chrome availability, FFmpeg availability, available system memory, disk space
c. run npx hyperframes browser to manage the bundled Chrome (list, install, remove, verify)
d. run npx hyperframes info to display CLI version, Node version, OS, and environment variables
e. run npx hyperframes upgrade to check for and install newer CLI versions
f. run npx hyperframes compositions to list all compositions in the project
g. run npx hyperframes docs to open the official documentation in your browser
h. run npx hyperframes benchmark . to profile render performance on current hardware
output: diagnostic report (text), version info, environment snapshot, or benchmark results
if running init for the first time in a project directory, then provide a project name; else if re-running init on an existing project, then risk overwriting files (confirm or use a new directory)
if you have --example template name in mind, then supply it to init; else complete the interactive wizard prompts (template, media, Tailwind preference)
if project uses Tailwind v4.2 (scaffolded with --tailwind), then invoke the tailwind skill before editing utility classes or theme tokens; else use inline styles or external CSS as usual
if lint reports errors, then fix them before preview or render; else proceed to inspect
if inspect reports errors, then fix them before render; else if inspect reports warnings only and user accepts risk, then proceed to render (or use --strict to fail)
if preview server fails to start, then run npx hyperframes doctor to diagnose FFmpeg, Chrome, or Node issues; else use the reported studio URL
if render fails, then check doctor output for missing FFmpeg or Chrome, free up memory/disk, or reduce --workers count; else check render logs for composition-specific errors (missing assets, invalid variable types)
if composition declares data-composition-variables array on html root, then override defaults with --variables JSON object or --variables-file path; else if no variables declared, then --variables flag is ignored
if using --docker, then render is reproducible across machines; else native render performance may vary by OS and hardware
if render target is transparent video (e.g., overlay), then use --format webm; else default to --format mp4
if rendering at 60fps, then expect double the time vs 30fps; else 30fps is sufficient for most content
successful lint:
{errors: [...], warnings: [...], info: [...]} with severity, message, and location keyssuccessful inspect:
{errors: [...], warnings: [...], collapsed_count: N} with coordinates and severitydata-layout-allow-overflow or data-layout-ignore present, those elements excluded from reportsuccessful preview:
http://localhost:<port>/#project/<project-name>successful render:
renders/<project>_YYYYMMDD_HHMMSS.mp4 by default)--format webm) with audio, video, and metadata intact--strict or --strict-all, render succeeds only if lint/inspect passsuccessful doctor:
index.html, compositions/, and media assets copied; audio transcribed if supplied; "init complete" message