Files
T
Wenbo ZhuandClaude Opus 5.5 7cb6018c6b feat(cli): surface outdated CLI and skills to agents; add hyperframes update --check (#7094)
* feat(cli): surface outdated CLI and skills to agents; add hyperframes update

Single commit of #7094 on top of main (no merge commits through the signed
GraphQL path). Includes: 2h update/skills check interval and stale-cache
recheck; `_meta.checkedAt`, `_meta.skillsOutdated`, `_meta.skillsMissing`;
`_meta.updateNotice`, one sentence for the agent to relay to the person, at
most once a day per project (brew/npx-aware command, omitted under CI, the
update-check opt-out and agent plugins); `hyperframes update [--check]
[--yes] [--json]` (CLI then skills at the installed CLI's tag; brew
version read back); doctor names the running binary and its channel; the
hyperframes-cli skill gets one line to pass the notice on, naming no
command. Keeps main's install-target skills check (#7120) in updateSkills.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): update notice names a command that moves this install

- `_meta.updateNotice` (and `update --check`'s skills command) now name a
  command that moves the running install: a global npm/pnpm/bun/brew CLI
  runs its own `hyperframes update` (or just its manager's command when
  only the CLI is behind), since `npx hyperframes` would run a project's
  copy or a fresh npx one; a project-local CLI moves with its project's
  manager by lockfile (`npm install`/`pnpm add`/`bun add`/`yarn add
  hyperframes@<v>`), which `update --yes` now names too instead of
  `npx hyperframes@latest`.
- `update`'s confirmation hint states a fact and names no step for the
  agent: "Updating is the person's call; `update --check` only reports."
- `upgrade --json`, `upgrade --project --json` and every `skills` JSON
  output leave out `_meta.updateNotice` (NO_UPDATE_NOTICE), like `update`.
- dailyNotice: a null/non-object file reads as empty and is repaired; a
  future timestamp is stale; writes go through a 0600 tmp file + rename;
  withMeta never throws from the notice.
- Docs: --json without --yes exits 2; plugin `update` exits 1
  (plugin_managed); full `_meta` sample; per-install notice commands.
  `update --check` says "npm registry not reached" instead of "latest".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 09:31:52 +00:00

7.2 KiB

name, description
name description
hyperframes-cli The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.

Plugin installs: Before setup or freshness commands, follow plugin execution rules when this skill is inside a HyperFrames plugin.

HyperFrames CLI

Run npx hyperframes <command> unless the project gives a wrapper; then use the wrapper. It needs Node.js 22+ and FFmpeg. Every command has --help; most take --json, and a failure prints ✗ …, a Fix: line and exits non-zero.

A --json result may carry _meta.updateNotice: a newer HyperFrames release is out. Pass it to the person once per conversation, in your own words, at a natural pause; updating is theirs to decide.

Commands by job

Job Commands
Start init <dir> (blank; --example <name> only when asked), capture <url>
Read a project info, compositions, timeline --json, docs <topic>
Check it lint while writing; check --json as the gate (lint, runtime, layout, contrast)
Look at it snapshot (--at <t,…>, --range START,END, --composition <id>, --zoom, --angle, --against <video>), keyframes, compare, audio
Edit the timeline timeline with move, trim, split, set, duplicate, delete, apply, undo, ids
Reuse catalog, add (/hyperframes-registry)
Media and sound media-treatment, grade-compare, remove-background, tts, transcribe, beats, normalize-audio (/media-use)
Show and ship preview, present (/slideshow), render, publish, cloud, lambda, cloudrun
Desktop app open, catch-up
Upkeep doctor, browser, upgrade, skills, usage, clean, feedback

validate, inspect and layout are deprecated aliases of check; events is telemetry for skills' own scripts. Don't run them.

The loop

  1. Write, then npx hyperframes lint after the first pass and after structural changes.
  2. npx hyperframes check --json and fix every error. While a lint error remains the layout and contrast audits don't run; "0 samples" means nothing was checked. Contrast failures carry a suggestedColor. A finding at a single sample (an entrance in flight) is info; a 3 s+ video with no visible change fails sweep_static.
  3. npx hyperframes snapshot and read the PNGs (under .hyperframes/artifacts/snapshots/): that is how you see the video. With sub-compositions, snapshot a midpoint of every scene; tiny unstyled content or a missing hero is a mount defect (../hyperframes/references/format.md).
  4. npx hyperframes preview --background, check the URL answers 200, give the person the project URL and wait, unless they asked for the file or for no stops. Passing checks alone is not a reason to render.
  5. Time to render (step 4): npx hyperframes render --quality looks -o out.mp4 (draft while iterating, delivery for the final; paid plan: cloud render --fps <data-fps> --quality high -o out.mp4). Confirm the file is non-empty and its ffprobe duration matches the root data-duration, then look at decoded frames.

"This element" or the current selection: npx hyperframes preview --context --json --context-fields selection; no-selection means ask them to click it.

Edit the timeline

These are the edits Studio itself makes, so the result stays in Studio's shape.

  • timeline --json lists clips with absolute absStart/absEnd, owning file and the #id ref the edit commands take (timeline ids stamps missing ids).
  • timeline move|trim|split|set|duplicate|delete <ref> … --plan --json previews one edit; run it again without --plan. --start, --end, --duration set one edge or the length.
  • An edit is refused when the clip would overlap a neighbour (--overwrite, or move the neighbour first) or end past its composition: raise the root's data-duration first. No command changes data-duration.
  • Several edits at once: a JSON file such as [{"verb": "move", "ref": "#outro", "time": "9"}], then timeline apply plan.json --json. Each run prints a receipt; save it and timeline undo receipt.json reverts it.

Project history

Every write is kept and can be undone. At the start of a turn, npx hyperframes history begin --who <you> --label "<plan>", then history --since mine --who <you> to see what the person changed; build on their edits. A check failed or they say it got worse: history undo --who <you>, never hand-edit back. End the turn with history end.

Render where

Need Command
Local render --quality looks -o out.mp4 (draft, delivery)
Reproducible container render --docker --strict -o out.mp4
Batch from variables render --batch rows.json -o "renders/{name}.mp4"
Hosted, no local Chrome or FFmpeg cloud render (references/cloud.md)
Your own AWS or GCP lambda render, cloudrun render (references/lambda.md, references/cloudrun.md)

A 30 s film renders in a minute or two: run it in the foreground. Detach only a render longer than your tool's timeout (HYPERFRAMES_RENDER_DETACHED=1, its own group, output to a log) and wait with until grep -qE 'Render (complete|failed)' render.log; do sleep 5; done, never pgrep -f, which matches its own loop and waits until the tool times out.

After a verified render, send one feedback --rating, plus a report for anything the person asked for that HyperFrames can't do, unless telemetry is off: references/feedback.md.

When a command fails

Symptom Fix
Chrome missing or won't start npx hyperframes browser ensure; doctor --json always exits 0, gate on .ok
A heavy page isn't ready in time Raise --timeout on check or snapshot
Unusual codec looks blank Keep --proxy on (the default)
Render slow on Linux The summary's second line says screenshot + software gpu: the slow path
capture fails or writes BLOCKED.md Take nothing from its partial files; retry into a new -o folder
Disk tight clean --dry-run, then clean; never delete .hyperframes (it holds history)

References

Read the row before running its command.

Commands Read
init, capture, skills references/init-and-scaffold.md
lint, check, motion sidecars, snapshot references/lint-validate-inspect.md
compare, grade-compare, render --batch references/compare-and-batch.md
beats references/beats.md
preview, play, render, publish, Studio context references/preview-render.md
doctor, browser references/doctor-browser.md
auth, cloud, template variables references/cloud.md
lambda, cloudrun references/lambda.md, references/cloudrun.md
info, upgrade, compositions, timeline, docs, usage, telemetry references/upgrade-info-misc.md
--strict flags, run ids, clean, shader lint, JSON paths references/conventions.md
keyframes ../hyperframes/references/motion.md (Seeing motion)