notebook

# Notebook canvas CLI `notebook` is a CLI over a running notedeck's embedded relay. It keeps its **own** nostrdb cache, reconciles with the relay each run (NIP-77 negentropy, falling back to NIP-01, or fully offline against the cache), folds the canvas locally with the same reducer the egui app uses, and forwards edits back so the running app sees them. Source: `crates/notebook_cli`; the cache/sync/relay/key plumbing is shared with `headway` via `crates/relay_sync`. ## Running it Prefer a built binary; fall back to cargo: ```bash # build once, then call the binary directly (fast, no rebuild per command) cargo build -p notebook_cli # produces target/debug/notebook target/debug/notebook <command> # or, one-off: cargo run -q -p notebook_cli -- <command> ``` In examples below, `notebook` means whichever form you're using. ## Logging in The CLI reads and writes **your own** canvas once you're logged in. The author whose canvas is loaded comes from `--author <pk>`, else the signing key's own pubkey — so to read or edit without `--author` you need a key configured. Relay defaults to `ws://127.0.0.1:6677` (notedeck's embedded relay); override with `--relay <url>` or `$NOTEBOOK_RELAY`. If no relay answers, the CLI works offline against its cache and edits reach the app on the next connected run. If a command fails because no key is configured (`need --nsec to sign, or --author to read a canvas`), ask the user to run `notebook login`. Don't handle the key yourself. ## The golden rule: `show` before you edit Each node has a friendly **reference** — the `notebook:` scheme then three BIP-39 words encoding the leading bits of its event id, e.g. `notebook:maple-river-canyon`. It's a sayable rendering of the node's real identity (its 64-char nostr event id), the notebook sibling of headway's `headway:<board>/…` cards — single-segment (no canvas), because a node's identity is its event id, not the canvas it happens to sit on. `show` prints it muted at the end of each node line; quote it in chat or commits, and pass it back to any command that takes a `<node>`. A `<node>` argument resolves, in order, as: - the full 64-char **hex id**, or any unique **hex prefix** — canonical, best for scripted edits where you've pulled the id from `show --json` - a **`notebook:<word-id>` reference**, e.g. `notebook:maple-river-canyon`. The `notebook:` scheme is required — a bare `maple-river-canyon` is not a reference and won't resolve. Edges are addressed by their **edge id** (`<from-hex>-<to-hex>`, shown muted by `show`) or a unique prefix. Always run `show` first to read the current ids, then act on what you actually see — never assume an id or that a node is where you expect. ```bash notebook show # human-readable: title, nodes, edges, pending notebook show --json # machine-readable, for parsing (each node has `id` + `ref`) notebook show <node>... # print only the given nodes (hex id, notebook:<word-id>, or prefix) notebook show <node> --json ``` `show` prints the canvas title (with `[open]` if open), then each node as `<first line of text> (x,y w×h) notebook:<word-id>` with the geometry and reference muted, then edges as `<from-ref> → <to-ref> <edge-id>`, then any **pending** nodes (proposals on a closed canvas). If there's no canvas yet it tells you to run `notebook seed`; with `--json` it prints `null`. If a selector doesn't resolve, errors are explicit: an ambiguous prefix says `ambiguous node prefix` / `ambiguous edge prefix`, an unknown one `no node matching` / `no edge matching` — re-read `show` and retry with a longer prefix, the `notebook:<word-id>` reference, or the full id. **Which form to use:** refer to a node by its **`notebook:<word-id>` reference** when talking to a human (it's sayable, they'll recognise it, and it renders as a live inline chip in notes/chat). When *you* script an edit, the hex id from `show --json` is canonical and can never be ambiguous; the reference resolves too and is fine for one-offs. ## Commands | Command | What it does | | --- | --- | | `show [nodes...] [--json]` | Print the canvas, or only the given nodes | | `seed [title...]` | Create the canvas if none exists (default title `Notebook`) | | `add <text...> [-x -y -w --height]` | Add a text node, optionally placed/sized | | `move <node> [-x -y -w --height]` | Move/resize a node (unset fields keep current geometry) | | `edit <node> <text...>` | Replace a node's text | | `color <node> [color]` | Recolor a node (`none`/`-`/empty clears; `--color` also works) | | `restack <node> <index>` | Restack a node to a display index (`0` = bottom) | | `delete <node>` | Remove a node (reversible tombstone) | | `connect <from> <to> [--from-side <s>] [--to-side <s>]` | Draw an edge between two nodes | | `disconnect <edge>` | Remove an edge (id from `show`) | | `rename <title...>` | Rename the canvas | | `login <nsec>` | Store a signing key so later runs just work | | `logout` | Forget the stored signing key | `show`, `seed`, `login`, and `logout` aside, every command edits the canvas and needs a signing key. Re-drawing the same `connect <from> <to>` updates that edge rather than stacking a duplicate (edge ids are stable per ordered pair, latest-wins). ### Geometry flags `add` and `move` take geometry in canvas pixels: `-x`/`--x`, `-y`/`--y` for position and `-w`/`--w`, `--height` for size (height has no `-h` short — that's `--help`). `add` fills any unset field from defaults (a new text node is `250×120` at the origin); `move` fills unset fields from the node's current geometry, so `move <node> -x 400` slides it horizontally without touching its size or `y`. ```bash notebook add "ship the thing" -x 100 -y 200 # new node at (100,200) notebook move 1a2b3c4d -x 400 -y 50 # reposition, keep size ``` Other flags: `--author <pk>` (read someone else's canvas), `--canvas <id>` (non-default canvas, default `notebook`), `--db <path>` (cache dir), `--nsec <nsec>` (key for this run; `$NOTEBOOK_NSEC` takes precedence over the stored key), `-h`/`--help`. ## Typical workflow Add a node, then connect it to an existing one: ```bash notebook show # read the canvas + word-ids notebook add "new idea" -x 300 -y 100 # create the node notebook show # read back both word-ids notebook connect maple-river-canyon glide-amber-mesa # draw an edge between them notebook show # verify the edge landed ``` For scripted edits where ambiguity must be impossible, pull the hex `id` from `notebook show --json` and pass that instead of the word-id. ## Notes - Edits print `ok (N events)`; offline edits append `— offline, not forwarded to the app`, meaning they're cached but haven't reached the running notedeck yet. `seed` prints `seeded canvas '<id>' (N events)`. - `seed` errors if a canvas already exists; that's expected — just `show` instead. An edit that resolves to no change prints `action produced no events (unknown node or edge?)`. - The cache lives at `<data-dir>/notebook-cli` unless `--db` overrides it. The CLI and the running app converge through the relay, so either side's edits show up on the other after a reconcile. </content> </invoke>