Repository navigation
docs(cli): document open, catch-up, timeline and history - #5442
Conversation
Add the four commands that `hyperframes --help` lists but the CLI reference page left out, with their options taken from each command's args and examples checked against a sample project. Closes heygen-com#5386 Co-Authored-By: Claude Opus 5.5 <[email protected]>
|
FYI, unrelated to this PR: while running the |
jrusso1020
left a comment
jrusso1020
left a comment
There was a problem hiding this comment.
Thanks @meghna810, nice work. I checked every new claim against packages/cli/src/commands/ and found nothing wrong. The timeline sample output even matches the printer column for column. Three optional wording notes are inline.
— Rames
|
|
||
| ### `open` and `catch-up` | ||
|
|
||
| `open` opens a project in the HyperFrames desktop app and adds it to Home. |
There was a problem hiding this comment.
Worth a note: the hand-off is macOS-only for now (HANDOFF_READY = process.platform === "darwin" in utils/desktopApp.ts:27), so on Windows and Linux open always exits 1 with the download link.
|
|
||
| | Flag | Applies to | Description | | ||
| | ------------- | -------------------------------------------------------------- | ------------------------------------------------------------- | | ||
| | `--plan` | `move`, `trim`, `split`, `delete`, `set`, `duplicate`, `apply` | Print the result and the diff without writing | |
There was a problem hiding this comment.
Small nuance: apply --plan in text mode prints only planned N files. The diff shows with --json (a2Commands.ts:239-253). The single verbs print the diff as described.
| | Command | What it does | | ||
| | ----------------------- | ------------------------------------------------------------------------------------------------------ | | ||
| | `show <ref> [--diff]` | One entry's files, before and after. `--diff` prints a text diff (needs `git`). | | ||
| | `undo [ref]` | Undo an entry, or with `--who <name>` and no ref, that name's newest turn still in effect | |
There was a problem hiding this comment.
More exact: it undoes what is still in effect from that name's last recorded turn. If none of that turn is still in effect, it refuses rather than falling back to an older turn (history.ts:192-207).
|
Thanks @meghna810! I checked every flag, argument, default and exit code here against the command sources, and they match, including which
Auto-merge is on. — Rames |
…and history (heygen-com#6110) Note that the desktop hand-off in `open` is macOS-only for now, that `timeline apply --plan` prints only a count without --json, and what `history undo --who` reverts. Refs heygen-com#5386 Co-authored-by: Claude Opus 5.5 <[email protected]>
What
Adds
open,catch-up,timelineandhistoryto the CLI reference (docs/packages/cli.mdx).hyperframes --helplists all four, but the page didn't document them.Why
They only appeared in the changelog, plus a passing mention of
timelineindocs/developers/cli.mdx.Related work
Fixes #5386
How
openandcatch-up: one section under "Look at it, or share it", next topublish, since they are the two halves of the desktop-app hand-off.timelineandhistory: a new "Edit from the command line" group before "Render to a file". Both have subcommands (timeline move|trim|split|delete|set|duplicate|apply|undo|ids,history show|undo|restore|peek|pin|begin|end). Each section has a table of subcommands and a table of flags.historyand thetimelineedit commands among the commands that take--dir.Every documented option comes from the command's
argsinpackages/cli/src/commands/{open,catch-up,timeline,history}.tsand matches--help. Behaviour theargsdon't spell out (time expressions,setfields, theapplyplan shape, conflict handling onhistory undo) comes frompackages/cli/src/timeline/andhistory.ts.Two things the
argsdefine that I left out on purpose:timeline setreadsvolume,rateandtrackasfield=valuepositionals. It also checks for--volume/--rate/--track, but those aren't in itsargs, so I documented only thefield=valueform.--start,--end,--duration,--atand--snapare defined on all six clip edits, but onlytrim,duplicateand the time-taking verbs use them. The flag table lists where each one has an effect.Test plan
hyperframes initplus two extra clips) with the CLI built frommain:timeline(print,--json,movewith--plan, offset, frame andafter:anchor times, the overlap refusal (exit 2),trim,split,set,duplicate --at,delete --json, thenundowith that receipt),history(list,begin/end,--since mine --who,undo --who),open --json(app not installed: exit 1 withreasonanddownloadUrl), andcatch-up(project not handed off).npx mint validateandnpx mint broken-links --check-redirectspass (run indocs/on Node 22, as indocs.yml).bun run check:docs-snippet-motionandcheck:studio-copy-dashespass.🤖 Generated with Claude Code