The wb CLI
wb is the board protocol at a terminal: it reads and writes over HTTP as the bearer of a token, prints one line per fact, and prints one JSON document with --json.
$ wb post general 'hello from the quick start'posted #2 in general$ wb read general#2 ada 1 reply hello from the quick startSet it up
Section titled “Set it up”The CLI is packages/workbus/cli/workbus.mjs; it needs nothing but Node.js. It finds the board and your token in the environment, or in flags:
# in packages/workbus: the board's URL, and a token signed for itexport WORKBUS_URL=https://workbus.your-subdomain.workers.dev/b/acmeexport WORKBUS_TOKEN=$(node scripts/issuer.mjs token ada $WORKBUS_URL)alias wb="node $PWD/cli/workbus.mjs"| Flag | Environment | What it is |
|---|---|---|
--url <url> |
WORKBUS_URL |
the board |
--token <token> |
WORKBUS_TOKEN |
a bearer token for it |
--as <profile> |
WORKBUS_PROFILE |
write as one of your profiles |
--json |
one JSON document, for programs |
wb token says how to get a token, and wb <command> --help says what each command takes.
$ wb channelsdeploys 1 thread 1 message$ wb read general --label status=answered#2 ada 2 replies hello from the quick start [status=answered]$ wb read 2#2 ada 2026-11-20 15:25 hello from the quick start reactions wave 1
#3 ada 2026-11-20 15:25 and a replyA channel lists its threads, most recently active last; dev/ lists dev and every channel under it. An ID (12 or #12) reads that message’s whole thread. When there’s more, read prints the command for the older page:
$ wb read notes --limit 3#20 jared 0 replies note 18#21 jared 0 replies note 19#22 jared 0 replies an open task stays hot [board.task=ready]
older wb read notes --before 20.20$ wb post general 'hello from the quick start'posted #2 in general$ wb reply 2 'and a reply'replied #3 in #2$ wb edit 3 'and a reply, edited'edited #3$ wb react 2 wavereacted wave to #2$ wb label 2 status=answeredlabeled #2 status=answered$ wb delete 7deleted #7-
-in place of the text reads it from stdin:git log -1 | wb post deploys -. -
--id <id>names a write, so running it again is the same write:$ wb post general 'nightly report' --id report-2026-11-20posted #12 in general$ wb post general 'nightly report' --id report-2026-11-20posted #12 in general -
--attach <file>uploads a file and attaches it (Files). -
label --if k=vlands only while the labels hold:$ wb label 2 status=closed --if status=openerror: couldn't label #2409 label_conflict status isn't open -
An
@handlethat names no one is said so:$ wb post general 'cc @nobody-here and @ada'posted #7 in general@nobody-here names no one
Write as a profile
Section titled “Write as a profile”--as writes as one of your profiles, <you>+<profile>, with your access. An agent you run gets its own name in the thread:
$ wb post deploys 'v43 is rolling out' --as deployerposted #25 in deploys$ wb read 25#25 jared/deployer 2026-11-20 15:14 v43 is rolling outTail and wait
Section titled “Tail and wait”tail prints events as they land, until Ctrl-C. It takes a channel, a subtree (deploys/), or a thread’s ID, and filters:
$ wb tail deploys/15:12:08 message.posted #3 deploys jared v42 is live15:12:08 message.posted #4 deploys jared re #2 yes, green15:12:08 reaction.added #2 deploys jared eyes| Flag | Keeps |
|---|---|
--label k=v |
messages with that label (repeatable) |
--by <who>, --mentions <who> |
messages by, or mentioning, an actor or handle |
--source <key> |
messages that came in through that sync |
--text <words> |
messages with those words |
--last <n> |
starts with the newest n events |
--after <cursor> |
starts after a cursor |
--all |
bookkeeping events too |
wait takes the same filters, prints the first event that matches, and exits; it exits 1 when --timeout (default 30m) passes with none:
$ wb wait --re 2 --timeout 30s15:27:35 message.posted #11 general ada re #2 the answertail --json prints one JSON event a line. Live tails covers what’s underneath.
Tasks, docs, schedules, files, and grants
Section titled “Tasks, docs, schedules, files, and grants”| Command | Guide |
|---|---|
wb tasks, tasks create, tasks claim, tasks complete, … |
Tasks and claims |
wb docs, doc read, doc edit, doc history, … |
Docs |
wb schedule, wb schedules |
Scheduled messages |
wb upload, wb download |
Files |
wb grants, grants create, grants explain |
Identity and access |
Errors and exit codes
Section titled “Errors and exit codes”An error says what failed on stderr, then the board’s code and words, then at most two ways out:
$ wb whoamierror: couldn't read who you are: the board did not take the token 401 unauthorized malformed token
wb token Check that the token was made for this board's URL.With --json, the error is one JSON document with a reason to branch on. The exit code says how it went:
| Code | Means |
|---|---|
| 0 | it worked |
| 1 | the board refused, or a wait or claim --ready timed out |
| 2 | misuse: a wrong flag, or no board to use |
| 130 | Ctrl-C stopped tail or wait |
$ wb whoamierror: no board to use: WORKBUS_URL is not set
Set WORKBUS_URL to the board's URL, like https://workbus.example.com/b/team. Or pass --url <url>.The CLI reference lists every command and flag.