Content & Media Creation · heygen-com/hyperframes
hyperframes-cli
Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, timeline, history, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandExternal WriteNetwork AccessWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
Formalize the entire CLI lifecycle into a 9-step loop (scaffold → catalog search for building blocks → author → lint fast feedback → check final gate → sub-composition snapshots → preview → render upon approval → verify output), establishing that check includes lint and prohibiting redundant extra lint passes.
skills/hyperframes-cli/SKILL.md
run `npx hyperframes check`; it reruns lint before opening the browser.
Purpose: Clearly define which gate to use and when, preventing agents from running both lint and check redundantly; check is the sole maintained final gate.
Explicitly define catalog search as a local-only operation (no hosted layer, no account required, search queries never sent externally), and enforce disciplines such as 'query in English' and 'inspect the tier field rather than guessing based on search result presence'.
skills/hyperframes-cli/SKILL.md
Search is entirely local: there is no hosted tier, no account, and the query text is never sent anywhere.
Purpose: Embed search privacy commitments directly into instructions while clarifying the distinction and scoring interpretation between literal (words) and semantic (on-device) ranking (top_score is evidence, not a hard threshold).
Formulate strict evaluation semantics for check: only persistent findings dictate exit codes, whereas transient entrance/exit findings are purely informational; use --strict when tighter validation is required.
skills/hyperframes-cli/SKILL.md
Persistent findings gate the exit code; transient entrance or exit findings are informational.
Purpose: Prevent agents from treating a single entrance flicker as a blocking failure, while ensuring genuine defects are not dismissed as transient glitches—gating logic is hardcoded rather than guessed.
Provide four distinct rendering paths (Local, HeyGen-hosted cloud, self-managed AWS Lambda, self-managed GCP Cloud Run), establishing clear selection criteria and a mandatory 'read reference before running' rule.
skills/hyperframes-cli/SKILL.md
Use cloud rendering when the user wants hosted rendering without local Chrome, FFmpeg, or AWS.
Purpose: Disentangle cloud rendering into hosted and self-managed responsibility models; Lambda is only worthwhile when the user already operates AWS infrastructure (stated in cloud.md), and Cloud Run is reserved for GCP environments.
Prioritize `timeline --json` over manual HTML parsing to inspect the timeline—nested rows contain absolute absStart/absEnd timings against the main timeline and owning files, saving tokens and improving accuracy compared to inspecting index.html.
skills/hyperframes-cli/SKILL.md
run `npx hyperframes timeline --json` instead of reading `index.html` and every sub-composition file
Purpose: Shift evidence collection from raw file inspection to structured output queries; the reference provides 5 jq/node one-liners (e.g., retrieve currently playing clips by absolute time, locate files by ID, find gaps and overlaps).
Treat feedback as a first-class citizen with ethical constraints: send one report after success, sanitize public submissions, conditionally attach COMPOSITION_STRUCTURE privacy bundles based on ratings, and require explicit user consent via `--file-issue` before publishing minimal reproductions.
skills/hyperframes-cli/references/preview-render.md
**Feedback is submitted to a public channel — anonymize before sending.**
Purpose: Codify reporting protocols (strip absolute paths, preserve HF_*/PRODUCER_* environment variables, include the last failed command even without a full reproduction) and strictly guarantee issues are never filed automatically.
Account for doctor JSON mode always returning exit 0 (indicating 'diagnostic execution completed' rather than 'environment is healthy'), requiring explicit inspection and gating on its payload.
skills/hyperframes-cli/SKILL.md
`doctor --json` always exits zero. Gate on its payload:
Purpose: Prevent false negatives caused by assuming exit code implies health; doctor inspects Node ≥22, CPU/memory/disk, FFmpeg/FFprobe, Chrome, Docker, etc., and compares versions against npm latest.
Explicitly identify commands that should not be run: events is an internal telemetry endpoint for skill self-reporting (not for reading telemetry), while validate/inspect/layout are deprecated aliases—only check is maintained.
skills/hyperframes-cli/SKILL.md
Two entries in `hyperframes --help` are not part of the authoring loop, and reaching for them wastes a turn
Purpose: Save agent trial-and-error iterations, clarifying that events always exits with 0 regardless of arguments and provides no capabilities.
Enforce 'read corresponding reference before executing commands' as a strict requirement rather than optional background reading: 11 command domains have dedicated documentation alongside mandatory cross-skill references (sub-composition/motion/keyframes/audio/media-use).
skills/hyperframes-cli/SKILL.md
The following references and owning skills are mandatory command contracts, not optional background reading.
Purpose: Keep SKILL.md concentrated on 'loop + discipline' while delegating details to references, relying on read-before-run to ensure parameters and failure codes are not hallucinated.
2Core Capabilities
01Project scaffolding and site capture: init to scaffold projects (resolution/presets/video-audio templates/Tailwind/non-interactive), capture to generate projects directly from a URL (including automatic Whisper transcription)
02Building block discovery and installation: catalog to query local/official registries using natural language, add to install selected blocks/components into the project for in-place customization
03Verification gates: lint for rapid feedback + check as the final gate (single browser session + single seek audit for runtime errors, failed requests, layout, motion.json assertions, and WCAG contrast) + snapshot for frame extraction and crop evidence
04Preview and presentation: preview (including --background to launch a local server) / play / present (slide deck + speaker sync) / beats (Studio beat grid) / keyframes (motion trajectory diagnostics)
05Rendering tiers and batch processing: draft/looks/delivery quality tiers, --docker for reproducible containerized rendering, --batch rows.json for parameter-driven batch generation
06Cloud and self-managed distributed rendering: HeyGen-hosted cloud (zero infrastructure), AWS Lambda, and GCP Cloud Run paths, each with dedicated reference docs and deployment/teardown lifecycles
07Publishing and cloud asset management: publish to upload project source code and generate stable hosted URLs (private by default, --public to expose), cloud list/get/delete to manage render history (including short-lived signed URLs)
08Environment diagnostics and self-healing: doctor to verify versions/Node/CPU/memory/disk/environment variables/FFmpeg/Chrome/Docker, browser commands to manage bundled Chrome instances
09Transparency and maintenance: telemetry status/enable/disable, feedback reporting, upgrade --check/--project, skills self-refresh, info/compositions/docs/benchmark, tts/transcribe/remove-background media preprocessing
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| cli | 官方 npx hyperframes CLI（本 skill 覆盖的全部子命令面；要求 Node 22+ 与 FFmpeg） |
| api | HeyGen 托管云渲染 API（zip 直传 S3 → 提交渲染 → 轮询 → 下载签名 URL；按 credit 计费） |
| cli | AWS（Lambda 自管分布式渲染：SAM 部署 Lambda + Step Functions + S3 + IAM） |
| cli | GCP（Cloud Run + Workflows + Cloud Storage，靠 gcloud 与 Terraform 部署） |
| api | npm registry（upgrade --check 比对已装版本与 npm latest；npx 首次拉取官方包） |
| network | 官方站点/文档（catalog 搜索说明页；SKILL.md 直接引用） |
| network | GitHub（init 时对着 GitHub 检查并更新已装 skill；registry 条目与 skills 自刷新） |
| package | 可选的 on-device 语义检索索引（量化 ONNX 模型 + catalog 向量，需用户同意后下载并缓存在本机） |
| cli | ffprobe（渲染后对账：时长/帧率 vs 根 data-duration） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Local script or command execution: The skill directory contains NO internal scripts (all 11 files are markdown: SKILL.md + 10 reference files); documented commands refer to the hyperframes CLI binary.
- 外部 API: Posting, creating, or modifying resources on external platforms.
- 环境变量 / API Key: Reading vendor service credentials: HeyGen credential resolution order (explicit in cloud.md): HEYGEN_API_KEY → HYPERFRAMES_API_KEY → ~/.heygen.
- 本地工作目录: File read/write and artifact output: Within projects: hyperframes.json, index.html, compositions/, renders/, snapshots/, beats/<au
Audit Notes: Evaluation targets the skill directory itself: 11 files consisting entirely of markdown, zero scripts, zero embedded endpoints, and zero code-level credential access. However, SKILL.md and its 10 reference files form the skill's declarative interface, which orchestrates upload commands involving credentials and outbound network traffic: resolving HeyGen credentials (HEYGEN_API_KEY → HYPERFRAMES_API_KEY → ~/.heygen/credentials) and uploading user project zip archives to HeyGen's cloud rendering backend (billed against account credits), as well as managing self-hosted AWS/GCP deployments, publish commands uploading source code, feedback submitted to public channels, and --file-issue publishing minimal reproductions. Per standard criteria, reading credentials for declared functionality and sending user assets to external backend services (incurring billing) warrants an Amber rating; peer skills media-use and product-launch-video (reading ~/.heygen) are likewise rated Amber. Trigger conditions are explicit: network egress only occurs when running cloud, lambda, cloudrun, publish, auth, or feedback paths, whereas the default local loop (init, add, catalog, lint, check, preview, render) remains offline. Mitigations: no executable scripts inside the directory, telemetry can be disabled and is self-described as presence-probing only, feedback includes data sanitization and consent terms, and responsibility boundaries between local and self-managed paths are clearly documented. No TLS downgrade, anti-remediation/anti-automation bypasses, or arbitrary code execution detected → does not escalate to Red.
5Second-Pass Verification
- [ok] 凭证读取是否真发生在该 skill 目录内（橙档判定关键） — 目录内无任何代码（11 个文件全 md），故严格意义上「读取」由官方 CLI 执行；橙档依据是**声明面**：cloud.md 明写凭证解析顺序 HEYGEN_API_KEY → HYPERFRAMES_API_KEY → ~/.heygen/credentials，SKILL.md 又把 auth/cloud/lambda/cloudrun/publish/feedback 列为本 skill 统领的命令。与同批 hyperframes-cli 之外的 figma（FIGMA_TOKEN）保持同一口径，并在 reason 里注明执行主体。
- [ok] SKILL.md 里的 hyperframes.heygen.com 链接是不是被当作端点调用 — 该 URL 出自「Search the catalog before writing motion by hand」段落，是 catalog 搜索的**说明页引用**（句末带句点，形如文档链接），不是命令参数；同段明确写搜索本身 entirely local、查询文本 never sent anywhere。故按范式归为文档引用，不计入外发面。
- [ok] 云上传是否真是「用户素材出网 + 消耗额度」，且是否有幂等风险提示 — cloud.md 的渲染流水线写明 zip → 直传 S3 → POST /v3/hyperframes/renders → 轮询 → 下载，并直说「you pay per credit」；同文另给安全重试条款：zip 上传非幂等，盲重试会重复计费，故须 --idempotency-key。声明与风险提示齐备，未夸大。
- [ok] feedback / telemetry 的隐私表述是否有反例 — preview-render.md 有专门的脱敏段落（剥离绝对路径、机器标识、密钥，保留 HF_*/PRODUCER_* 变量原名），并给 COMPOSITION_STRUCTURE 的「无路径/无 src URL/无用户文本」定义；upgrade-info-misc.md 说明 telemetry 指纹只做存在性探测、从不读环境变量取值，且提供 telemetry disable 与 HYPERFRAMES_NO_TELEMETRY。未发现与声明矛盾之处。
- [unlocatable] 是否漏网的高危行为（关沙箱/TLS 降级/绕过检测） — 对 keywords（sandbox / danger / no-verify / AutomationControlled / NODE_TLS / rejectUnauthorized）做全目录扫描均无命中；但本 skill 不含代码，真实执行细节在 packages/cli 内、不属于本 skill 目录，故只能声明「本目录未出现」，不能替 CLI 整体背书。
6Verdict & Scenarios
Best for: Ideal for users and agents taking HyperFrames projects from inception to final delivery: project scaffolding and site capture, finding prebuilt building blocks with natural language, iterating and gathering evidence through lint/check/snapshot cycles, switching to containerized or cloud rendering (HeyGen-hosted or self-managed AWS/GCP) when needed, publishing, upgrading versions, and using history to resume peer edits across turns in Studio. Also suited for quickly auditing timeline state via `timeline --json`.
Not for: Not suitable for: 1) Users who prohibit network egress or wish to avoid cloud credits (should rely solely on local render); 2) Environments lacking Node 22+/FFmpeg/Chrome where cloud deployment is not an option; 3) Users creating isolated motion effects without requiring the full engineering lifecycle (refer directly to specific workflow skills like /motion-graphics or /product-launch-video); 4) Detailed artistic direction of render outputs (this skill focuses on tooling mechanics; design and narrative rules reside in hyperframes-core / hyperframes-creative); 5) Restricted CI pipelines relying solely on exit codes for health checks—doctor --json always returns 0, requiring payload inspection.
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload hyperframes-cli.tar.gz
sha256:
Option B · Copy Guide for Agent9d841064257cece2…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d2f0bc7f34.