# Hyperframes Cli

> Bucle de desarrollo del CLI de HyperFrames: init, add, preview, render, publish, doctor y demás comandos, más el renderizado en la nube con AWS Lambda.

Fuente: https://skillsagentes.com/skills/calesthio/openmontage/hyperframes-cli
Markdown: https://skillsagentes.com/skills/calesthio/openmontage/hyperframes-cli.md

Repositorio: https://github.com/calesthio/OpenMontage
Autor: calesthio
Licencia: AGPL-3.0
Actualizado: el mes pasado
Coste de contexto: 118 tok instalada, 2.4k tok al activarse, 13.8k tok con todos los archivos del bundle
Bundle: 7 archivos, 54 KB
Permisos que pide: ninguno declarado

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add calesthio/OpenMontage --skill hyperframes-cli --agent claude-code
# Cursor
npx -y skills add calesthio/OpenMontage --skill hyperframes-cli --agent cursor
# Codex
npx -y skills add calesthio/OpenMontage --skill hyperframes-cli --agent codex
# Gemini CLI
npx -y skills add calesthio/OpenMontage --skill hyperframes-cli --agent gemini
# Windsurf
npx -y skills add calesthio/OpenMontage --skill hyperframes-cli --agent windsurf
# Cline
npx -y skills add calesthio/OpenMontage --skill hyperframes-cli --agent cline
```

## Qué hace

- Cubre el bucle de desarrollo del CLI de HyperFrames: `init`, `add`, `preview`, `render`, `publish`, `doctor` y el resto de comandos
- Es el punto de entrada del renderizado en la nube con AWS Lambda: `lambda deploy / render / progress / destroy / policies`
- Define una puerta mínima de finalización con gates estáticos: `lint`, `validate` e `inspect`
- Exige una prueba visual con `hyperframes snapshot` cuando el proyecto usa sub-composiciones, porque los gates estáticos evalúan cada composición aislada
- Mapea cada síntoma visual del snapshot a su causa: `<style>` fuera del `<template>`, o id de host distinto del id de la plantilla

## Cuándo usarla

- Se ejecuta cualquier comando `npx hyperframes …`
- Hay que diagnosticar el entorno de build o de render de HyperFrames
- Se va a renderizar en la nube con AWS Lambda

## Qué la activa

- "Renderiza este proyecto de HyperFrames"
- "Configura el render en Lambda"
- "El render falla, ¿qué comprobación hago?"
- "Saca un snapshot para revisar las escenas"

## Antes de instalar

- Necesita el CLI de HyperFrames (`npx hyperframes`); el render en la nube exige desplegar antes la función Lambda.
- Necesita en el PATH: npx

## Archivos

- SKILL.md — 9 KB
- references/doctor-browser.md — 2 KB
- references/init-and-scaffold.md — 3 KB
- references/lambda.md — 11 KB
- references/lint-validate-inspect.md — 8 KB
- references/preview-render.md — 17 KB
- references/upgrade-info-misc.md — 4 KB

## SKILL.md

Reproducido tal cual desde calesthio/OpenMontage bajo AGPL-3.0. Esta sección es el documento original y está en inglés.

# HyperFrames CLI

Everything runs through `npx hyperframes` unless project instructions specify a local wrapper. Obey the local wrapper exactly. Requires Node.js >= 22 and FFmpeg.

## Workflow

1. **Scaffold** — `npx hyperframes init my-video` (or `capture` from a URL). `init` also checks the installed skills against the latest on GitHub and updates the global set if any are out of date. The `--skip-skills` flag is currently neutered (temporary, while the skills.sh registry catches up), so every `init` runs this check and pulls our latest skills regardless.
2. **Write** — author HTML composition (see the `hyperframes-core` skill)
3. **Lint** — `npx hyperframes lint`
4. **Validate** — `npx hyperframes validate` (runtime errors + contrast)
5. **Visual inspect** — `npx hyperframes inspect`
6. **Preview** — `npx hyperframes preview` opens **Studio**, the timeline editor where the user can manually edit anything (not just watch). Review there, then ask before rendering.
7. **Render** — pick the variant:
   - Iterate: `npx hyperframes render --quality draft`
   - Deliver: `npx hyperframes render --quality high --output out.mp4`
   - CI / cross-host repro: `npx hyperframes render --docker --strict --output out.mp4`
   - Cloud (long / large): `npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait` (see Lambda below)

Run lint, validate, and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `validate` loads the composition in headless Chrome and reports runtime console errors plus WCAG contrast issues. `inspect` seeks through the timeline and reports text spilling out of bubbles/containers or off the canvas — and, when a `*.motion.json` sidecar is present, verifies motion intent (entrances firing under seek, stagger order, in-frame, liveness) against that same seeked timeline.

For motion-heavy work, prefer snapshot-driven iteration and a `*.motion.json` sidecar — see `references/lint-validate-inspect.md` for the discipline and motion-verification spec.

## Agent Conventions

Cross-cutting rules that hold for every command:

- **`--json` is available on every command except `render`, `preview`, and `play`.** Use it for any agent / CI invocation of the supported commands; output includes a `_meta` envelope (cli version, latest available, update advice). `render` reports status via stdout + exit code only — verify success with the post-render check below; `preview` / `play` are servers, no JSON.
- **`doctor --json` always exits 0**, even when the environment is broken. Gate on the payload's `ok` field: `npx hyperframes doctor --json | jq -e '.ok' > /dev/null`. This insulates pipelines from CLI release churn.
- **Non-TTY mode is auto-detected.** When `stdout` is not a TTY (CI, agents, piped output) the CLI auto-switches to non-interactive; `init` then **requires `--example`**. Pass `--non-interactive` to force this mode even on a TTY.
- **CI gating on render**: `--strict` fails on lint errors, `--strict-all` fails on warnings too, `--strict-variables` fails on undeclared `--variables` keys.
- **Paths in `--json` are redacted** — `$HOME` becomes the literal `$HOME` so output is safe to paste into bug reports and agent contexts.
- **Render is user-gated.** Never auto-render once the checks pass. Pause at `preview`, tell the user the video is editable in Studio, and render only after they approve.
- **Post-render verification.** After `render` returns exit 0, confirm the output file exists and has plausible size before reporting success: `[ -s "$OUTPUT" ] || echo "render produced no output"`. The CLI prints `◇  <path>` on success; for long renders also sanity-check duration with `ffprobe -i "$OUTPUT" -show_format -v error`.

## Routing

| Want to…                                                                                                   | Read                                  |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| Scaffold a project (`init`, `capture`, `skills`)                                                           | `references/init-and-scaffold.md`     |
| Check correctness (`lint`, `validate`, `inspect`, `snapshot`)                                              | `references/lint-validate-inspect.md` |
| Preview or render (`preview`, `play`, `render`, `publish`)                                                 | `references/preview-render.md`        |
| Diagnose the environment (`doctor`, `browser`)                                                             | `references/doctor-browser.md`        |
| Cloud render on AWS Lambda (`lambda deploy / sites / render / progress / destroy / policies`)              | `references/lambda.md`                |
| Everything else (`info`, `upgrade`, `compositions`, `docs`, `benchmark`, `telemetry`, asset preprocessing) | `references/upgrade-info-misc.md`     |

## Cross-Skill Hand-Offs

- **Tailwind projects** (`init --tailwind`) → use `hyperframes-core` (Tailwind reference) before editing classes or theme tokens.
- **Registry blocks/components** (`hyperframes add`, `hyperframes catalog`) → use `hyperframes-registry` for install paths, sub-composition wiring, and snippet merging.
- **Asset preprocessing** (`tts`, `transcribe`, `remove-background`) → use `hyperframes-media` for voice selection, Whisper model rules, captions, and TTS-to-captions chain.
- **Parametrized renders** (`--variables`) → declared via `data-composition-variables` on `<html>`; see `hyperframes-core` for the full schema.

## Lambda (Cloud Rendering)

`hyperframes lambda` deploys distributed rendering to AWS Lambda and drives renders from your laptop or CI. End-to-end is three commands:

```bash
npx hyperframes lambda deploy                                             # provision SAM stack (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy                                            # tear down (S3 bucket is retained)
```

Use Lambda when a render is too long / too large for one host (multi-minute videos, 4K, large parallel batches) and you have AWS credentials configured. For dev-loop iteration stay on local `render`.

See `references/lambda.md` for prerequisites, all 6 subcommands (`deploy`, `sites create`, `render`, `progress`, `destroy`, `policies`), IAM policy validation, state files, and cost / cleanup rules.

## Minimum Completion Gate

### Static gates

```bash
npx hyperframes lint
npx hyperframes validate
```

Add `inspect` for layout-sensitive work and `render --strict` in CI to fail on lint errors.

### Visual smoke test — required when the project uses sub-compositions

`lint` / `validate` / `inspect` evaluate each composition **in isolation**. They never load `index.html` and mount sub-compositions via `data-composition-src`, so they cannot catch cross-file mount failures (see `hyperframes-core` → `references/sub-compositions.md`, "Common pitfalls"). The only gate that catches them is one that actually loads `index.html` and seeks the timeline.

Use `hyperframes snapshot` — it loads the project the same way `render` does (so it exercises the same mount path) but only captures the timestamps you request, so it's seconds instead of a full render:

```bash
# Capture one frame at the midpoint of every sub-composition.
# Midpoints = data-start + data-duration/2 for each host slot in index.html.
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...

