On this page
On this page
CLI commands
Workboard CLI
openclaw workboard is the terminal surface for the bundled Workboard plugin. It lets an operator list cards, create a card, inspect one card, and ask the running Gateway to dispatch ready work into subagent worker runs.
Enable the plugin before using the command:
Usage
The command uses the same plugin-owned SQLite database as the dashboard and Workboard agent tools. When a local Gateway owns the state directory, commands route through that Gateway before opening the store. With the Gateway stopped, commands acquire exclusive offline ownership and close the store before releasing it. An unavailable, older, or rejecting live Gateway never triggers a local write fallback; fix its connection or stop it through its service owner and retry. Card ids are UUIDs. Commands that accept a card id also accept an unambiguous id prefix. The compact text output shows the first 8 characters.
Valid status values: triage, backlog, todo, scheduled, ready, running, review, blocked, done. Valid priority values: low, normal, high, urgent.
list
Text output is compact:
Columns are id prefix, status, priority, board id, optional agent id, and title.
An invalid --status exits with an error listing the allowed values instead of returning an empty list.
| Flag | Purpose |
|---|---|
--board <id> |
Limit results to one board namespace |
--status <status> |
Limit results to one Workboard status |
--include-archived |
Include archived cards in compact text output |
--json |
Print the full card list as machine JSON |
Compact text output hides archived cards by default so the CLI matches /workboard list. Pass --include-archived to show them. JSON output always keeps the full card list, including archived cards, for existing automation.
create
| Flag | Purpose |
|---|---|
--notes <text> |
Initial card notes |
--status <status> |
Initial status, default todo |
--priority <priority> |
Priority, default normal |
--agent <id> |
Assign the card to an agent or owner id |
--board <id> |
Store the card on a board namespace |
--labels <items> |
Comma-separated labels |
--json |
Print the created card as machine JSON |
create writes through the selected state owner. The card is immediately visible in the Control UI Workboard tab and to Workboard tools.
show
Text output prints the compact card line and notes. JSON output returns the full card record, including execution metadata, attempts, comments, links, proof, artifacts, worker logs, protocol state, diagnostics, and automation metadata.
Proof statuses in JSON are worker-reported outcomes. passed records the worker's
self-assessment of the attached command or check. It is not an independent verification
result.
move
move changes the card's status using the same manual-operator path as dragging a card in the dashboard. It accepts a full card id or an unambiguous prefix. Active dependency and schedule holds still apply. Operators may move a claimed card without its agent claim token. Claim tokens remain scoped to agent-tool mutations, and JSON output redacts them.
This command writes through the selected state owner, using Gateway RPC while the Gateway is running and exclusive offline ownership when it is stopped.
dispatch
dispatch selects the active Gateway before opening local Workboard state. Implicit local requests use the owner-bound workboard.cards.dispatch.owner RPC. That method uses the same subagent runtime as the dashboard dispatch action. Ready cards therefore become task-tracked worker runs with linked session keys. --max-starts uses workboard.cards.dispatchWithOptions.owner for the implicit local Gateway. Older Gateways or Workboard plugins without owner routing refuse before starting workers; explicit remote targets retain the existing workboard.cards.dispatch and workboard.cards.dispatchWithOptions contracts. Restart the Gateway after upgrading, before you use the flag. Cards with an assigned agent use agent-scoped subagent session keys. Unassigned cards keep an unscoped subagent key, so the Gateway's configured default agent is preserved.
The dispatch loop:
- Promotes dependency-ready children to
ready. - Blocks expired claims or timed-out worker runs.
- Selects a small batch of unclaimed ready cards.
- Claims each selected card for the dispatcher or assigned agent.
- Starts a subagent worker run with bounded card context and the card claim token.
- Stores the worker run id, session key, execution status, and worker log on the card.
Idle scans leave ready-card history unchanged. Existing dispatch counters and timestamps remain as historical values; new launches use the card's launch, attempt, and execution history.
Selection is conservative. One dispatch starts at most three workers by default. It skips archived or already-claimed cards. It starts only one card per owner or agent in a single pass. Cards already owned by active running or review work are left for a later dispatch. Pass --max-starts <count> with a positive integer to change the per-pass cap. The one-card-per-owner rule still applies, so the effective number of starts can be lower.
If worker start fails after a card is claimed, Workboard blocks that card and clears the claim. It records the failure in card execution and worker-log metadata. Failed starts stay visible instead of returning the card to the queue silently.
The CLI falls back to data-only dispatch against local Workboard state when both of these are true:
- You give no explicit Gateway target.
- The local Gateway is stopped and the CLI can acquire exclusive offline state ownership.
Data-only dispatch can still promote dependencies, clean stale claims, and block timed-out runs, but it does not start workers. A live owner that cannot be reached, lacks the required method, or rejects the request never triggers local fallback. Auth, permission, validation, and explicit-target failures are reported directly. After an uncertain reply, inspect the board before retrying.
Data-only dispatch requires the Gateway to be stopped. A connection error or missing RPC method alone does not establish that it stopped. A running Gateway does not poll for mutations made by another process.
Text output reports worker starts:
When a worker cannot start, text output also prints its card id prefix and the failure reason. JSON output includes the same reason in startFailures.
For a card already authorized for full-host workspace access, a refusal because the current caller is limited to configured workspaces includes a --admin hint. This requests operator.admin; the Gateway must approve that scope. The hint does not apply to cards with restricted, read-only, or unknown persisted workspace authority, and --admin does not override those limits.
Fallback output is explicit:
JSON output includes the dispatch result. Gateway-backed dispatch can include started and startFailures. Data-only fallback includes gatewayUnavailable: true and empty started and startFailures arrays. Claim tokens are redacted from card JSON output.
In the dashboard, the same dispatch result appears as a short summary. An operator can see how many cards started, promoted, blocked, reclaimed, or failed without opening card details.
Slash command parity
Command-capable channels can use the matching slash command:
Slash command dispatch also uses the Gateway subagent runtime. It follows the same claim, worker-start, and failure behavior as the dashboard and CLI Gateway path.
/workboard list and /workboard show are read commands for authorized command senders. /workboard create, /workboard move, and /workboard dispatch mutate board state and require owner status on chat surfaces or a Gateway client with operator.write or operator.admin.
Permissions
The CLI dispatch path normally requests Gateway operator.write and operator.read scopes. Workspace-bound cards run directly in an exact configured agent workspace. A worktree request is narrowed to that directory, so the host does not materialize repository-controlled code. The selected worker must have writable, non-shared Docker sandbox access to that exact workspace, a live container hash matching the requested mounts and policy, and no host escape capability. Pass --admin to explicitly request operator.admin, allow another host checkout, and use normal managed-worktree setup. The connection fails if that scope is not approved for the client. A read-only Gateway token can inspect Workboard data through read methods, but it cannot create cards or dispatch workers. Workspace limits do not otherwise change manual card movement for callers with Workboard mutation permission.
Local list, create, show, and move commands operate on the local OpenClaw state directory used by the current profile. Use --dev or --profile <name> on the top-level openclaw command when you need a different state root.
Troubleshooting
No cards appear
Check that the plugin is enabled for the same profile and state root:
If the dashboard shows cards but the CLI does not, check that both commands use the same --dev or --profile setting.
Dispatch says data-only
Start or restart the Gateway:
Then retry openclaw workboard dispatch. Data-only fallback is useful for local state cleanup, but worker runs need a live Gateway.
Dispatch starts nothing
Check for at least one ready card without an active claim:
Cards can also be skipped when the same owner already has running or review work. Move completed work to done, release stale claims through the Workboard tools, or run dispatch again after the active worker finishes.
