Files
hyperframes/packages/cli
JamesandClaude Opus 4.6 61bd39e95c feat(cli)!: rename --template to --example
PR 4/17 of the catalog system rollout. Single clean cut — the old flag
is gone, replaced by --example. Alias changes from -t to -e.

BREAKING CHANGE: --template is no longer accepted. Use --example <name>
instead. When the old flag is used, the CLI exits 1 with a rename hint
that includes the corrected command line.

## What

- Rename the init command's --template flag to --example (alias -e)
- Accept --template as a recognized-but-errored flag so users get a
  clear diagnostic instead of citty silently ignoring it and producing
  a blank project
- Update all user-visible strings that referenced "template" as a
  user-facing concept in the init flow:
  - picker prompt: "Pick a template" → "Pick an example"
  - step comment: "Pick template" → "Pick example"
  - offline-fallback suggestion: "Use --template blank" → "Use --example blank"
- New init.test.ts covering: --example scaffolds, --template exits 1
  with the rename message

## Docs (bundled in this PR per the tracker principle)

- docs/templates.mdx — all --template references
- docs/quickstart.mdx — agent-mode + video-mode examples
- docs/packages/cli.mdx — --help table, prose, alias (-e)
- packages/cli/src/docs/templates.md — help-topic doc
- No updates needed in README.md or CONTRIBUTING.md (they don't
  reference the flag)

The user-facing renames of the templates.mdx page, nav entry, and
directory routes are deferred to PR 11 (catalog discoverability UX)
as planned.

## Why

Two motivations: (1) "examples" matches shadcn + Remotion convention
for full-project scaffolds and frees "template" for future
parameterization work (string templating, placeholder substitution);
(2) once hyperframes add lands in PR 5, "template" vs "block" vs
"component" would be three subtly different concepts — renaming the
old one to "example" makes the taxonomy self-explaining.

## How

- citty silently ignores unknown flags. That meant naively removing
  --template would cause hyperframes init my-video --template warm-grain
  to silently fall through and scaffold a blank project. Very
  confusing. So --template stays declared but its run handler
  immediately errors with a rename hint including the corrected
  command. This is user guidance, not backwards compat — the old
  flag has no working behavior.
- Internal names (templateId local, getStaticTemplateDir function,
  BUNDLED_TEMPLATES constant) are unchanged in this PR. They're
  implementation details; their rename is scheduled for PR 5 when
  the compat shims in packages/cli/src/templates/ are fully removed.

## Test plan

- [x] bun run test in packages/cli: 72 passed (was 70 on #254, +2
      new init.test.ts cases). Same 4 pre-existing failures unchanged
- [x] Manual smoke: init /tmp/x --example blank succeeds; init /tmp/y
      --template blank errors with rename hint and exits 1
- [x] bunx oxfmt + bunx oxlint on changed files: clean
- [x] Pre-commit typecheck (core + studio): clean
- Also fixes an incidental regression from the PR 3 simplify-fix
  commit: the resolver test for loadAllItems' warning path was still
  spying on console.warn after the onWarn callback refactor. Now
  uses the callback directly.

## Stacks on

#254 (PR 3 — registry resolver + installer).

## Next in stack

PR 5 — feat(cli): add command + hyperframes.json. The big UX PR
where init.ts gets fully ported to the new resolver, the compat
shims are removed, and users gain the add verb for installing
blocks and components into existing projects.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-14 03:42:24 +00:00
..
2026-04-14 01:16:06 +02:00
2026-03-21 22:43:56 -07:00

hyperframes

CLI for creating, previewing, and rendering HTML video compositions.

Install

npm install -g hyperframes

Or use directly with npx:

npx hyperframes <command>

Requirements: Node.js >= 22, FFmpeg

Commands

init

Scaffold a new Hyperframes project from a template:

npx hyperframes init my-video
cd my-video

preview

Start the live preview studio in your browser:

npx hyperframes preview
# Studio running at http://localhost:3002

npx hyperframes preview --port 4567

render

Render a composition to MP4:

npx hyperframes render ./my-composition.html -o output.mp4

lint

Validate your Hyperframes HTML:

npx hyperframes lint ./my-composition
npx hyperframes lint ./my-composition --json      # JSON output for CI/tooling
npx hyperframes lint ./my-composition --verbose   # Include info-level findings

By default only errors and warnings are shown. Use --verbose to also display informational findings (e.g., external script dependency notices). Use --json for machine-readable output with errorCount, warningCount, infoCount, and a findings array.

compositions

List compositions found in the current project:

npx hyperframes compositions

benchmark

Run rendering benchmarks:

npx hyperframes benchmark ./my-composition.html

doctor

Check your environment for required dependencies (Chrome, FFmpeg, Node.js):

npx hyperframes doctor

browser

Manage the bundled Chrome/Chromium installation:

npx hyperframes browser

info

Print version and environment info:

npx hyperframes info

docs

Open the documentation in your browser:

npx hyperframes docs

upgrade

Check for updates and show upgrade instructions:

npx hyperframes upgrade
npx hyperframes upgrade --check --json  # machine-readable for agents

Documentation

Full documentation: hyperframes.heygen.com/packages/cli