# Or, if you don't need per-scene targeting, an evenly-spaced sample:
npx hyperframes snapshot --frames 9
```

Output lands in `snapshots/frame-NN-at-Xs.png`. Eyeball each frame against the scene plan.

Per-frame red flags (each maps to a specific failure mode the static gates miss):

| What you see                                                                       | Root cause                                                                                  |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Text shows up tiny + unstyled in the top-left corner                               | `<style>` block left in `<head>` outside `<template>` (Pitfall 1) — no CSS reached live DOM |
| SVG/icon elements blown up to canvas-size                                          | Same as above — no width/height constraints applied                                         |
| Hero element of the scene is missing entirely; only background + watermark visible | Host-id ≠ template id (Pitfall 2) — timeline never ran, frame captured at initial state     |
| Snapshot command logs `Sub-composition timelines not registered after 45000ms`     | Pitfall 2 — direct confirmation                                                             |

`snapshots/` can be deleted after eyeballing; the user-facing final render is a separate pass with `npx hyperframes render`.

## Dónde encaja

- Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código.
- Creador: [calesthio](https://skillsagentes.com/creators/calesthio.md) — 0 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Seedance 2 5](https://skillsagentes.com/skills/calesthio/openmontage/seedance-2-5.md): Genera vídeo cinematográfico de 4-30 s con ByteDance Seedance 2.5 por fal.ai, Volcengine Ark, Runway o ComfyUI. Cubre el contrato de prompt 2.5, cortes duros, locks de continuidad y voz.
- [Comfyui](https://skillsagentes.com/skills/calesthio/openmontage/comfyui.md): Úsalo al trabajar con workflows de ComfyUI en OpenMontage: comfyui_image/video/music, workflows propios, selección de output_node, modelos que faltan, LoRAs, poca VRAM e importación de workflows de la comunidad.
- [Fish Audio Tts](https://skillsagentes.com/skills/calesthio/openmontage/fish-audio-tts.md): Genera narración expresiva y multilingüe con fish.audio (modelos S1 / S2) y reutiliza voces clonadas mediante reference_id.
- [Minimax H3](https://skillsagentes.com/skills/calesthio/openmontage/minimax-h3.md): Genera vídeo con MiniMax H3 (Hailuo 3.0) por la API oficial v2, fal.ai, Runway, nodos partner de ComfyUI o pesos abiertos locales. Clips de 4-15s a 2K con animación de primer/último fotograma.
- [Gemini Omni](https://skillsagentes.com/skills/calesthio/openmontage/gemini-omni.md): Genera y edita conversacionalmente vídeos cortos con Google Gemini Omni Flash: itera con ediciones en lenguaje natural, clips de 3-10s a 720p con audio y texto en pantalla, e imágenes de referencia por etiquetas.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)