---
summary: "CLI reference for `openclaw workboard` cards, dispatch, and worker runs"
read_when:
  - You want to inspect or create Workboard cards from the terminal
  - You want to dispatch Workboard worker runs from the CLI
  - You are debugging Workboard CLI or slash command behavior
title: "Workboard CLI"
---

`openclaw workboard` is the terminal surface for the bundled
[Workboard plugin](/plugins/workboard). 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:

```bash
openclaw plugins enable workboard
openclaw gateway restart
```

## Usage

```bash
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`

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

Text output is compact:

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

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

Flags:

| Flag                | Purpose                                  |
| ------------------- | ---------------------------------------- |
| `--board <id>`      | Limit results to one board namespace     |
| `--status <status>` | Limit results to one Workboard status    |
| `--json`            | Print the full card list as machine JSON |

## `create`

```bash
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."
```

Flags:

| 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 directly to Workboard SQLite state. The card is immediately
visible in the Control UI Workboard tab and to Workboard tools.

## `show`

```bash
openclaw workboard show 7f4a2c10
openclaw 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`

```bash
openclaw workboard dispatch
openclaw workboard dispatch --json
openclaw 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:

```text
dispatch complete: started=2 failures=0
```

Fallback output is explicit:

```text
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:

```text
/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:

```bash
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:

```bash
openclaw gateway restart
openclaw 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:

```bash
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](/plugins/workboard)
- [CLI reference](/cli)
- [Slash commands](/tools/slash-commands)
- [Control UI](/web/control-ui)