Commands

Set up

pullboard tour#

see it work: a reject and its rework, scripted, in thirty seconds

pullboard init [--model <name>]#

config, SPEC.md, agent instructions, git hooks, board; optional coordinator model

pullboard worktree <lane> --model <name> [--route light] [--family <name>]#

make and join a worktree for a new agent

pullboard join <lane> --model <name> [--route light] [--family <name>]#

register this worktree as an agent A model is required (or set PULLBOARD_MODEL); family is a separate declaration

pullboard join coordinator --model <name>#

declare the main checkout's coordinator model pullboard.json agents.names: suffix (default) or prefix

pullboard whoami | lanes | status#

who you are, the lanes, the board at a glance

pullboard takeover#

rebind this checkout when the same agent starts a new session

pullboard resources#

local resource holders and their FIFO queues

pullboard settings [gateSlots <n>]#

view or set this machine's gate slots (default 2)

pullboard view [--port N] [--no-open]#

every project on this machine in your browser; default http://127.0.0.1:4890 items, shouts, doctrine, agents and activity; --port 0 chooses a free port add items, shout and hold lanes from it

pullboard view --export <dir>#

a read-only snapshot with event replay, for any static host

pullboard serve [--port N]#

local API v1: boards, state, moves, requests and live events, behind the session secret in its printed address

pullboard relay [on|off|pair|join <code>] [--url <address>]#

link, inspect or unlink this board's sealed relay on signs in through GitHub; the address defaults to https://app.pullboard.dev pair prints a one-use machine code; join stores it in another clone

pullboard relay on --all [--url <address>]#

link every registered project after one sign-in; pair the phone once keep this command open until pairing finishes; later projects link on registration

pullboard relay devices#

list paired device ids and their public-key fingerprints

pullboard relay revoke <device>#

stop future key delivery; already received keys remain known

pullboard relay tokens#

list this board's agent token ids, agents and expiry, never credentials

pullboard relay revoke <token-id>#

revoke one token from that list; other agents keep working

pullboard relay recover --skip <sequence>#

person-only recovery of one blocked next relay position

pullboard resume#

where you are: your claim, branch, uncommitted work, what came back, unread shouts, what to do next; run it to start any session

pullboard hooks#

reinstall the git hooks (e.g. after a fresh clone)

Work

pullboard add <lane> <title> [--criterion "..."] [--specs G1.2,K3] [--after 3,4] [--parent <id>][--brief "..." | --brief-file <file>] [--route light|mid]#

--after: claiming waits until those items are verified

--brief: what a cold agent needs; --route light: any model can build it

[--check "<command>"] [--wait] the command that proves it; --wait waits for its main baseline with --criterion and a brief, --check is needed below strong

pullboard edit <id> [--brief "..." | --brief-file <file>] [--route light|mid|strong] [--criterion "..."] [--check "..."]#

[--wait] wait for a new check's baseline; otherwise it runs in the background

pullboard escalate <id> --note "what was tried and how it failed"#

hand it one tier up

pullboard run --agent "<command>" [--attempts 3] [--minutes 15] [--items N] [--wait M]#

build routed items unattended in this worktree: the agent command reads the context pack at $PULLBOARD_PACK (and $PULLBOARD_CHECK, $PULLBOARD_ITEM, $PULLBOARD_ATTEMPT, $PULLBOARD_TIER); green work is submitted, red escalated

[--agent-light "..."] [--agent-mid "..."] [--agent-strong "..."] a command per tier

pullboard list [lane] [--all] [--route light|mid|strong]#

open and active items; --all adds closed ones

pullboard roadmap#

ordered milestones and each item's live status

pullboard milestone add <name> [--note ...] [--items 1,2,3]#

create a milestone and optionally add items

pullboard milestone items <name> --add|--remove ids#

append or remove item references

pullboard milestone move <name> --before <other>#

reorder a milestone

pullboard milestone edit <name> [--name <new>] [--note <text>]#

rename or update a milestone note

pullboard milestone remove <name>#

remove a milestone without changing its items

pullboard doctor#

check board integrity without changing it

pullboard skills --update#

refresh unchanged Claude Code skills from shipped versions

pullboard show <id> [--history]#

an item, the criterion frozen at claim, its verdicts: the latest in full, earlier ones as one line; --history prints every note in full

pullboard fact <id> <kind> <text> [--supersedes <fact-id>] [--ref path:lines@full-sha]#

append an observation or a holder/coordinator judgement to its thread

pullboard next [--wait <minutes>]#

offer an eligible review when reviews pile up, otherwise claim work

pullboard next --build#

claim a build explicitly, recording a skipped review offer

pullboard next --verify#

reserve the next submitted item you can check;

pullboard next --verify <id>#

reserve that submitted item instead in the main checkout, verifying needs --as coordinator

pullboard check [id] [--yes]#

show and run your item's check; --yes confirms a check set by someone else the command and its author print first; the project gate is pullboard gate

pullboard claim <id>#

take or renew a lease; the first claim freezes the criterion

pullboard release <id> [--note "why"]#

hand it back; a review release needs a one-line reason

pullboard submit <id>#

needs a clean tree, item check and affected tests green at HEAD (alias: done)

pullboard verify <id> accept --note "what you broke or which edge you tried, and what happened"#

pullboard verify <id> reject --reason TEST_FAILURE --note "what failed"#

