hyperframes-cli

Name: hyperframes-cli
Author: heygen-com

byheygen-com· 46 skills

Installs

296k

Stars

38k

Forks

3.6k

How to install hyperframes-cli?

heygen-com/hyperframes/hyperframes-cli

$npx -y skills add heygen-com/hyperframes --skill hyperframes-cli

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/heygen-com/hyperframes" --skill "heygen-com/hyperframes/hyperframes-cli"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/heygen-com/hyperframes" that are relevant to the current task. Run `npx skills add "https://github.com/heygen-com/hyperframes"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# HyperFrames CLI
2
3	Run commands as `npx hyperframes ...` unless project instructions provide a wrapper. Obey the wrapper when present. The CLI requires Node.js 22 or newer and FFmpeg.
4
5	## Development loop
6
7	1. Scaffold: `npx hyperframes init <project>` or capture a site. In non-TTY mode, pass `--non-interactive --example=<name>`.
8	2. Author: write the composition using `/hyperframes-core`.
9	3. Get fast feedback while editing: run `npx hyperframes lint` after the first HTML pass and after structural changes.
10	4. Run the final gate: run `npx hyperframes check`; it reruns lint before opening the browser. Do not prepend a redundant standalone lint invocation. Add `--snapshots` for annotated overview frames and finding crops.
11	5. Inspect sub-compositions: when `index.html` mounts `data-composition-src`, capture midpoint snapshots and inspect each mounted scene.
12	6. Open the final Studio preview: run `npx hyperframes preview`, hand the timeline project URL to the user, and ask whether to revise or render.
13	7. Render only after approval: use draft quality for iteration and high quality for delivery.
14	8. Verify the output: confirm the file exists, is non-empty, and has a plausible duration.
15
16	```bash
17	# Fast iteration check; repeat while authoring as needed.
18	npx hyperframes lint
19
20	# Required final gate; includes lint.
21	npx hyperframes check
22	npx hyperframes preview
23	npx hyperframes render --quality high --output out.mp4
24	test -s out.mp4
25	ffprobe -v error -show_format out.mp4
26	```
27
28	`check` runs lint first, then uses one browser session and one seek pass to audit runtime errors, failed requests, layout, `*.motion.json` assertions, and WCAG contrast. Persistent findings gate the exit code; transient entrance or exit findings are informational. Use `--strict` to gate warnings. `validate`, `inspect`, and `layout` remain aliases for compatibility but must not appear in new instructions or scripts.
29
30	## Two different preview surfaces
31
32	Do not confuse these states:
33
34	\| Surface \| When it may open \| Purpose \|
35	\| ------------------------- \| ------------------------------------------------------ \| --------------------------------------------------------------------------------- \|
36	\| Storyboard board \| Before composition checks, only when `storyboard: yes` \| Review plan cards and wireframe sketches. Open `?view=storyboard#project/<name>`. \|
37	\| Final composition preview \| After `check` passes \| Review the assembled timeline before render. Open `#project/<name>`. \|
38
39	The early board is not approval of the final video. Rendering always requires the final approval defined by `hyperframes-core/references/review-loop.md`.
40
41	## Sub-composition smoke test
42
43	Static audits cannot catch every mount failure. When the project uses sub-compositions, capture at least one visible midpoint for each host slot:
44
45	```bash
46	npx hyperframes snapshot --at <t1>,<t2>,<t3>
47	```
48
49	Treat tiny unstyled content, canvas-sized icons, missing hero elements, or timeline-registration timeouts as render-blocking mount defects. See `hyperframes-core/references/sub-compositions.md` for the corresponding fixes.
50
51	## Agent conventions
52
53	- Prefer `--json` for agent and CI calls. Server-mode `render`, `preview`, and `play` do not provide ordinary JSON output; `preview --selection --json` and `preview --context --json` are query-mode exceptions.
54	- `doctor --json` always exits zero. Gate on its payload:
55
56	```bash
57	npx hyperframes doctor --json \| jq -e '.ok' >/dev/null
58	```
59
60	- Non-TTY mode is automatic. `init` requires `--example` there; use `--non-interactive` to force deterministic behavior on a TTY.
61	- Use one `HYPERFRAMES_RUN_ID` for all commands in the same verification loop.
62	- Use `--strict`, `--strict-all`, and `--strict-variables` when the corresponding warnings, variables, or CI conditions must gate the render.
63	- JSON paths redact the home directory as `$HOME`; do not try to reverse the redaction.
64	- When a hosted cloud project approaches or exceeds the 200 MB upload limit, use `cloud render --dry-run --json` and follow the `.hyperframesignore` investigation in `references/cloud.md`. Never ignore an asset merely because it is large.
65	- Never render merely because checks pass. Pause at the final preview and wait for approval.
66
67	## Studio-directed edits
68
69	When the user refers to “this element” or the current selection, query Studio instead of guessing:
70
71	```bash
72	npx hyperframes preview --context --json --context-fields selection
73	```
74
75	Use `selection.target.hfId` when available, otherwise its selector and source file. If the result reports `no-selection`, ask the user to click the element and rerun. Request only the context slices you need; use `--context-detail full` only for computed styles or editable text metadata. Full behavior and failure codes live in `references/preview-render.md`.
76
77	## Render choices
78
79	\| Need \| Command \|
80	\| ---------------------------------------- \| ----------------------------------------------------------------------------- \|
81	\| Fast local iteration \| `npx hyperframes render --quality draft` \|
82	\| Final local delivery \| `npx hyperframes render --quality high --output out.mp4` \|
83	\| Reproducible container render \| `npx hyperframes render --docker --strict --output out.mp4` \|
84	\| Local variable-driven batch render \| `npx hyperframes render --batch rows.json --output "renders/{name}.mp4"` \|
85	\| HeyGen-hosted zero-infrastructure render \| `npx hyperframes cloud render` \|
86	\| Self-managed distributed AWS render \| `npx hyperframes lambda render <project> --width 1920 --height 1080 --wait` \|
87	\| Self-managed distributed GCP render \| `npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait` \|
88
89	Skill attribution is automatic — the examples above need no `--skill`. A project scaffolded by a workflow (`hyperframes init --skill=<workflow>`) records its owning skill in `hyperframes.json`, and every later render inherits it on anonymous telemetry: re-renders, `npm run render`, and `--batch` alike. Pass `--skill=<slug>` explicitly only to stamp a project that was not created through a workflow (its first render then persists it).
90
91	Use cloud rendering when the user wants hosted rendering without local Chrome, FFmpeg, or AWS. Use Lambda only when AWS ownership is a requirement. Use Cloud Run only when GCP ownership is a requirement. Read the matching reference before running any cloud path.
92
93	After verifying a successful render, send one feedback report unless telemetry is disabled or the user opted out:
94
95	```bash
96	npx hyperframes feedback --rating <0-10> --comment "<specific result or friction>"
97	```
98
99	Keep clean-run feedback concise. For any bug or friction, capture a reproduction packet before submitting; do not send only a symptom summary. Include the rerunnable command (relative to the project directory — feedback is submitted to a public channel, so do not paste absolute paths, home-directory prefixes, or user/machine identifiers), expected versus actual behavior, exact error (also strip absolute paths from stack traces — keep basename + line, drop the leading directory), whether output completed/fell back/failed, workaround, and repro-project status. For a rating ≤ 7 that describes a visual defect (black frame, flicker, corrupt output, wrong frame, blank output, other visual anomaly), also include a `COMPOSITION_STRUCTURE:` block — a privacy-preserving structural anatomy (element census + attribute presence + timeline shape) so maintainers can pattern-match against known bug families without the composition ZIP. Agents auto-fill this via the composition-census helper; the human user does not fill it by hand. If the issue did not reproduce again, say so and still include the last failing command and logs. Use `--file-issue` only with consent: it publishes a minimal reproduction to a public URL. The required packet format and privacy warning live in `references/preview-render.md`.
100
101	## Read the matching reference before running a command
102
103	The following references and owning skills are mandatory command contracts, not optional background reading. Before running a command in the table, read its matching row.
104
105	\| Need \| Reference \|
106	\| -------------------------------------------------------------------------------------- \| ------------------------------------- \|
107	\| `init`, `capture`, `skills` \| `references/init-and-scaffold.md` \|
108	\| `lint`, `check`, motion sidecars, `snapshot` \| `references/lint-validate-inspect.md` \|
109	\| `compare`, `grade-compare`, variable-driven `render --batch` \| `references/compare-and-batch.md` \|
110	\| `beats` for an existing project's Studio beat grid \| `references/beats.md` \|
111	\| `preview`, `play`, `render`, `publish`, Studio context, feedback \| `references/preview-render.md` \|
112	\| `doctor`, browser management \| `references/doctor-browser.md` \|
113	\| `auth`, HeyGen-hosted cloud rendering, and template variables \| `references/cloud.md` \|
114	\| AWS Lambda deployment and rendering \| `references/lambda.md` \|
115	\| Google Cloud Run deployment and rendering \| `references/cloudrun.md` \|
116	\| `info`, `upgrade`, `compositions`, `docs`, `benchmark`, telemetry, media preprocessing \| `references/upgrade-info-misc.md` \|
117
118	For composition variables, also read `/hyperframes-core` → `references/variables-and-media.md`. For `hyperframes add` and `hyperframes catalog`, use `/hyperframes-registry`. Before `hyperframes present`, read `/slideshow`; before `hyperframes keyframes`, read `/hyperframes-keyframes`. For TTS, transcription, captions, or background removal choices, use `/media-use`.
119
120	The specialized commands are deliberately documented by their owning workflows:
121
122	```bash
123	npx hyperframes present <project-dir> --port 3004 --no-open
124	npx hyperframes beats <project-dir> --json
125	npx hyperframes keyframes <project-dir> --json
126	```
127
128	`present` serves a navigable deck with presenter and audience synchronization. `beats` is the standalone Studio beat-grid utility defined in `references/beats.md`. `keyframes` surfaces seek-safe animation and motion-path diagnostics.

6 picks

Type

Run `npx skills use "https://github.com/heygen-com/hyperframes" --skill "heygen-com/hyperframes/hyperframes-cli"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/heygen-com/hyperframes" that are relevant to the current task. Run `npx skills add "https://github.com/heygen-com/hyperframes"` and select the relevant skills, then follow their instructions.

hyperframes-cli

How to install hyperframes-cli?

Related

hyperframes-cli

How to install hyperframes-cli?

Related