Command reference

plotwork board watch

Print each change to a board, or one tab, as it happens; Ctrl-C stops it. It is a command of the Plotwork command line, the npm package @buun_group/plotwork.

TL;DR

Question	Answer
What does it do?	Print each change to a board, or one tab, as it happens; Ctrl-C stops it.
How do I run it?	`npx -y @buun_group/plotwork@0.2.0 board watch`, or `plotwork board watch` once the package is installed.
What does it write?	Nothing on this machine.
Does it use the network?	Yes: calls to the Plotwork API with the key in `PLOTWORK_API_KEY`, which is never printed.
Does it read the repository settings?	No.
How do I read this in a terminal?	`plotwork board watch --help`

Synopsis

plotwork board watch <board> [<tab>] [--interval <seconds>] [--idle <minutes>] [--json]

What it does

Polls as an agent does: there is no socket in the command line. Each round asks the API's index whether the board changed, which does not wake the board, and reads what changed only when it did. The wait starts at --interval, doubles while nothing changes, up to 120 seconds, and drops back after a change. It stops by itself after --idle quiet minutes, and gives up after 5 failed rounds in a row.

With --json it prints one JSON object a line: watching, then a change for each version (with who made it and what it counted), tab.added, tab.removed, retry, and stopped.

A board is named by its id, its address in the portal (an address with #tab-<id> also names the tab), or its name; a tab by its id or its name. A name costs one more call to look it up.

Options

Option	Default	What it does
`--interval <seconds>`	15	The first wait between rounds, at least 5. Each round is a call that counts against the key's daily calls.
`--idle <minutes>`	30	Stop after this many minutes with no change.
`--json`	Off	Print one JSON document: the API's answer when it worked, or `{ "error": true, "errorCode", "message", "hint", "status" }` when it did not.

Examples

Print every change to every tab.

plotwork board watch Checkout

One tab, as a JSON line per change.

plotwork board watch Checkout Payments --json

Exit codes

Code	When
`0`	It stopped by Ctrl-C or after the idle minutes.
`1`	The API refused the call (its code, words and a hint are printed), or could not be reached.
`2`	A mistake in the command line: an unknown option, a missing operand, a file or glob that matches nothing, or a settings file that cannot be read. Also when `PLOTWORK_API_KEY` is missing or refused.

Doc	Why
Command reference	Every command of the command line
Live whiteboards	Boards, tabs, revisions and who may change them
From the command line	Signing in, pull and push, conflicts, and watch
Claude Code plugin	The board and board-sync skills
Exit codes and output formats	What every code and format means