CLI for the agent

The CLI is the agent’s control surface. Humans normally speak intent in chat; the agent translates it into these commands. You do not need to memorize them to use mdBoard.

This page documents the 1.0 named-action surface.

Global options

--root <PATH>   Board root containing mdboard.toml (default: .)
--json          Machine-readable output where supported
--actor <ID>    Actor id; roles come from .mdboard/actors.toml

A mutating command requires an actor. The agent usually runs as --actor agent.

Authority flags

Card-level human gates support:

--authorised-by <ACTOR>     Human who authorised the action
--authorization <TEXT>     The human's statement, recorded in the event

The agent supplies both when executing a human-authorised action. The event records executor=agent and authorised_by=<human>. Branch merges and releases do not accept these flags for the agent; only the human owner executes them.

Initialize and serve

Command	Purpose
`mdboard init [DIR] [--force] [--upstream BRANCH] [--roadmap-limit N] [--subscription NAME] [--eur-per-million-tokens VALUE] [--init-git]`	Create the board and write the initial configuration.
`mdboard serve [--host H] [--port P] [--open] [--no-watch] [--actor A]`	HTML board and JSON API; writes require an actor.
`mdboard watch`	Rebuild views and the HTML site on changes.
`mdboard schema`	Machine-readable kinds, states and transitions.

Orientation

Command	Purpose
`mdboard runbook`	Print the normative agent instructions.
`mdboard context`	Board state: iteration, active batch, roadmap, meetings, blocked/error.
`mdboard brief`	Human-readable summary after a change.
`mdboard actions <ID>`	Legal actions for the card, actor and state.
`mdboard history <ID>`	Event timeline for one card.
`mdboard commit -m "…"`	Stage everything and commit; enforces the open iteration and writer lease.
`mdboard status`	Short board summary.
`mdboard check [--git]`	Validate invariants.
`mdboard render [--check]`	Write or compare `BOARD.md` and `ROADMAP.md`.
`mdboard whoami`	Configured actors and roles.

Idea actions

Command	Transition	Authority
`spark <TITLE> [--body TEXT]`	create idea in `spark`	human instruction
`refine <ID>`	`spark → refine`	human instruction
`pitch <ID>`	`refine → pitch`	human instruction
`accept-idea <ID> --authorised-by …`	`pitch → accepted`, kind becomes batch	consortium
`reject-idea <ID> --reason … --authorised-by …`	`pitch → rejected`	consortium
`request-changes <ID> --reason … --authorised-by …`	`pitch → refine`	consortium
`park <ID> --reason … --authorised-by …`	`refine → spark`	creator
`reopen <ID> --reason … --authorised-by …`	`rejected → spark`	owner/creator
`cancel <ID> --reason … --authorised-by …`	idea or batch → canceled	owner/member

Example:

mdboard --actor agent spark "CSV export for the report table"
mdboard --actor agent refine '#0007'
mdboard --actor agent pitch '#0007' \
  --authorised-by owner --authorization "Pitch it at the next review."

Estimation and roadmap

Command	Effect
`estimate <ID> --tokens-optimistic N --tokens-realistic N --tokens-pessimistic N --agent-hours-optimistic N --agent-hours-realistic N --agent-hours-pessimistic N`	Set the batch estimate.
`reestimate <ID> … --reason … --authorised-by …`	Replace the estimate and update the roadmap total.
`roadmap <ID> --authorised-by …`	`accepted → roadmap`; requires estimate and limit.
`unroadmap <ID> --authorised-by …`	`roadmap → accepted`; no non-canceled tasks.
`breakdown <ID> --authorised-by …`	`roadmap → breakdown`; one active batch.
`abort-breakdown <ID> --reason … --authorised-by …`	`breakdown → roadmap`; cancel pending tasks.
`start <ID> --authorised-by …`	`breakdown → doing`; clarification accepted.

mdboard --actor agent estimate '#0007' \
  --tokens-optimistic 8000 --tokens-realistic 12000 --tokens-pessimistic 20000 \
  --agent-hours-optimistic 0.5 --agent-hours-realistic 1.0 --agent-hours-pessimistic 1.5
mdboard --actor agent roadmap '#0007' \
  --authorised-by owner --authorization "Put it on the roadmap."

Task actions

Command	Effect
`task new <BATCH> <TITLE> [--depends-on <ID>]`	Create a pending task during breakdown.
`work <ID>`	`pending → working`; parent doing; dependencies done.
`done <ID> --commit <SHA>`	`working → done`; records evidence.
`fail <ID> --reason …`	`working → error`.
`recover <ID> --authorised-by …`	`error → pending`.
`handover <BATCH>`	`doing → handover`; all tasks done, no error.

Only one task may be working. The agent commits each finished task.

Review actions

Command	Effect
`review <BATCH> --reviewer <ID> --authored-by <HUMAN> --verdict accepted\|changes-required [--finding ID:TEXT] [--transcribed-by agent]`	Record a review artifact for the current round.
`request-changes <BATCH> --reason … --authorised-by …`	`handover → doing`; rework tasks are created.
`complete <BATCH> --authorised-by …`	`handover → completed`; report and changelog.

complete requires an independent review artifact, the owner accept, a report and a changelog bullet. The agent may transcribe the review, but the provenance is recorded.

Exceptions

Command	Effect
`block <ID> --reason … --authorised-by …`	Any nonterminal batch → `blocked`; stores the return state.
`unblock <ID> --authorised-by …`	`blocked → previous`.
`cancel <ID> --reason … --authorised-by …`	Terminal; cascades to nonterminal tasks.

Meetings

Command	Effect
`meeting list [--pending]`	Show pending, deferred and fixed meetings.
`meeting open <KIND> --batch <ID>`	Open an on-demand gate.
`meeting question add <MEETING> <TEXT>`	Add a clarification question.
`meeting question resolve <MEETING> <QUESTION>`	Mark a question resolved.
`meeting accept <MEETING> --decision …`	Accept the gate.
`meeting defer <MEETING> --until <DATE>`	Keep pending with a new reminder date.
`meeting dismiss <MEETING> --reason …`	Close without a decision.

Branch operations

Command	Who	Effect
`upstream start`	agent or owner	Open a iteration, fast-forward to nightly, take the lease.
`upstream status`	anyone	Iteration, lease, base and merge state.
`upstream merge`	owner only	Merge upstream → nightly, close the iteration.
`release`	owner only	Merge nightly → stable, write release notes and tag.

The agent may prepare checks and reports, but it must not execute the merge or release. The CLI enforces the actor.

Roadmap override

mdboard --actor owner roadmap override --limit 8 \
  --reason "Release crunch" --until 2026-11-01
mdboard --actor owner roadmap clear-override

The effective limit is the override while unexpired; an expired override fails check.

JSON and exit codes

--json is available on read and mutation commands. A typical mutation returns:

{
  "ok": true,
  "card": "#0007",
  "state": "roadmap",
  "authorised_by": "owner",
  "estimated_cost_eur": 0.0027
}

Exit codes:

0 success;
1 validation, authority or state failure;
Clap usage errors use the standard non-zero exit code.

What the agent should always do

Run mdboard actions <ID> before a non-obvious transition.
Check the authority flag before executing a human gate.
Record the human’s statement for every gated action.
Run mdboard context and brief the human after the transition.
Never hand-edit a card, event or generated view.