Skip to content

Commit 1b1a576

Browse files
ukimsanovclaude
andauthored
docs(cli): document every command, and check it in CI (#5938)
* docs(cli): document media-use and usage commands Both command groups are registered and visible but had no section in the CLI reference. - media-use: subcommands, resolve flags, the per-type source order, where files land, which sources need a HeyGen sign-in or can cost money, and telemetry. - usage: flags, the known and unknown result shapes, which logins it reads, and that it sends no telemetry. - Add both to the "Find your command" table. The from, reuse, and params subcommands cannot take their value in this release, so the page points to the working resolve --from, --reuse, and --params forms instead. Co-Authored-By: Claude Opus 5.5 <[email protected]> * docs(cli): drop the media-use bug workaround note The bugs go to the media-use owner instead of living in the docs. Co-Authored-By: Claude Opus 5.5 <[email protected]> * docs(cli): list every command in the finder, and check it in CI A ~20-line check fails the docs workflow when a CLI command is missing from "Find your command". On main it finds media-use, usage, models, clean and events. AGENTS.md and CLAUDE.md ask agents to ship docs with the change. Co-Authored-By: Claude Opus 5.5 <[email protected]> * chore: format the docs command check --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 3dd9f51 commit 1b1a576

5 files changed

Lines changed: 189 additions & 3 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,19 @@ on:
1616
- "DOCS_GUIDELINES.md"
1717
- "packages/core/schemas/**"
1818
- "scripts/sync-schemas.ts"
19+
# A new CLI command must be listed in the docs (check-docs-cli-commands.mjs).
20+
- "packages/cli/src/cli.ts"
21+
- "scripts/check-docs-cli-commands.mjs"
1922
push:
2023
branches: [main]
2124
paths:
2225
- "docs/**"
2326
- "DOCS_GUIDELINES.md"
2427
- "packages/core/schemas/**"
2528
- "scripts/sync-schemas.ts"
29+
# A new CLI command must be listed in the docs (check-docs-cli-commands.mjs).
30+
- "packages/cli/src/cli.ts"
31+
- "scripts/check-docs-cli-commands.mjs"
2632

2733
concurrency:
2834
group: docs-${{ github.ref }}
@@ -43,6 +49,9 @@ jobs:
4349
- name: Check schema mirror (core → docs)
4450
run: npx tsx scripts/sync-schemas.ts --check
4551

52+
- name: Check every CLI command is listed in the docs
53+
run: node scripts/check-docs-cli-commands.mjs
54+
4655
- name: Validate build
4756
working-directory: docs
4857
run: npx mint validate

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@ skills/ → AI agent skill definitions
100100
- **Compositions**: HTML files with `data-*` attributes. Clips need `class="clip"`. Register one paused GSAP root timeline per composition on `window.__timelines`. Scene timelines manually added to that root must not be paused, or they will not advance when the root is seeked.
101101
- **Frame Adapters**: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.
102102
- **Deterministic rendering**: No `Date.now()`, no unseeded `Math.random()`, no render-time network fetches.
103+
- **Docs ship with the change**: a PR that adds or changes a CLI command, flag, or user-visible behavior updates `docs/` in the same PR. A new command also goes in "Find your command" in `docs/packages/cli.mdx` (CI checks it).
103104

104105
## Documentation
105106

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ skills/ → AI agent skill definitions
9898
- **Compositions**: HTML files with `data-*` attributes. Clips need `class="clip"`. Register one paused GSAP root timeline per composition on `window.__timelines`. Scene timelines manually added to that root must not be paused, or they will not advance when the root is seeked.
9999
- **Frame Adapters**: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.
100100
- **Deterministic rendering**: No `Date.now()`, no unseeded `Math.random()`, no render-time network fetches.
101+
- **Docs ship with the change**: a PR that adds or changes a CLI command, flag, or user-visible behavior updates `docs/` in the same PR. A new command also goes in "Find your command" in `docs/packages/cli.mdx` (CI checks it).
101102

102103
## Documentation
103104

‎docs/packages/cli.mdx‎

Lines changed: 153 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,14 +23,14 @@ npm install -g hyperframes
2323
| You want to | Use |
2424
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2525
| Start a project | [`init`](#init), [`add`](#add), [`catalog`](#catalog) |
26-
| Bring in source material | [`capture`](#capture), [`transcribe`](#transcribe), [`tts`](#tts), [`remove-background`](#remove-background), [`media-treatment`](#media-treatment), [`beats`](#beats), [`audio`](#audio), [`normalize-audio`](#normalize-audio) |
26+
| Bring in source material | [`capture`](#capture), [`media-use`](#media-use), [`transcribe`](#transcribe), [`tts`](#tts), [`remove-background`](#remove-background), [`media-treatment`](#media-treatment), [`beats`](#beats), [`audio`](#audio), [`normalize-audio`](#normalize-audio), [`models`](#models) |
2727
| Look at it, or share it | [`preview`](#preview), [`present`](#present-and-play), [`play`](#present-and-play), [`publish`](#publish), [`open`](#open-and-catch-up), [`catch-up`](#open-and-catch-up) |
2828
| Find problems | [`lint`](#lint), [`check`](#check), [`snapshot`](#snapshot), [`keyframes`](#keyframes), [`compare`](#compare-and-grade-compare), [`grade-compare`](#compare-and-grade-compare) |
2929
| Edit from the terminal | [`timeline`](#timeline), [`history`](#history) |
3030
| Make a file | [`render`](#render), [`benchmark`](#benchmark) |
3131
| Render somewhere else | [`cloud`](#hyperframes-cloud), [`lambda`](#hyperframes-lambda), [`cloudrun`](#hyperframes-cloudrun) |
32-
| Fix your setup | [`doctor`](#doctor), [`browser`](#browser), [`upgrade`](#upgrade), [`docs`](#docs), [`info`](#info-and-compositions), [`compositions`](#info-and-compositions) |
33-
| Connect other tools | [`auth`](#hyperframes-auth), [`skills`](#skills), [`figma`](#figma-and-events), [`telemetry`](#telemetry), [`feedback`](#feedback) |
32+
| Fix your setup | [`doctor`](#doctor), [`browser`](#browser), [`upgrade`](#upgrade), [`docs`](#docs), [`info`](#info-and-compositions), [`compositions`](#info-and-compositions), [`clean`](#clean) |
33+
| Connect other tools | [`auth`](#hyperframes-auth), [`skills`](#skills), [`usage`](#usage), [`figma`](#figma-and-events), [`events`](#figma-and-events), [`telemetry`](#telemetry), [`feedback`](#feedback) |
3434

3535
`validate`, `inspect`, and `layout` still work but are
3636
[deprecated](#deprecated-validate-inspect-and-layout). Use `check` instead.
@@ -499,6 +499,106 @@ The command writes `data-color-grading` — the same contract Studio, preview, a
499499
render all read, so the two can never disagree. It does not recognise subjects
500500
or isolate part of an image; the effect covers the whole media layer.
501501

502+
### `media-use`
503+
504+
Get the music, sound effects, images, icons, logos, voiceover, and color grades
505+
a video needs, saved as files inside the project. Every asset is recorded, so
506+
asking for the same thing again reuses the file instead of fetching it twice.
507+
The `media-use` skill drives this command; you can also run it yourself.
508+
509+
```bash
510+
# Find or make one asset and save it in the project
511+
npx hyperframes media-use resolve --type sfx --intent "whoosh"
512+
npx hyperframes media-use resolve --type logo --entity linkedin --intent "LinkedIn logo"
513+
npx hyperframes media-use resolve --type grade --intent "warm daylight" --json
514+
515+
# Look at what you already have before fetching more
516+
npx hyperframes media-use candidates --type bgm --intent "upbeat tech launch"
517+
npx hyperframes media-use resolve --type bgm --reuse 06e052c0
518+
519+
# Bring in a file you already have
520+
npx hyperframes media-use resolve --type image --from ./photo.jpg
521+
522+
# Check the setup, and see what has been used
523+
npx hyperframes media-use doctor
524+
npx hyperframes media-use stats --days 7
525+
```
526+
527+
`resolve` prints one line, such as
528+
`resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.6s)`, or the whole
529+
record with `--json`. It never edits your composition HTML; you reference the
530+
file yourself.
531+
532+
| Subcommand | What it does |
533+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
534+
| `resolve` | Find, make, or import one asset. Takes every flag below |
535+
| `candidates` | List assets already in the project and the global cache for `--type`, best match for `--intent` first. Downloads nothing and changes nothing. Same as `resolve --candidates` |
536+
| `adopt` | Record the files already in `assets/` so later requests find them, with duration and size read by `ffprobe` |
537+
| `analyze` | Measure an image or video and print suggested exposure and color corrections, saving nothing. Needs `--type grade --for <file>` |
538+
| `doctor` | Check ffmpeg, ffprobe, Node.js, the bundled sound library, and the `heygen` CLI (installed, v0.3.0 or newer, signed in). Changes nothing |
539+
| `stats` | Count requests, misses, and reuse from the project's `.media/` and the global `~/.media/` |
540+
541+
| Flag | Description |
542+
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
543+
| `--type` | Media type, from the table below. Required for every subcommand except `doctor`, `stats`, and `adopt` |
544+
| `--intent` | What you need, in plain words. For `voice` and `video` it is the text to speak |
545+
| `--entity` | A name such as a brand (`linkedin`), so a later request for the same thing reuses the file |
546+
| `--project, -p` | Project directory (default: current directory) |
547+
| `--candidates` | List reusable assets instead of resolving. `--dry-run` does the same |
548+
| `--reuse <sha>` | Copy one global-cache asset into this project, by the content hash or prefix that `candidates` prints |
549+
| `--from <file>` | Import a local file or a direct public media URL. Pages such as YouTube links are refused |
550+
| `--params <json>` | Build a LUT from explicit values, such as `'{"contrast":0.2}'`. `lut` and `grade` only |
551+
| `--for <media>` | Measure this image or video and add the suggested corrections to the grade. `grade` only |
552+
| `--analyze` | With `--type grade --for`, print the measurement and stop |
553+
| `--local-only` | Skip every network provider. Only the caches and tools installed on this machine are used |
554+
| `--provider <name>` | Use only this provider and skip reuse: for example `heygen`, `codex`, `mflux`, `kokoro`. An unknown name fails and lists valid ones |
555+
| `--voice-id` | HeyGen voice for `voice` and `video` (default: the first voice the catalog lists) |
556+
| `--avatar-id` | HeyGen avatar for `video` (default: the first public avatar) |
557+
| `--days <n>` | With `stats`, count only the last `n` days |
558+
| `--json` | Print JSON instead of one line |
559+
560+
Where each type comes from, tried in order until one succeeds:
561+
562+
| `--type` | You get | Sources |
563+
| -------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
564+
| `bgm` | Background music | HeyGen music catalog |
565+
| `sfx` | Sound effects | Openverse (CC0 or CC BY, no account), then a bundled library that works offline |
566+
| `image` | Photos and backgrounds | HeyGen asset search, then generated by mflux on this machine, then by the `codex` CLI |
567+
| `icon` | Icons | HeyGen asset search |
568+
| `logo` | Official brand marks | theSVG, then the GitHub organization avatar, then the site's favicon |
569+
| `voice` | Spoken audio of the `--intent` text | HeyGen text to speech, then Kokoro on this machine |
570+
| `video` | An avatar speaking the `--intent` text | HeyGen avatar video, then LTX on this machine when it is enabled |
571+
| `brand` | Brand colors, font, and logo | The project's own `frame.md` or `design.md`. Never the network |
572+
| `grade` | A color-grading block for `data-color-grading` | A built-in preset, a look-library LUT, or a LUT built from the words in `--intent` |
573+
| `lut` | A `.cube` LUT file | A look-library LUT, or one built from the words in `--intent` |
574+
575+
Before it fetches anything, `resolve` reuses an exact earlier match: the same
576+
`--type` and `--intent` (or `--entity`) in this project, a file in `assets/`
577+
whose name shares a word with the intent, then the same request in the global
578+
cache at `~/.media/`. `--provider` skips this. New files land in
579+
`.media/<kind>/`, are listed in `.media/manifest.jsonl` and `.media/index.md`,
580+
and are copied to `~/.media/` so other projects can reuse them. Sound effects
581+
under CC BY get their credit written to `.media/audio/sfx/CREDITS.md`.
582+
583+
**What needs an account, and what can cost money.** The HeyGen sources run
584+
through the separate `heygen` CLI, signed in with `heygen auth login --oauth`.
585+
Searching the music, image, and icon catalogs is free. Text to speech and avatar
586+
video draw on a free allowance when you are signed in with OAuth, then on your
587+
HeyGen billing, so an agent should ask before generating them. When a
588+
host app sets `HEYGEN_API_BASE` and `HEYGEN_API_KEY`, HeyGen calls go through that
589+
host instead and are charged to its key. The `codex` image fallback uses your
590+
ChatGPT subscription. Openverse, theSVG, GitHub, favicons, color grades, and the
591+
local generators cost nothing. `doctor` exits 1 only when ffmpeg, ffprobe, or the
592+
bundled sounds are missing; HeyGen problems are listed with a fix but do not fail it.
593+
594+
`media-use` sends anonymous usage events — the media type, which source won, and
595+
whether it reused a file, never your intent text or paths — and honors the same
596+
opt-outs as [`telemetry`](#telemetry).
597+
598+
See [Voice, sound, and captions](/guides/voice-and-audio) and
599+
[Color grading](/guides/color-grading) for the workflows around these assets, and
600+
[Authentication](/guides/authentication) for HeyGen credentials.
601+
502602
### `beats`
503603

504604
Find the beats in a composition's music and write them where Studio expects
@@ -1781,6 +1881,56 @@ If you called the upstream command directly instead, set it yourself:
17811881
GIT_CLONE_PROTECTION_ACTIVE=0 npx skills add heygen-com/hyperframes
17821882
```
17831883

1884+
### `usage`
1885+
1886+
See how much of your AI coding subscription is left — Claude Code, Codex, or
1887+
Grok — so an agent can size a video to the allowance before it starts. The
1888+
HyperFrames skills run it at the start of a video and again before rendering.
1889+
1890+
```bash
1891+
npx hyperframes usage
1892+
npx hyperframes usage --json
1893+
npx hyperframes usage --harness codex --json
1894+
```
1895+
1896+
| Flag | Description |
1897+
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
1898+
| `--harness` | `claude-code`, `codex`, or `grok`. Default: the agent running the command, detected from `CLAUDECODE`, `CODEX_THREAD_ID`, or `GROK_AGENT=1` |
1899+
| `--json` | Print the result as one line of JSON |
1900+
1901+
```json
1902+
{
1903+
"status": "known",
1904+
"harness": "claude-code",
1905+
"session": { "usedPercent": 42, "remainingPercent": 58, "resetsAt": "2026-10-20T18:00:00Z" },
1906+
"weekly": { "usedPercent": 20, "remainingPercent": 80, "resetsAt": "2026-10-24T09:00:00Z" },
1907+
"spend": null,
1908+
"planTier": "max"
1909+
}
1910+
```
1911+
1912+
`session` is the short window (five hours on Claude Code and Codex) and `weekly`
1913+
the weekly one; a window the plan does not have is `null`. Grok reports only
1914+
`weekly`. `spend` appears only for spend-metered Claude Code plans, such as
1915+
Enterprise: the share of the billing period's spend limit already used.
1916+
`planTier` is the subscription name when the provider gives one.
1917+
1918+
Without `--json`, a known result prints this object indented. When it cannot
1919+
tell, it says so rather than guessing: `Usage unknown (no_subscription_login).`,
1920+
or `{"status":"unknown","reason":"no_subscription_login"}` with `--json`. Other reasons include
1921+
`expired_login`, `unsupported_auth` (for example Claude Code on an API key),
1922+
`unsupported_harness`, `usage_request_failed`, and `http_<status>`. The command
1923+
exits 0 either way, so check `status`.
1924+
1925+
It reads the login your agent already has: for Claude Code the macOS keychain or
1926+
`~/.claude/.credentials.json`, for Codex `~/.codex/auth.json`, for Grok
1927+
`~/.grok/auth.json` (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `GROK_HOME`, and
1928+
`GROK_AUTH_PATH` move them).
1929+
It never refreshes or rewrites that login and never prints the token. The token
1930+
goes only to that provider's own usage endpoint. The command sends no telemetry
1931+
and skips the update check. The numbers are a snapshot: they do not reserve
1932+
allowance or estimate what the next video will cost.
1933+
17841934
### `figma` and `events`
17851935

17861936
`npx hyperframes figma` imports through the Figma REST API, with three

0 commit comments

Comments
 (0)