any --note can be --note-file <file>, which keeps quotes, $ and backticks intact

pullboard shout <lane|agent|person|all> <text>#

pullboard inbox#

pullboard shout [<to>] <text> --decision#

ask for a decision; defaults to your coordinator or the person

pullboard shout <to> <text> --evidence attempt|receipt --outcome <word> --item <id> --commit <rev>#

pullboard answer <shout-id> <text> [--as person]#

answer your decision; person mode is main-checkout only

pullboard pass <shout-id> <note>#

coordinator passes a decision to the person

pullboard decisions [--as person]#

shouts waiting for you; main checkout defaults to coordinator

pullboard export#

print the whole board as versioned JSON

pullboard import <file>#

restore a versioned export into an empty board

Coordinator

pullboard sweep --run "<checker>" --check "<checker on {file}>" [--route light] [--max 20] [--dry-run]#

file one item per file a linter, type checker or test reporter flags

pullboard land [--max N] [--dry-run] [--adopt]#

gate and push a durable batch of verified items

pullboard land --waive <test> --until <date> --reason "why"#

the person records an expiring test waiver

pullboard merged <id> <commit>#

record where verified work landed

pullboard withdraw <id> <reason>#

drop an item nobody should build

pullboard refreeze <id>#

adopt a corrected criterion or changed spec rows

pullboard reopen <id> --note "why"#

return a submission for criterion correction without a verdict

pullboard hold <lane> --reason "..."#

pause a lane: next there claims nothing and names the reason

pullboard hold <id> "reason"#

hold one item so next skips it

pullboard hold <lane|id> --off#

lift a lane or item hold

Receipts

pullboard stats [--since <date>]#

proof numbers from the event log; --json for sites and tools stage averages/medians count ends inside the inclusive UTC window; build: first claim to final submit (including rework); review wait: final submit to the closing review reservation; released/expired reservations remain wait, not review; review: closing reservation to verdict; merge wait: accept to first merge unfinished stages are omitted; missing legacy reservations are unmeasured JSON flow.asOf records one observation clock; oldest.since records its origin; ageMinutes = (asOf - since) / 60000 for every queue age queues include all current work, even added before --since; open age restarts on add, reopen, reject, release or claim lapse; claimed age starts at claim (not renewal), submitted at final submit, accepted-not-merged at accept; oldest ties use the lower item id daily additions and first merges use UTC dates; repeated merge receipts count once active agents moved in the last 60 minutes (inclusive), by role and lane; role is latest role-bearing move, falling back to earlier history or unknown: claim/submit/build release = builder; reserve/verdict/review release = verifier; the coordinator is coordinator; shouts and joins never imply a role bottleneck: largest summed stage share over fully measured first-merge cycles; ties: build, review wait, review, merge wait; print fully measured/total cycles; fewer than half fully measured means low confidence; no measured cycles means no action one action, first matching rule: review wait + fewer than 1 verifier per 4 active builders: add a verifier review wait otherwise: review the oldest submission first (#N) build + more than 30% sent back: tighten criteria or briefs: N of M submissions were sent back build otherwise: add a builder in the lane with most open items (lane-name tie) review: reviews are slow (median X min): check how long the frozen checks take merge wait: land the accepted items: #A, #B when that queue is empty, the action says none waiting or waits for open work

pullboard ledger#

markdown: what was built, by whom, verified by whom

pullboard log [id]#

every move, in order

Spec

pullboard spec --json#

parsed SPEC.md and doctrine rows as JSON

pullboard forget <path>#

remove a repo from this machine's project list

pullboard spec check#

lint SPEC.md and the doctrine (house rules for agentic development)

pullboard spec view [--out file]#

the spec, open questions, sign-offs and doctrine as one page

pullboard spec show <id> | unmet [--must] | signoff <ids> [--by <principal>]#

signoff: --note "what was checked" stays with the receipt

pullboard spec draft <text> [--aim] [--gate "<gate>"]#

any agent appends a pending row; never approves it Defaults to must and gate review.

pullboard spec signers add [--key <path>] [--by <principal>]#

opt into SSH-signed sign-offs principal defaults to Git user.email; --by overrides it

pullboard spec approve <ids> | decline <ids> --reason "why"#

the person's exact-row decision approve <id> --text "new wording" approves an exact rewrite

pullboard spec apply#

coordinator applies recorded row decisions to the files

Role guides

pullboard prompt decompose|plan|signoff|review|verify#

how to do each role; Claude Code gets them as skills

Gate and hooks

pullboard gate [--landing]#

run the configured gate; prioritize a trunk landing in the machine queue

pullboard hook pre-commit|pre-merge-commit|commit-msg|pre-push#

git runs these

Lifecycle, read from src/machine.js

pullboard lifecycle#

the states, moves, guards and refusals as a markdown page, with a diagram

agent

claim, release, submit, reserve, accept, reject, escalate, refreeze (when a live claim has a pending coordinator correction)

coordinator

claim, release, submit, reserve, accept, reject, reopen, escalate, refreeze, withdraw

clock

lapse (when its lease runs out)

Reject reasons: TEST_FAILURE, BEHAVIOR_MISMATCH, INSUFFICIENT_EVIDENCE, STALE_HEAD, OTHER.

--json prints one versioned document for every command; refusals include their code and next step.

From pullboard 0.8.18.