fix(cli): an unknown command answers in a few lines and says what to run instead by miguel-heygen · Pull Request #7247 · heygen-com/hyperframes

miguel-heygen · 2026-11-05T14:19:46Z

What

hyperframes <word> for a word that is not a command now answers in a few lines instead of printing the whole help: the suggestion, then where to list every command. hyperframes captions says there is no such command and what to run instead (transcribe, then the captions reference of the hyperframes skill).

Why

An agent looking for caption help ran hyperframes captions --help and got "Unknown command" followed by the full help text, with nothing that named the command it needed. Captions are built from a transcript, so the right answer is transcribe plus the captions reference.

Related work

Builds on the existing did-you-mean for commands (utils/didYouMean.ts); no overlapping PR.

How

COMMAND_REDIRECTS in utils/didYouMean.ts replaces the synonym table: each row is a word, the command that does that job, and an optional next step. captions is the first row with one.
The hyperframes-cli skill's line for each row with a next step is redirectLine(word); a test checks the skill contains it, so the CLI's words and the skill's cannot drift.
unknownCommandError prints the hint and Run 'hyperframes --help' to list every command.; the full usage dump is gone. When nothing is close it lists the closest commands that share a word.

Test plan

Unit tests added/updated
Manual testing performed
Documentation updated (if applicable)
Comments follow CONTRIBUTING.md "Comments"

cli.agentMode.test.ts: captions and a typo (rendr) both exit 2 with a stderr under 8 lines holding the hint and the --help pointer; didYouMean.test.ts: the skill carries the redirect line. Ran on a Linux box with the workspace built: 527 tests across the two files pass; the new CLI test fails on main (the whole help comes back).

fails without the fix: packages/cli/src/cli.agentMode.test.ts "an unknown command answers in a few lines, never the full help"

Not exercised: the installed package on Windows and the --json envelope for captions (its hint field now carries the same sentence; the existing rendr --json test still passes).

Size

94 changed lines, a lone fix: no open PR of mine in this repo can carry it, and Home asked for it as its own small PR.

…run instead

heygengenesis

Verdict: REQUEST CHANGES · 2 blockers · 0 important · 1 nit · head 3a4b5271

The behavior is right: on this head captions, captions --help and rendr each exit 2 in 3 lines, and on the merge-base captions printed 81 lines with no pointer to transcribe. The fails without the fix: line names a real test. Two required checks fail because of this diff (details inline):

Preflight lint: hyperframes-cli/SKILL.md is 7663 B, over its 7616 B budget (fails Preflight, preview-regression and both Windows lanes)
Comments: RAISED comment share: packages/cli/src/utils/didYouMean.ts is 4.7% (4/85), at the base 1.5% (1/67)

Scope

Read all 5 files end to end. Ran the CLI from source for captions, captions --help, captions --json, rendr, zzzq, catalog-foo and render-x. didYouMean.test.ts passes locally. cli.agentMode.test.ts would not load in my sandbox (a generated module was missing), so I checked its new case by running the same entry by hand. CI logs come from the Actions API. No prior reviews.

heygengenesis · 2026-11-05T14:23:21Z

 | Desktop app | `open`, `catch-up` |
 | Upkeep | `doctor`, `browser`, `upgrade`, `usage`, `clean`, `feedback` |

+`captions` is not a command: run `transcribe`, then build the caption track as the hyperframes skill's references/captions.md says.


