Skip to content

Commit 2973b3c

Browse files
meghna810claude
andauthored
docs(cli): document open, catch-up, timeline and history (#5442)
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 #5386 Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 1577060 commit 2973b3c

1 file changed

Lines changed: 157 additions & 11 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 157 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -20,16 +20,17 @@ npm install -g hyperframes
2020

2121
## Find your command
2222

23-
| You want to | Use |
24-
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
25-
| Start a project | [`init`](#init), [`add`](#add), [`catalog`](#catalog) |
23+
| You want to | Use |
24+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
25+
| Start a project | [`init`](#init), [`add`](#add), [`catalog`](#catalog) |
2626
| Bring in source material | [`capture`](#capture), [`transcribe`](#transcribe), [`tts`](#tts), [`remove-background`](#remove-background), [`media-treatment`](#media-treatment), [`beats`](#beats), [`normalize-audio`](#normalize-audio) |
27-
| Look at it, or share it | [`preview`](#preview), [`present`](#present-and-play), [`play`](#present-and-play), [`publish`](#publish) |
28-
| Find problems | [`lint`](#lint), [`check`](#check), [`snapshot`](#snapshot), [`keyframes`](#keyframes), [`compare`](#compare-and-grade-compare), [`grade-compare`](#compare-and-grade-compare) |
29-
| Make a file | [`render`](#render), [`benchmark`](#benchmark) |
30-
| Render somewhere else | [`cloud`](#hyperframes-cloud), [`lambda`](#hyperframes-lambda), [`cloudrun`](#hyperframes-cloudrun) |
31-
| Fix your setup | [`doctor`](#doctor), [`browser`](#browser), [`upgrade`](#upgrade), [`docs`](#docs), [`info`](#info-and-compositions), [`compositions`](#info-and-compositions) |
32-
| Connect other tools | [`auth`](#hyperframes-auth), [`skills`](#skills), [`figma`](#figma-and-events), [`telemetry`](#telemetry), [`feedback`](#feedback) |
27+
| 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) |
28+
| Find problems | [`lint`](#lint), [`check`](#check), [`snapshot`](#snapshot), [`keyframes`](#keyframes), [`compare`](#compare-and-grade-compare), [`grade-compare`](#compare-and-grade-compare) |
29+
| Edit from the terminal | [`timeline`](#timeline), [`history`](#history) |
30+
| Make a file | [`render`](#render), [`benchmark`](#benchmark) |
31+
| 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) |
3334

3435
`validate`, `inspect`, and `layout` still work but are
3536
[deprecated](#deprecated-validate-inspect-and-layout). Use `check` instead.
@@ -40,8 +41,8 @@ Read this once and skip the repetition below.
4041

4142
**The project directory.** Most commands take it as the first argument and
4243
default to the current directory: `npx hyperframes check ./my-video`. A few
43-
take it as a flag instead — `add`, `transcribe`, `feedback`, and `skills` use
44-
`--dir`.
44+
take it as a flag instead — `add`, `transcribe`, `feedback`, `skills`, `history`, and
45+
the `timeline` edit commands use `--dir`.
4546

4647
**`--json` for agents and scripts.** Almost every command accepts it. The
4748
payload is wrapped with a `_meta` field so a script can spot an outdated CLI
@@ -635,6 +636,46 @@ Sign in with `npx hyperframes auth login` first when you want an owned, stable
635636
link you can publish to again. `--update` and `--space` both need that
636637
ownership.
637638

639+
### `open` and `catch-up`
640+
641+
`open` opens a project in the HyperFrames desktop app and adds it to Home.
642+
643+
```bash
644+
npx hyperframes open # the project in the current directory
645+
npx hyperframes open ./my-video
646+
npx hyperframes open --json # for agents
647+
```
648+
649+
| Flag | Description |
650+
| -------- | ------------------------------------ |
651+
| `[dir]` | Project directory (default: current) |
652+
| `--json` | Machine-readable result |
653+
654+
When it runs under Claude Code, Codex, or Grok, the app's chat picks up that
655+
conversation. When it cannot open the app, for example because the app is not
656+
installed, `open` exits 1 and prints a download link. With `--json`, the result
657+
names the `reason` and the `downloadUrl`.
658+
659+
`catch-up` is the other half of that hand-off. Run it when the person is back
660+
from the desktop app, before you change anything: it lists what they asked and
661+
what changed in the app since you last looked, and the files changed since
662+
then.
663+
664+
```bash
665+
npx hyperframes catch-up
666+
npx hyperframes catch-up ./my-video
667+
npx hyperframes catch-up --json
668+
```
669+
670+
| Flag | Description |
671+
| -------- | ------------------------------------ |
672+
| `[dir]` | Project directory (default: current) |
673+
| `--json` | Machine-readable result |
674+
675+
Each run marks what it showed as seen, so the next run lists only what is new.
676+
A project that was never handed to the app from here has nothing to catch up
677+
on.
678+
638679
## Check your work
639680

640681
### `lint`
@@ -897,6 +938,111 @@ session, and it is where new work should go. Their flags are unchanged — run
897938
`npx hyperframes inspect --help` if you are maintaining automation that still
898939
calls them.
899940

941+
## Edit from the command line
942+
943+
### `timeline`
944+
945+
Print the project's tracks and clips, or edit one clip.
946+
947+
```bash
948+
npx hyperframes timeline [dir]
949+
npx hyperframes timeline --json
950+
```
951+
952+
```
953+
timeline 10s
954+
955+
graphics (3)
956+
|████████████████████████████████████████| #title title 0-10s
957+
|████████████ | #intro intro 0-3s
958+
| ████████████ | #outro outro 5-8s
959+
```
960+
961+
| Flag | Description |
962+
| -------- | ------------------------------------------------------------- |
963+
| `[dir]` | Project directory (default: current) |
964+
| `--json` | Every track and clip with its start, duration, file and track |
965+
966+
The edit commands take a clip ref, such as `#outro`, and write the change to the
967+
file that holds the clip:
968+
969+
```bash
970+
npx hyperframes timeline move '#outro' +1 --plan # show the result and diff, write nothing
971+
npx hyperframes timeline move '#outro' after:#intro
972+
npx hyperframes timeline trim '#intro' --duration 2
973+
npx hyperframes timeline split '#outro' 6.5
974+
npx hyperframes timeline set '#music' volume=0.5
975+
npx hyperframes timeline duplicate '#intro' --at 3
976+
npx hyperframes timeline delete '#outro' --json
977+
```
978+
979+
| Command | What it does |
980+
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
981+
| `move <ref> <time>` | Start the clip at `<time>`, keeping its length |
982+
| `trim <ref>` | Change the clip's `--start`, `--end`, or `--duration` (at least one) |
983+
| `split <ref> <time>` | Cut the clip in two at `<time>` |
984+
| `delete <ref>` | Remove the clip |
985+
| `set <ref> <field>=<value>` | Set `volume`, `rate` (playback rate) or `track` (a whole number) |
986+
| `duplicate <ref>` | Copy the clip to `--at <time>` (default: right after the clip) |
987+
| `apply <file>` | Apply a JSON array of edits, such as `[{"verb": "move", "ref": "#intro", "time": "+1"}]`, all or nothing. Pass `-` to read it from stdin. |
988+
| `undo <receipt>` | Restore the files an edit changed, from its receipt (the JSON or its file) |
989+
| `ids` | Stamp stable ids on the timeline's clips |
990+
991+
A time is seconds (`4.5`), an offset from the clip's start (`+1`, `-0.5`),
992+
frames (`30f`), `end`, or an anchor on another clip: `after:#intro`,
993+
`before:#intro`, `start-of:#intro` or `end-of:#intro`.
994+
995+
| Flag | Applies to | Description |
996+
| ------------- | -------------------------------------------------------------- | ------------------------------------------------------------- |
997+
| `--plan` | `move`, `trim`, `split`, `delete`, `set`, `duplicate`, `apply` | Print the result and the diff without writing |
998+
| `--overwrite` | `move`, `trim` | Allow the clip to overlap a neighbour on its track |
999+
| `--snap` | `move`, `trim`, `split`, `duplicate` | Round times to whole frames. Needs `data-fps` on the project. |
1000+
| `--at` | `duplicate` | Where the copy starts |
1001+
| `--dir` | all edit commands | Project directory (default: current) |
1002+
| `--json` | all edit commands | Machine-readable result, with the receipt `undo` takes |
1003+
1004+
A refused edit, such as a move that would overlap a neighbour, writes nothing,
1005+
exits 2 and says how to fix it.
1006+
1007+
### `history`
1008+
1009+
List, undo and restore the project's recorded changes. Each change is an entry
1010+
with who made it, a label and the files it touched.
1011+
1012+
```bash
1013+
npx hyperframes history # newest 20 entries
1014+
npx hyperframes history --since mine --who claude # what changed since your last entry
1015+
npx hyperframes history begin --who claude --label "Bigger title"
1016+
npx hyperframes history end
1017+
npx hyperframes history undo --who claude # undo your newest turn
1018+
```
1019+
1020+
| Flag | Description |
1021+
| --------- | ------------------------------------------------- |
1022+
| `--dir` | Project directory (default: current) |
1023+
| `--json` | Machine-readable result |
1024+
| `--since` | Only entries after an entry id, a time, or `mine` |
1025+
| `--who` | Your name, for `--since mine` |
1026+
| `--limit` | Newest entries to show (default 20) |
1027+
1028+
| Command | What it does |
1029+
| ----------------------- | ------------------------------------------------------------------------------------------------------ |
1030+
| `show <ref> [--diff]` | One entry's files, before and after. `--diff` prints a text diff (needs `git`). |
1031+
| `undo [ref]` | Undo an entry, or with `--who <name>` and no ref, that name's newest turn still in effect |
1032+
| `restore <ref> [--who]` | Make the files what they were right after an entry, a time, or `start` |
1033+
| `peek <ref> [path]` | List the files at an entry, a time, or `start` without changing anything; with a path, print that file |
1034+
| `pin <ref> [--off]` | Keep an entry, and what it needs, when old history is trimmed. `--off` unpins it. |
1035+
| `begin --who --label` | Start a turn: your writes until `end` become one entry under your name |
1036+
| `end` | End your turn and print its entry |
1037+
1038+
Every command also takes `--dir` and `--json`. A ref is an entry id or a unique
1039+
prefix of one; a time is a local date or date-time such as `2026-09-24T14:30`.
1040+
1041+
When a file in the entry has changed since, `undo` writes nothing, exits 2 and
1042+
lists the newer entries. Run it again with `--just-this` to put back only that
1043+
entry's files over the newer edits, or `--back-to-before` to go back to before
1044+
it, undoing the newer entries too.
1045+
9001046
## Render to a file
9011047

9021048
### `render`

0 commit comments

Comments
 (0)