Workboard CLI Reference

openclaw workboard is the command-line interface for the included Workboard plugin. Operators can list cards, create new ones, inspect a single card, and request that the active Gateway dispatch ready work into subagent worker runs through it.

The plugin must be enabled before the command can be used:

openclaw plugins enable workboard
openclaw gateway restart

Usage

openclaw workboard list [--board <id>] [--status <status>] [--include-archived] [--json]
openclaw workboard create <title...> [--notes <text>] [--status <status>] [--priority <priority>] [--agent <id>] [--board <id>] [--labels <items>] [--json]
openclaw workboard show <id> [--json]
openclaw workboard move <id> --status <status> [--json]
openclaw workboard dispatch [--board <id>] [--max-starts <count>] [--admin] [--url <url>] [--token <token>] [--timeout <ms>] [--json]

This command accesses and modifies the same plugin-owned SQLite database that the dashboard and Workboard agent tools use. Card identifiers are UUIDs; any command that expects a card id also accepts an unambiguous prefix of the id (the compact text format displays the first 8 characters).

Acceptable status values include triage, backlog, todo, scheduled, ready, running, review, blocked, done. Acceptable priority values include low, normal, high, urgent.

`list`

openclaw workboard list
openclaw workboard list --board default --status ready
openclaw workboard list --json

Compact text is the default output format:

7f4a2c10  ready     high    default agent-a  Fix stale worker heartbeat

The columns represent id prefix, status, priority, board id, optional agent id, and title.

Flag	Purpose
`--board <id>`	Restrict results to a single board namespace
`--status <status>`	Restrict results to a single Workboard status
`--include-archived`	Show archived cards in compact text output
`--json`	Output the full card list as machine JSON

By default, compact text output hides archived cards so the CLI behaves like /workboard list. Provide --include-archived to display them. JSON output always includes the complete card list with archived cards, preserving compatibility with existing automation.

`create`

openclaw workboard create "Fix stale worker heartbeat" --priority high --labels bug,workboard
openclaw workboard create "Write Workboard docs" --status ready --agent docs-agent --board docs --notes "Cover CLI, slash command, dispatch, and SQLite state."

Flag	Purpose
`--notes <text>`	Initial notes for the card
`--status <status>`	Starting status, defaults to `todo`
`--priority <priority>`	Priority, defaults to `normal`
`--agent <id>`	Assign the card to an agent or owner id
`--board <id>`	Place the card on a board namespace
`--labels <items>`	Labels separated by commas
`--json`	Output the new card as machine JSON

create writes directly to the Workboard SQLite state. The card appears immediately in the Workboard tab of the Control UI and is accessible to Workboard tools.

`show`

openclaw workboard show 7f4a2c10
openclaw workboard show 7f4a2c10 --json

Text output shows the compact card line along with any notes. JSON output provides the full card record, including execution metadata, attempts, comments, links, proof, artifacts, worker logs, protocol state, diagnostics, and automation metadata.

Proof statuses in JSON reflect outcomes reported by workers. passed captures the worker's own evaluation of the attached command or check; it does not represent an independent verification result.

`move`

openclaw workboard move 7f4a2c10 --status review
openclaw workboard move 7f4a2c10 --status done --json

move updates the card's status through the same manual operator path used when dragging a card in the dashboard. It accepts either a full card id or an unambiguous prefix. Active dependency and schedule holds continue to apply. Operators can move a claimed card without needing its agent claim token; claim tokens remain limited to agent-tool mutations and are removed from JSON output.

`dispatch`

openclaw workboard dispatch
openclaw workboard dispatch --json
openclaw workboard dispatch --max-starts 10
openclaw workboard dispatch --admin
openclaw workboard dispatch --url http://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

dispatch begins by calling the running Gateway RPC method workboard.cards.dispatch, which uses the same subagent runtime as the dashboard dispatch action, so ready cards become task-tracked worker runs with linked session keys. --max-starts uses the additive workboard.cards.dispatchWithOptions method so an older Gateway rejects the option before starting any workers; restart the Gateway after upgrading before using the flag. Cards assigned to an agent use agent-scoped subagent session keys; unassigned cards retain 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.
Records dispatch metadata on ready cards.
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, task linkage when the Gateway task ledger reports it, execution status, and worker log on the card.

Selection is conservative: by default, one dispatch starts at most three workers, skips archived or already-claimed cards, and 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. Provide --max-starts <count> with a positive integer to change the per-pass limit; the one-card-per-owner rule still applies, so the actual number of starts may be lower.

If worker start fails after a card is claimed, Workboard blocks that card, clears the claim, and records the failure in card execution and worker-log metadata, keeping failed starts visible instead of silently returning the card to the queue.

If no explicit Gateway target is given and the local Gateway is unavailable or does not yet expose the Workboard dispatch method, the CLI falls back to data-only dispatch against local Workboard state. Data-only dispatch can still promote dependencies, clean stale claims, and block timed-out runs, but it does not start workers. Auth, permission, and validation failures, and failures for an explicit --url or --token target, are reported directly instead of triggering the fallback.

Text output reports worker starts:

dispatch complete: started=2 failures=0

Fallback output is explicit:

gateway unavailable; data dispatch only: promoted=1 blocked=0

When JSON output is returned, it contains the dispatch result. If dispatch uses the Gateway backend, the response may include started and startFailures; with data-only fallback, gatewayUnavailable: true is included instead. Claim tokens are hidden from the card JSON output.

On the dashboard, the same dispatch result appears as a brief summary. This lets an operator see how many cards were started, promoted, blocked, reclaimed, or failed without needing to open individual card details.

Slash command parity

Channels that support commands can use the corresponding slash command:

/workboard list
/workboard show 7f4a2c10
/workboard create Fix stale worker heartbeat
/workboard move 7f4a2c10 --status review
/workboard dispatch

Slash command dispatch also runs through the Gateway subagent runtime. As a result, 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 available to authorized senders. /workboard create, /workboard move, and /workboard dispatch modify board state and require owner status on chat surfaces or a Gateway client with operator.write or operator.admin.

Permissions

By default, the CLI dispatch path requests Gateway operator.write and operator.read scopes. Workspace-bound cards execute directly inside an exact configured agent workspace; a worktree request is scoped to that directory rather than allowing the host to materialize repository-controlled code. The chosen worker must have writable, non-shared Docker sandbox access to that specific workspace, a live container hash that matches the requested mounts and policy, and no ability to escape the host. Pass --admin to explicitly request operator.admin, permit 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 using read methods, but cannot create cards or dispatch workers. Workspace limits do not otherwise change manual card movement for callers who have Workboard mutation permission.

Local list, create, show, and move commands work against the local OpenClaw state directory associated with the current profile. When a different state root is needed, use --dev or --profile <name> on the top-level openclaw command.

Troubleshooting

No cards appear

Verify that the plugin is enabled for the same profile and state root:

openclaw plugins inspect workboard --runtime --json

If cards appear on the dashboard but not in the CLI, confirm that both commands use the same --dev or --profile setting.

Dispatch says data-only

Start or restart the Gateway:

openclaw gateway restart
openclaw gateway status --deep

Then retry openclaw workboard dispatch. Data-only fallback is useful for cleaning up local state, but worker runs require a live Gateway.

Dispatch starts nothing

Look for at least one ready card that has no active claim:

openclaw workboard list --status ready

Cards may also be skipped if 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.