blocker: this line takes the skill to 7663 B, over its 7616 B budget, so lint fails in Preflight. Preview-regression and both Windows lanes fail on that preflight. To fit, cut at least 47 B. One way: shorten the then text (for example then follow the hyperframes skill's references/captions.md), which shortens this line and the CLI message together. redirectLine keeps the two in sync.

✅ Fixed in b854e2e

heygengenesis · 2026-11-05T14:23:21Z

-  list: "catalog",
-  install: "add",
+/** Words an agent or person types for a job a command does, the command that does it, and what to do after it.
+ * The hyperframes-cli skill's "Not commands" line is built from the same rows (redirectLine). */


blocker: the Comments check fails. The diff adds 3 comment lines, which raises this file's comment share from 1.5% to 4.7%, and the ratchet only lets that share go down. Drop the two doc comments (this one and the one on redirectLine); COMMAND_REDIRECTS, redirectLine and the test already say what they would. This comment also points to a "Not commands" line, and SKILL.md has no line by that name.

✅ Fixed in b854e2e

heygengenesis · 2026-11-05T14:23:21Z

+  const group = ["hyperframes", ...path].join(" ");
+  const redirect = path.length === 0 ? commandRedirect(word, names) : undefined;
+  if (redirect?.then)
+    return `'${word}' is not a command. Run '${group} ${redirect.command}', ${redirect.then}.`;


nit: stderr now says the same thing twice: Unknown command: captions, then 'captions' is not a command. You could make this hint start at Run '...' instead.

✅ Fixed in b854e2e

github-actions · 2026-11-05T14:28:03Z

Edit accuracy: accurate 267 (base branch 267), smooth 122 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (8)

seqplainkeys-none-center-r0-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): fail / pass / pass, passes
seqplainkeys-none-center-r0-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
seqplainkeys-none-center-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
seqplainkeys-none-pct-r0-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): fail / pass / pass, passes
seqplainkeys-none-pct-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
seqplainkeys-none-px-r0-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): pass, passes
seqplainkeys-none-px-r30-nested-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run
seqplainkeys-none-px-r30-root-z100 (fixed by studio: undo/redo on a keyframed plain element sometimes leaves the box 230-400px off (edit-accuracy seqplainkeys-none-*) #6989): not run

…ents

heygengenesis

Verdict: REQUEST CHANGES — 3 resolved, 0 open, 1 new · 3a4b5271 → b854e2ec

The skill is 7612 B and the comment lines are gone; the preview-regression failure is an ffmpeg download 504 (infra). New blocker inline: the shortened pointer now names a file that does not exist.

heygengenesis · 2026-11-05T14:39:36Z

 | Desktop app | `open`, `catch-up` |
 | Upkeep | `doctor`, `browser`, `upgrade`, `usage`, `clean`, `feedback` |

+`captions` is not a command: run `transcribe`, then read references/captions.md.


blocker: in this skill, references/x.md means this skill's own folder (see lines 69–70, references/cloud.md). skills/hyperframes-cli/references/captions.md does not exist. The guide is skills/hyperframes/references/captions.md, which this file elsewhere cites as ../hyperframes/references/... (lines 6 and 39). An agent that follows this line, or the CLI hint built from the same then, finds no file, and that hint is the whole point of the PR. Point the then in didYouMean.ts at ../hyperframes/references/captions.md, or name the hyperframes skill as before. That adds about 14 B, so trim about 10 B elsewhere in this file to stay under 7616.

✅ Fixed in 990da64

…nd test the path exists

heygengenesis

Verdict: REQUEST CHANGES — 1 resolved, 0 open, 1 new · b854e2ec → 990da64f

The captions pointer now resolves, and the test checks that it does. New blocker: CI › Skills: manifest in sync fails with skills-manifest.json is out of date (hyperframes-cli 571fffd79a7d42f9 → 2c977e879386734b), because this PR edits skills/hyperframes-cli/SKILL.md. Run bun run --cwd packages/cli gen:skills-manifest and commit skills-manifest.json. The same --check passes on main.

…ill edit

heygengenesis

Verdict: APPROVE — 1 resolved, 0 open, 0 new · 990da64f → 5c570a27

The skills manifest is regenerated: gen-skills-manifest.ts --check passes locally, and that file is the only change in the range-diff. All workflows on this head are green.

…eview Adopts or partially adopts 11 groups: multi-worker tween replay behind the timeline stand-in (heygen-com#7231), template entries in the shared compile stage (heygen-com#7217), HYPERFRAMES_CACHE_DIR and HYPERFRAMES_CONFIG_DIR for every per-user cache and settings file (heygen-com#7224, heygen-com#7229; HeyGen credentials stay under HEYGEN_CONFIG_DIR), WebKit audio clock (heygen-com#7225), packet-based video length (heygen-com#7233), HLG tone mapping (heygen-com#7234), fetch network cause (heygen-com#7236), .hyperframesignore in lint (heygen-com#7239), info --media (heygen-com#7235), lint priority (heygen-com#7244), check --budget (heygen-com#7245) and the unknown-command answer (heygen-com#7247). bun.lock gains only the lint `ignore` edge from heygen-com#7239, already resolved. Watermark advances to 0a6746e. Co-authored-by: Jerrai <[email protected]> Co-authored-by: Miguel Ángel <[email protected]> Co-authored-by: WaterrrForever <[email protected]> Co-Authored-By: Claude Opus 5.5 <[email protected]>

fix(cli): an unknown command answers in a few lines and says what to …

3a4b527

…run instead

heygengenesis Bot requested changes Nov 5, 2026

View reviewed changes

fix(cli): shorten the captions pointer and drop the redirect doc comm…

b854e2e

…ents

heygengenesis Bot requested changes Nov 5, 2026

View reviewed changes

fix(cli): point the captions hint at the hyperframes skill's guide, a…

990da64

…nd test the path exists

heygengenesis Bot requested changes Nov 5, 2026

View reviewed changes

chore(cli): regenerate the skills manifest for the hyperframes-cli sk…

5c570a2

…ill edit

heygengenesis Bot approved these changes Nov 5, 2026

View reviewed changes

miguel-heygen added this pull request to the merge queue Nov 5, 2026

Merged via the queue into main with commit 0a6746e Nov 5, 2026
85 checks passed

miguel-heygen deleted the dharness/unknown-command-hint branch November 5, 2026 15:57

WaterrrForever mentioned this pull request Nov 9, 2026

fix(cli): measure answers the four mistakes agents make most #7443

Merged

Conversation

miguel-heygen commented Nov 5, 2026

What

Why

Related work

How

Test plan

Size

Uh oh!

heygengenesis Bot left a comment

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Nov 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Edit accuracy: accurate 267 (base branch 267), smooth 122 of those

Uh oh!

heygengenesis Bot left a comment

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot left a comment

Choose a reason for hiding this comment

Uh oh!

heygengenesis Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

github-actions Bot commented Nov 5, 2026 •

edited

Loading