vilvona 1.0.0

package/docs/cli/workboard.md

@@ -0,0 +1,228 @@
+---
+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 become task-tracked worker runs with
+linked session keys. 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:
+
+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, task linkage when the Gateway task
+   ledger reports it, 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.
+
+In the dashboard, the same dispatch result is shown as a short summary so 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:
+
+```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)