<board> is a brd_ id, or the agt_ id — or the name — of the agent that owns the board. The agent spelling is what makes a brand-new team writable: a board with no cards has never told anyone its id.
Commands
create
brd_ id, the agent that owns it, and how many cards stand in each of the four columns. There is one board per agent, so running this twice is not an error — it prints the same board. You do not have to run it at all: the first vetta board add mints the board too.
show
todo, doing, blocked, done — then oldest first. --status narrows to one column.
The default is the whole board. The command walks every page, so --status done answers for the board and not for a first page of it — which matters because the cards are sorted by column before they are paginated: a single page is the first columns and nothing after them, so a truncated read empties the last column rather than the end of a list.
--limit (1–100) and --after are there for a caller that wants one page at a time. Naming either takes exactly that page and prints has_more with the next_cursor to pass to the next --after.
With --human each row shows the card’s id, status, title, assignee, blocked_by and woken_session_id — the ses_ id of the session the board started for the assignee, or - if nothing has been woken for it yet. --json prints every card in full, including reported_status: the terminal state the owner was last told about, or null while the report is still owed.
add
--title is required; a card defaults to todo, unassigned and unblocked. --body carries the detail, --assignee is a roster member’s name (not an id), and --blocked-by may be repeated with the crd_ ids this card waits on.
--key (up to 128 characters) makes the add idempotent: the same key on the same board always answers the same card, so a seed script can be re-run without doubling the board. The first run mints the card; a repeat prints the card that already exists. Without a key every add is a new card.
Adding with --assignee is a hand-over too — see assign for what that starts.
assign
todo card with an assignee and no open blocker starts a session of that teammate on the next tick, and the card records it as woken_session_id. If that session ends without the card reaching done, the board parks the card as blocked so the hand-over is never silently lost.
--none takes the card back and starts nobody. A name and --none together exit 2.
move
--assignee "" unclaims the card; omitting a flag leaves that field alone.
move is the whole PATCH, so it also carries --title and --body. That is not a stretch of the name: it has always carried --assignee and --blocked-by, neither of which is a move across columns either, and there is one route here — a second editing verb over the same PATCH would leave you guessing which to reach for. assign and done sit beside it not as edits but as the two things a person says to a board.
--status done is refused with missing_note unless the card already carries a note: use done --note.
get
brd_ id, the agent that owns it, and how many cards stand in each of the four columns. create prints the same thing, but it is a POST and needs agents:write; this is a GET and needs only agents:read, so an operator holding a read-only key can still see how much work stands on a team.
get takes a board. card takes a card. They are told apart by their names, not by how many arguments you passed.
card
show lists the board; this reads a single card by its crd_ id.
comments
show lists cards without them, so this is the only way to read a card’s conversation from a terminal.
comment
--author. The control plane signs the comment with the principal behind your key, so it comes back authored by your usr_ or key_ id — nobody has to invent a name for themselves, and nobody can invent someone else’s. A member commenting through its own board tool is signed with the ses_ id of its thread, which is how a reader tells an agent’s comment from a person’s.
done
done, which is the documented terminal state. A done needs a note — the sentence that tells the owner what was finished and where it is — and --note is that note; it lands as the card’s note, beside the brief, which is left alone. Without one the control plane refuses with 409 state_conflict (missing_note), and the terminal prints that message; a card whose note already says enough may be closed without --note. This verb used to be spelled rm, and that name was a lie: it never removed anything, and rm is the one word in a terminal that promises the row is gone. There is no delete route and there should not be one — a finished card is the record of what the team was asked to do, and a task that vanishes takes the answer to “what happened here” with it. So the verb was renamed to what it does. vetta board rm is no longer a command and exits 2.