headway

# Headway board CLI `headway` 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 board locally, and forwards edits back so the running app sees them. Source: `crates/headway_cli`. ## 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 headway_cli # produces target/debug/headway target/debug/headway <command> # or, one-off: cargo run -q -p headway_cli -- <command> ``` In examples below, `headway` means whichever form you're using. ## Logging in Everything operates on your own board once you're logged in — `show` to read, the rest to edit. Relay defaults to `ws://127.0.0.1:6677` (notedeck's embedded relay); override with `--relay <url>` or `HEADWAY_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 you're not logged in, ask the user to run `headway login`. Don't handle the key yourself. ## Multiple boards A board is identified by a slug scoped to your key, so one identity can hold several boards (e.g. a personal `headway` board and a `work` board). **Always target a non-default board with the per-run `--board <id>` flag — never the stateful `headway board <id>` switch.** Pass `--board <id>` on *every* command in a sequence, so each call is self-contained: ```bash headway --board work show headway --board work add "Fix the relay reconnect" --col todo -l bug headway --board work move 1a2b3c4d… --col done ``` Why avoid the stateful switch: `headway board <id>` persists the selection to a file (`<data-dir>/headway-cli/board`) that is **shared mutable state**. The running notedeck app — or any other `headway` process — can flip it between your commands, so a `show` that targeted `work` can be followed by an edit that silently lands on `headway` (you'll see a confusing "no card matching" when the card "vanishes"). The `--board` flag is scoped to one run and can't be changed underneath you, so a multi-step edit always hits the board you meant. Board selection precedence, highest first: the `--board <id>` flag (one run only) → the board named by a `headway:<board>/<word-id>` card ref (see below) → `$HEADWAY_BOARD` → the board stored by `headway board <id>` → the default `headway`. If you're acting on many boards in one session, prefer `--board`; only fall back to `$HEADWAY_BOARD` (an env var, also stable for the session) when you truly want every command to default to the same non-default board. **Full card refs self-route.** A selector like `headway:commerce/purse-metal-toilet` already names its board, so `headway show headway:commerce/purse-metal-toilet` (and `move`, `comment`, …) targets `commerce` automatically — no `--board` needed. The `headway:<board>/<word-id>` that `show` prints is a working address wherever you paste it, which gives you the same self-contained, un-raceable targeting that `--board` does — prefer either over relying on the stateful switch. The scheme-less shorthand `commerce/purse-metal-toilet` self-routes too, and hex prefixes resolve against the current board (so they still need `--board` to reach another one). A **bare word-id** (`purse-metal-toilet`, no board segment) is no longer a card ref — it won't resolve; always include the board. Two refs naming different boards in one command — or a ref that disagrees with an explicit `--board` — are an error, not a silent resolution on the wrong board. `headway board` with **no argument** is a harmless read — it lists the boards in the cache and marks the current one with `*`; use it to discover slugs. Just don't rely on its persisted `*` selection for edits. To create a board that doesn't exist yet, `headway --board work seed`. ## The golden rule: `show` before you edit Cards are addressed by their **event id**, and columns by **id or case-insensitive name**. When scripting the CLI, pass a hex `id` from `show --json`. Any unique prefix resolves, so the full 64-char id is overkill — a **16-char (8-byte) prefix** is plenty for a board with a handful of cards, and even an 8-char prefix is usually unambiguous. Use a short prefix for automated edits; just lengthen it (or fall back to the full id) if you ever hit an "ambiguous card prefix" error. The human-readable `show` instead displays a muted **reference** like `headway:headway/maple-river-canyon` (a friendly rendering of that same event id, for quoting in commits/chat); it also resolves as a `<card>` argument, but prefer the hex id for automated edits. Always run `show` first to read the current ids and column names, then act on what you actually see — never assume an id or that a card is where you expect. ```bash headway show # human-readable: columns, titles, labels, word-ids headway show --archived # also list archived cards in full (default: count only) headway show --all # every board in the cache, each printed in full and led # by its slug (with --json, a JSON array of boards) headway show --json # machine-readable, for parsing (always includes archived) headway show <card>... # print the given cards (word-id or hex) in full # `git show`-style detail, not the whole board; with # --json each card gains a `column` field for the column # it sits in ``` By default `show` collapses archived cards to a one-line count to keep the board readable; pass `--archived` to list them (e.g. to find an id for `restore`). `show` prints each card as `<title> [labels] headway:<board>/<word-id>`, with the reference muted at the end of the line. **Which form to use — MANDATORY when talking to a human** (chat, a commit message, a PR, a board comment): refer to every card by its **full scheme reference**, `headway:<board>/<word-id>` — the exact string `show` prints, scheme *and* board included (`headway:dave/maple-river-canyon`; a notebook node is `notebook:mango-sibling-false`). This is the **only** form the user's client parses into a live link/chip. Any other form renders as dead text, so it is never acceptable in human-facing prose. Do **not** use, ever, when addressing a human: - `headway#maple-river-canyon` or `dave#maple-river-canyon` — the `#`/hash form does **not** linkify. This is the most common mistake; there is no `#` in a Headway reference. - a bare `maple-river-canyon` (no scheme, no board) — doesn't resolve at all. - the scheme-less `dave/maple-river-canyon` — fine as a CLI argument, but it does **not** linkify in prose; always add the `headway:`/`notebook:` scheme when writing for a human. The full `headway:<board>/<word-id>` is also self-routing and unambiguous no matter which board is current when it's read. Apply this to **every** ref in a message, not just the first — a comment that names five cards writes all five as full scheme references. When *you* edit the board (move, label, archive, …), pass the canonical **hex id** from `show --json` instead, so an automated edit can never hit the wrong card. All of these resolve as a `<card>` argument, to the same card every time: - a hex event id, full or any unique prefix (a 16-char prefix is plenty) — preferred for editing - `headway:dave/maple-river-canyon` — the full reference; it names its board, so it self-routes there without `--board` (see Multiple boards) - `dave/maple-river-canyon` — the scheme-less shorthand; self-routes too. A bare `maple-river-canyon` with no board segment is **not** a card ref and won't resolve. Default board columns: **Backlog**, **Todo**, **In Progress** (`in-progress`), **In Review** (`in-review`), **Done** (`done`). A column argument matches an id or a name case-insensitively, so `--col "in progress"`, `--col in-progress`, and `--col "In Progress"` are equivalent. ## Commands | Command | What it does | | --- | --- | | `show [cards...] [--archived] [--all] [--json]` | Print the board, or only the given cards (`--archived` lists archived cards; `--all` prints every board) | | `seed` | Create the default board if none exists | | `add <title...> [--col <c>] [-l <labels>] [--parent <card>] [--desc <text>\|--desc-file <path>]` | Add a card (defaults to the first column; `-l`/`--label` tags it; `--parent` creates it as a subissue; `--desc`/`--desc-file` sets its description at creation) | | `move <card> --col <c> [--row <n>]` | Move a card to a column (optional position) | | `title <card> <title...>` | Edit a card's title | | `desc <card> <text...>` | Edit a card's description | | `label <card> [labels...]` | Set labels — positional, comma-separated, or `-l` (no labels clears them) | | `priority <card> <level>` | Set priority: `none`/`low`/`medium`/`high`/`urgent` (`none` clears it) | | `parent <card> [parent]` | Make a card a subissue of `[parent]`; omit the parent to detach | | `block <card> --on <other>` | Mark `<card>` as blocked by `<other>` (see Dependencies) | | `unblock <card> --on <other>` | Remove the `<card>`-blocked-by-`<other>` edge | | `relate <card> --to <other>` | Relate two cards (an undirected "see also"; see Dependencies) | | `unrelate <card> --to <other>` | Remove the relation (from either endpoint) | | `due <card> <date>` | Set a due date (`YYYY-MM-DD`, or `none` to clear) | | `estimate <card> <n>` | Set an estimate — a number (or `none` to clear) | | `seq <card> <pos> [--in <c>]` | Position a card in a container's work-order (see Work order) | | `next [--in <c>] [--ready] [-n <k>]` | Print the ready frontier — what to work on next (see Work order) | | `comment <card> <text...> [--reply-to <c>]` | Comment on a card (NIP-22); `--reply-to` threads under another comment | | `delete <card>` | Remove a card (reversible tombstone) | | `archive <card>` | Archive a card off the board | | `restore <card>` | Restore an archived card | | `link <card> --to <board>` | Also place the card on another board (it stays on this one) | | `move-board <card> --to <board>` | Move the card off this board onto another | | `board [id]` | Switch the current board to `id`, or (no arg) list boards and mark the current one | | `rename <title...>` | Rename the current board's display title (slug unchanged) | | `login <nsec>` | Store a signing key so later runs just work | | `logout` | Forget the stored signing key | `add` accepts `-l`/`--label` to tag the new card in one step. The flag is repeatable and each value may be comma-separated, so `-l a,b --label c` and `-l a -l b -l c` are equivalent: ```bash headway add "Fix the relay reconnect" --col todo -l bug,p1 ``` `label <card>` takes the same spellings — separate positionals, one comma-separated positional, or the `-l`/`--label` flag — so these all set the same two labels. Note it *replaces* the card's set rather than adding to it, and `label <card>` with no labels at all is what clears: ```bash headway label 1a2b3c4d… bug p1 headway label 1a2b3c4d… bug,p1 headway label 1a2b3c4d… -l bug,p1 headway label 1a2b3c4d… # clears ``` `add` can also set the new card's description at creation, saving a follow-up `headway desc <card> …` (and the need to learn the new card's id first). `--desc <text>` takes the description inline; `--desc-file <path>` reads it from a file, or from stdin when `<path>` is `-`, so a long multi-line markdown description can heredoc in with no shell-escaping. The two are mutually exclusive and trailing whitespace is trimmed (so a heredoc's closing newline doesn't ride along). Both compose with `--col`/`-l`/`--parent`: ```bash headway add "Rework the sync engine" --col todo --desc "Backfill stalls past the maxSyncEvents cap." headway add "Migration plan" --col todo --desc-file - <<'EOF' ## Migration plan 1. Fork the session loop 2. Retire the per-app poller EOF ``` Other flags: `--board <id>` (target another board for one run; see Multiple boards), `--db <path>` (cache dir), `--author <pk>` (read someone else's board), `-h`/`--help`. `--on <card>` names the blocker for `block`/`unblock`; `--to` is the target board for `link`/`move-board` and the partner card for `relate`/`unrelate`; `--in <c>` is the container for `seq`/`next`. When commenting a finished card's commit hash, a Dave agentic session should also quote its own `agentium:` session ref (from `$AGENTIUM_SESSION`) beside the hash — see AGENTS.md "When done with the work" and the `agentium` skill. ## Subissues A card can be a **subissue** of one parent card (GitHub sub-issue semantics: one parent per child, any number of children per parent). Use this instead of the old hand-maintained epic pattern — an `epic` label plus a word-id checklist in the description — whenever work breaks down into trackable pieces: the rollup is derived from the board, so it can never go stale. ```bash headway add "wire up the parser" --col todo --parent <epic> # create as a subissue headway parent <card> <epic> # make an existing card a subissue (or re-parent) headway parent <card> # omit the parent to detach ``` Progress is **positional, not stored**: a child counts as done when it sits in the last column of its board (Done on the default board), or is archived. There is no checkbox to tick — moving the child card *is* the progress update. How it renders: - The board listing (`show`) marks parent cards with a dim `n/m` rollup. - Card detail (`show <epic>`) gains a `subissue of` line on children and a derived checklist on parents: ``` subissues (2/4 done) [x] route media loads through imgproxy headway:headway/mushroom-include-wolf [ ] cap media cache size with eviction headway:headway/extend-decrease-visit ``` - `show --json` gains `parent` (hex), `parent_ref` (a full `headway:<board>/<word-id>`), and `subissues` per card. Notes: re-parenting that would create a cycle is refused; children may live on a different board than the parent; nesting works (a child can itself be a parent) but each rollup counts direct children only. ## Work order: what to do next (`next` and `seq`) Beyond columns and subissues a board carries a **work-order** — a deliberate sequence over cards that answers "what should I pick up next?". Two commands read and write it: - `headway next` prints the **ready frontier**: the cards workable *right now*, in work-order. `next` alone prints just the first (the single best next thing); `next --ready` prints the whole frontier; `next -n <k>` caps it at `k`. More than one card can be ready at once — that's the parallel-dispatch signal