@@ -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
4243default 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
4748payload 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
635636link you can publish to again. ` --update ` and ` --space ` both need that
636637ownership.
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
898939calls 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