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:

openclaw plugins enable workboardopenclaw gateway restart

Usage

openclaw workboard list [--board <id>] [--status <status>] [--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 dispatch [--url <url>] [--token <token>] [--timeout <ms>] [--json]

The command reads and writes the same plugin-owned SQLite database used by the dashboard and Workboard agent tools. Card ids can be passed by full id or by an unambiguous prefix when a command accepts a card id.

list

openclaw workboard listopenclaw workboard list --board default --status readyopenclaw workboard list --json

Text output is compact:

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

Columns are id prefix, status, priority, board id, optional agent id, and title.

Flags:

create

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

Flags:

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

show

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

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.

dispatch

openclaw workboard dispatchopenclaw workboard dispatch --jsonopenclaw workboard dispatch --url http://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

dispatch first calls the running Gateway RPC method workboard.cards.dispatch. That path uses the same subagent runtime as the dashboard dispatch action, so ready cards can become real worker sessions.

The dispatch loop:

1. Promotes dependency-ready children to ready.
2. Blocks expired claims or timed-out worker runs.
3. Records dispatch metadata on ready cards.
4. Selects a small batch of unclaimed ready cards.
5. Claims each selected card for the dispatcher or assigned agent.
6. Starts a subagent worker run with bounded card context and the card claim token.
7. Stores the worker run id, session key, execution status, and worker log on the card.

Selection is intentionally conservative. One dispatch starts at most three workers by default, 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.

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. This keeps failed starts visible instead of silently returning the card to the queue.

If no explicit Gateway target is provided and the local Gateway is unavailable or does not expose the Workboard dispatch method yet, 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, validation failures, and failures for an explicit --url or --token target are reported directly.

Text output reports worker starts:

dispatch complete: started=2 failures=0

Fallback output is explicit:

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

JSON output includes the dispatch result. Gateway-backed dispatch can include started and startFailures; data-only fallback includes gatewayUnavailable: true. Claim tokens are redacted from card JSON output.

Slash Command Parity

Command-capable channels can use the matching slash command:

/workboard list/workboard show 7f4a2c10/workboard create Fix stale worker heartbeat/workboard dispatch

Slash command dispatch also uses the Gateway subagent runtime, so 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 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 calls Gateway RPC with operator.read and operator.write scopes. A read-only Gateway token can inspect Workboard data through read methods, but it cannot create cards or dispatch workers.

Local list, create, and show 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

Confirm the plugin is enabled for the same profile and state root:

openclaw plugins inspect workboard --runtime --json

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:

openclaw gateway restartopenclaw gateway status --deep

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:

openclaw workboard list --status ready

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.

Related

• Workboard plugin
• CLI reference
• Slash commands
• Control UI