docs: document the vev cmd control API
- commit
- 42775ebe43e47b7009fe6e1d9079b82dcd8bcac6
- author
- brice · · 2026-07-23 22:36 UTC
- committer
- brice · · 2026-07-23 22:36 UTC
- parent
- 8b4f298
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
2 files · +14 -2
M AGENTS.md +2 -2
| @@ -64,9 +64,9 @@ Before touching daemon teardown paths, read the lock-ordering notes at the top o | |||
| 64 | 64 | Wire payload types/codecs live in `internal/ports/frame.go` and `internal/ports/wire.go`. Connection framing lives in `internal/adapters/ipc/transport.go`. | |
| 65 | 65 | ||
| 66 | 66 | - IPC frames on a connection are 4-byte big-endian length, 1 type byte, then payload. | |
| 67 | - | - Client message types are `1–15`; server message types are `16+`. | |
| 67 | + | - Client message types currently occupy `1–12` (`MsgCommand` is `12`); server types currently occupy `16–22` (`MsgCommandResult` is `22`). The reserved bands are `1–15` and `16+` respectively. | |
| 68 | 68 | - Version negotiation requires strict equality. | |
| 69 | - | - `Hello.Version` must stay first so `PeekHelloVersion` works. | |
| 69 | + | - `Hello.Version` and `CommandRequest.Version` must stay first so their version peekers work. | |
| 70 | 70 | - Bump `ProtocolVersion` for any message layout change. | |
| 71 | 71 | ||
| 72 | 72 | ## Session flow | |
| @@ -64,9 +64,9 @@ Before touching daemon teardown paths, read the lock-ordering notes at the top o | |||||
| 64 | Wire payload types/codecs live in `internal/ports/frame.go` and `internal/ports/wire.go`. Connection framing lives in `internal/adapters/ipc/transport.go`. | 64 | Wire payload types/codecs live in `internal/ports/frame.go` and `internal/ports/wire.go`. Connection framing lives in `internal/adapters/ipc/transport.go`. | ||
| 65 | 65 | ||||
| 66 | - IPC frames on a connection are 4-byte big-endian length, 1 type byte, then payload. | 66 | - IPC frames on a connection are 4-byte big-endian length, 1 type byte, then payload. | ||
| 67 | - | - Client message types are `1–15`; server message types are `16+`. | 67 | + | - Client message types currently occupy `1–12` (`MsgCommand` is `12`); server types currently occupy `16–22` (`MsgCommandResult` is `22`). The reserved bands are `1–15` and `16+` respectively. |
| 68 | - Version negotiation requires strict equality. | 68 | - Version negotiation requires strict equality. | ||
| 69 | - | - `Hello.Version` must stay first so `PeekHelloVersion` works. | 69 | + | - `Hello.Version` and `CommandRequest.Version` must stay first so their version peekers work. |
| 70 | - Bump `ProtocolVersion` for any message layout change. | 70 | - Bump `ProtocolVersion` for any message layout change. | ||
| 71 | 71 | ||||
| 72 | ## Session flow | 72 | ## Session flow | ||
M README.md +12 -0
| @@ -40,6 +40,18 @@ vev kill <name> kill a session (--all kills everything) | |||
| 40 | 40 | ||
| 41 | 41 | The daemon starts on first use and exits with the last session. Ephemeral sessions are numbered, survive detach, and disappear with the daemon. Named sessions persist across daemon restarts and come back with their layout, scrollback, and allowlisted processes. | |
| 42 | 42 | ||
| 43 | + | ## Scripting | |
| 44 | + | ||
| 45 | + | `vev cmd` runs control commands against a running daemon; it never starts one. For example: | |
| 46 | + | ||
| 47 | + | ```sh | |
| 48 | + | vev cmd split-right | |
| 49 | + | vev cmd toast -l warn "build failed" | |
| 50 | + | vev cmd list-panes --json | |
| 51 | + | ``` | |
| 52 | + | ||
| 53 | + | Target a session explicitly with `-s` (`vev cmd -s work new-tab`). Otherwise vev uses `$VEV` inside a pane, then the only live session; ambiguous targets fail. Run `vev cmd --help` for the scriptable command list and `vev cmd <command> --help` for command usage. | |
| 54 | + | ||
| 43 | 55 | ## Keys | |
| 44 | 56 | ||
| 45 | 57 | No prefix key; everything is Alt. | |
| @@ -40,6 +40,18 @@ vev kill <name> kill a session (--all kills everything) | |||||
| 40 | 40 | ||||
| 41 | The daemon starts on first use and exits with the last session. Ephemeral sessions are numbered, survive detach, and disappear with the daemon. Named sessions persist across daemon restarts and come back with their layout, scrollback, and allowlisted processes. | 41 | The daemon starts on first use and exits with the last session. Ephemeral sessions are numbered, survive detach, and disappear with the daemon. Named sessions persist across daemon restarts and come back with their layout, scrollback, and allowlisted processes. | ||
| 42 | 42 | ||||
| 43 | + | ## Scripting | |||
| 44 | + | ||||
| 45 | + | `vev cmd` runs control commands against a running daemon; it never starts one. For example: | |||
| 46 | + | ||||
| 47 | + | ```sh | |||
| 48 | + | vev cmd split-right | |||
| 49 | + | vev cmd toast -l warn "build failed" | |||
| 50 | + | vev cmd list-panes --json | |||
| 51 | + | ``` | |||
| 52 | + | ||||
| 53 | + | Target a session explicitly with `-s` (`vev cmd -s work new-tab`). Otherwise vev uses `$VEV` inside a pane, then the only live session; ambiguous targets fail. Run `vev cmd --help` for the scriptable command list and `vev cmd <command> --help` for command usage. | |||
| 54 | + | ||||
| 43 | ## Keys | 55 | ## Keys | ||
| 44 | 56 | ||||
| 45 | No prefix key; everything is Alt. | 57 | No prefix key; everything is Alt. | ||