CLI reference

Complete reference for the mso command-line interface, grouped by what you are trying to do.

Every command prints its own full help, including worked examples, with mso <command> --help (and mso <command> <action> --help for commands with sub-actions). The same reference ships with every install — run mso docs cli-reference to read it offline, or mso docs to list every topic.

Contents

• Getting started — setup, quickstart, init, update, demo, version, docs
• Running the fleet — dispatch, pause, resume, status, doctor, cleanup, squad, worktree
• Voyages and orders — voyage, order, bug, review, chart
• Voyage PRs and releases — pr, release, verify
• Hub, resident LEAD, and Slack bridge — hub, lead, bridge
• Configuration — config, roles, packs, providers, projects, mcp, hooks, migrate
• Usage reporting — usage
• Security and governance — security, policy, identity, audit, secrets, data-flow
• Licence, backup and restore — licence, backup, restore
• Global flags, environment variables, exit codes

Targeting a workspace

Most commands find the workspace by walking up from the current directory to the nearest .mso/. Commands that accept --project ACRONYM can target any project in your registry (~/.maestro/projects.json) from anywhere — the acronym may be written with or without a leading @ (--project MSO or --project @MSO).

---

Getting started

mso setup

Prerequisite validation and the interactive setup wizard (prerequisites, persona, workspace).

mso setup                        # interactive wizard
mso setup --check [--json]       # non-interactive audit
mso setup --repair               # fix repairable issues automatically
mso setup --show persona         # read-only view of one section

Flag	Description
--check	Run checks non-interactively. Exits 0 = OK, 1 = FAIL, 2 = WARN.
--repair	Detect and automatically repair repairable issues.
--show SECTION	Read-only inspection of one section: prereqs, project, workspace, templates, persona.
--json	JSON output (use with --check for CI parsing).
--profile PATH_OR_URL	Explicit enrolment profile (takes precedence over any other profile source).
--non-interactive	Never prompt — fail with the name of the missing key instead (unattended imaging).
--answers FILE	Flat KEY=VALUE answers file consumed in --non-interactive mode.

For a step-by-step walkthrough of the wizard, plus mso init, licence activation, and mso hub setup, see Installation and configuration.

note

mso setup --check uses its own exit code 2 to mean WARN. That differs from the general meaning of 2 (usage error) listed under exit codes.

mso quickstart

Guided first-run experience — verifies the environment, scaffolds a demo workspace, dispatches a small demo voyage, and prints a summary.

mso quickstart [--project DEMO] [--crews N] [--no-demo]

Flag	Default	Description
--project ACRONYM	DEMO	Project acronym for the demo workspace.
--crews N	1	Number of crews to dispatch.
--no-demo		Skip the demo voyage; only verify the environment and initialise the workspace.
--skip-checks		Skip pre-flight checks (for CI use).
--repo ORG/NAME		Link the demo to a GitHub repo.
--no-link-repo		Run local-only, without linking a GitHub repo.
--force		Overwrite existing repo config in the project registry.

mso init

Scaffold a new Maestro workspace (.mso/) inside a project directory.

mso init --project PSG [--pack NAME] [--directory PATH]

Flag	Description
--project ACRONYM	Required. Project acronym (e.g. PSG).
--directory PATH	Workspace directory (default: current directory).
--force	Overwrite an existing .mso/.
--pack NAME	Division pack to scaffold: a built-in id (e.g. sdlc, test-engineering), a path to a custom pack directory, or an https:// URL to a signed custom-pack archive.
--enterprise	Enable enterprise mode — walks through audit-anchor provider configuration.
--non-interactive	Never prompt. With --enterprise, requires MAESTRO_ANCHOR_PROVIDER rather than defaulting to the filesystem anchor.

mso init creates the directory tree, CLAUDE.md layers and default config files. It never copies another project's artefacts — every workspace starts empty.

Omitting --pack, or passing --pack sdlc, gives the default SDLC workspace; the two are byte-identical. See division packs. Non-free packs require a matching licence tier (or MAESTRO_SKIP_AUTH=1 for a local trial).

mso update

Propagate schema and template updates to an existing workspace.

mso update                     # apply updates to the workspace in the current directory
mso update --dry-run           # preview the changes without writing anything
mso update --directory PATH    # target a different workspace
mso update --force             # also overwrite files that would otherwise be skipped

Applying is the default — there is no --apply flag. Idempotent — safe to run repeatedly.

mso demo

A simulated fleet on the live dashboard: six demo orders across three simulated crews, ending with a report and full cleanup. No Claude invocations, no token spend. Refuses to run while a real fleet is active.

mso demo [--headless] [--fast] [--keep]

Flag	Description
--headless	No live dashboard — run the simulation and print the report (CI mode).
--fast	Scale all timings to 10% (a full run in about 10 seconds).
--keep	Keep demo artefacts after the run (crew state is still restored).
--project ACRONYM	Project to use when not run from inside a workspace.

mso version

Print the installed Maestro version.

mso version

mso docs

Browse the documentation that ships with the package.

mso docs              # list every topic
mso docs hub          # read one topic

---

Running the fleet

mso dispatch

Launch fleet crews from the order queues. The dispatcher runs as a detached background process, so it survives the terminal that started it.

mso dispatch [--max-crews N] [--stagger-delay S] [--timeout M] [--max-turns N]

Flag	Default	Description
--max-crews N	5	Crew slots to fill concurrently (1–5).
--stagger-delay S	30	Seconds between successive crew launches — reduces API rate pressure.
--timeout M	60	Wall-clock ceiling per crew iteration, in minutes.
--max-turns N	200	Claude turn cap per crew iteration. When hit, the order is requeued with fresh context.
--convergence-timeout S	60	Per-operation timeout, in seconds, for convergence git network operations. Also configurable in workspace.json.
--cleanup		Run mso cleanup before dispatching.
--project ACRONYM		Registered project to dispatch.

How a stuck crew is detected. The primary hang control is an activity watchdog: a crew whose output stream has been silent for 10 minutes (configurable) is treated as hung, its in-flight work is preserved, and its order is requeued. A crew that keeps working is never killed before the --timeout ceiling, which only backstops a crew that streams continuously but never finishes. --timeout and --max-turns are both active — whichever fires first wins.

A heavy order can raise its own ceiling with a timeoutMinutes field on the order, and a role can have a default in workspace.json; both take precedence over --timeout.

mso pause

Drain the fleet: the dispatcher claims no new work, lets every running crew finish, then exits cleanly — nothing is killed, salvaged or retried.

mso pause [--wait]

Flag	Description
--wait	Block until the fleet reports PAUSED. Exits 1 if the dispatcher exits before the drain completes.
--project ACRONYM	Registered project to pause.

Draining can take as long as the longest-running crew's remaining timeout plus the verify gate. Need the fleet stopped now instead? Stop the dispatcher and run mso cleanup — running crews are killed and their in-flight work is preserved and requeued.

mso resume

Resume a paused fleet, or cancel a pause that is still draining.

mso resume [--max-crews N] [--stagger-delay S] [--timeout M] [--max-turns N]

• While PAUSING — withdraws the pause; the running dispatcher resumes claiming work on its next tick, with no restart.
• Once PAUSED — relaunches the dispatcher with the settings it was paused with. Any flag given here overrides the recorded value.

A plain mso dispatch also clears a paused fleet. No mso cleanup or mso order retry is needed.

mso status

Display the fleet status dashboard.

mso status [--once] [--compact]

Flag	Description
--once	Print once and exit (default is live-updating).
--compact	One-line summary per crew.
--project ACRONYM	Registered project to show.

mso doctor

Read-only fleet self-check — deterministic health checks across the dispatcher, crews, orders, voyages and workspace hygiene. No LLM, and no running dispatcher required. Each finding carries a suggested command; doctor itself never changes anything. Exits non-zero on any finding of high severity or above.

mso doctor [--json] [--all] [--explain]
mso doctor --all-projects

Flag	Description
--json	Machine-readable JSON output.
--all	Show every current finding, including unchanged ones (by default only changes since the last run are reported).
--explain	Also print which configuration tier supplied each check, and the resolved SCM/CI/issues/deploy provider per kind.
--all-projects	Check every project in the registry — one section per fleet, plus one machine-wide section.
--project ACRONYM	Registered project to check.
--single-check CHECK-ID	Run exactly one check and print a {verified, stillOpen, reason} JSON result, without recording state. Used by the Hub; pair with --subject-id ID.

See mso docs patrol for the check catalogue.

mso cleanup

Stop orphaned crew processes and reset stale crew state. A backup is taken first.

mso cleanup [--no-backup]

Flag	Description
--no-backup	Skip the automatic backup (fast recovery path).
--force	Proceed even though a live dispatcher is running. Intended only for a dispatcher that is alive but wedged (see mso doctor), never a healthy one.
--project ACRONYM	Registered project to clean up.
--maestro-dir PATH	Explicit path to the .mso directory (or its parent workspace root), bypassing workspace auto-detection.

cleanup refuses to run against a live dispatcher unless --force is given.

mso squad / mso crew

Inspect or stop a single crew slot. crew is an alias for squad.

mso crew --crew 1 --status
mso crew --crew 1 --watch
mso crew --crew 1 --cleanup

Flag	Description
--crew N	Required. Crew slot number, 1–5.
--status	Show the crew's status.
--watch	Watch the crew's progress live.
--cleanup	Stop this crew's process.
--project ACRONYM	Registered project.

mso worktree

Manage crew and voyage git worktrees directly.

mso worktree prune [--project ACRONYM]

prune removes worktrees whose voyage has been archived as complete. It is the same occupancy-guarded prune the dispatcher runs at startup. The resident LEAD agent only ever proposes a prune; this command is how you carry one out.

---

Voyages and orders

mso voyage / mso sprint

Manage voyages — a voyage owns one branch, one pull request, and a set of orders. sprint and voyage are interchangeable names for the same command.

mso voyage create "Voyage title" --project MSO
mso voyage list [--project MSO]
mso voyage status VOY-MSO-2026-0001
mso voyage why VOY-MSO-2026-0001 [--json]
mso voyage reconcile [--dry-run] [--json] [--voyage VOY-ID]
mso voyage supersede VOY-MSO-2026-0001 --by 393 [--note TEXT]

Action	Description
create TITLE --project ACRONYM	Create a voyage. Options: --plan-order ORDER-ID links the voyage to the plan order it was cut from. --checkout is deprecated (see below).
list	List active voyages. --project filters by project.
status VOY-ID	Show a voyage's details.
why VOY-ID	Explain why a voyage is not moving, and what to do about it. --json emits the same record the Hub shows.
reconcile	Archive voyages whose PR has merged (see below).
supersede VOY-ID --by PR	Record that a voyage's work shipped under a different PR after its original PR was closed. Options: --url URL, --note TEXT, --repo REPO (multi-repo voyages), --force to re-point an existing record.

Creating a voyage has no git side effect. The voyage records its branch name; the branch is created on the remote automatically the first time a crew is dispatched for it. --checkout restores the old behaviour of also running git checkout -b locally, and prints a deprecation notice.

reconcile flags

Flag	Description
--dry-run	Show what would be archived without changing anything.
--json	Emit the housekeeping report — what changed and what was refused, with reasons.
--voyage VOY-ID	Only reconcile this voyage.
--repo REPO	For a multi-repo voyage, only check this repo's PR. A subset never archives the whole voyage.
--maestro-dir PATH	Explicit path to the .mso directory, bypassing auto-detection.

The PR's merged state is authoritative, so squash, rebase and merge-commit merges are all detected. Reconcile runs automatically at dispatcher startup, and is the same operation as the Hub's housekeeping (broom) button. Because PRs are usually merged after the dispatcher has exited, run it by hand — or from the Hub — after merging.

mso order

Create, diagnose and recover orders.

mso order create "Add CSV export" --type FTR --project MSO [--voyage VOY-ID]
mso order why BUG-MSO-2026-0141 [--json]
mso order retry BUG-MSO-2026-0141 [--role BLD] [--reason TEXT]
mso order skip BUG-MSO-2026-0099 [--reason TEXT]
mso order unskip BUG-MSO-2026-0099
mso order remove BUG-MSO-2026-0099 --from-voyage VOY-MSO-2026-0042
mso order list

Action	Description
create TITLE	Create an order of any type (see flags below). Identical to an order created from the Hub or the Slack bridge.
why ORDER-ID	Explain why an order is stuck: the cause, the evidence, and the ordered options for unsticking it. Exits 0 with a plain sentence when nothing is wrong. --json for the machine-readable record.
retry ORDER-ID	Reopen a STALLED or FAILED order, or reset a stranded queued order, back to PENDING for re-dispatch. The only sanctioned way to re-run an order the fleet has recorded as finished.
skip ORDER-ID	Add an order to the persistent skip list — it will not be dispatched. --reason TEXT is optional.
unskip ORDER-ID	Remove an order from the skip list.
remove ORDER-ID --from-voyage VOY-ID	Remove an order from a voyage's manifest and add it to the skip list.
list	Show the orders currently on the skip list.

create flags

Flag	Description
--type TYPE	Required. Order type prefix: FTR, BUG, SEC, INV, PLN, DOC, … (a division pack may define more).
--project ACRONYM	Required. Project acronym.
--priority P	CRITICAL, HIGH, MEDIUM or LOW. Default depends on type — HIGH for BUG/SEC-style types, otherwise MEDIUM.
--description TEXT	Longer body for the crew.
--role-sequence LIST	Comma-separated role chain, e.g. PLN,BLD,TST. Default: the workspace's configured sequence for the order type.
--target-role ROLE	Role to start at (default: first role of the sequence). Must be in the sequence.
--voyage VOY-ID	Attach the order to a voyage: it is added to the voyage's order list and takes the voyage's branch.
--voyage-branch BRANCH	Branch the crew must work on. Defaults to the --voyage voyage's branch; refused if it disagrees with it.
--target-repo NAME	Target repo in a multi-repo workspace.
--plan-order ORDER-ID	Plan order this order was cut from.
--depends-on IDS	Comma-separated order IDs this order depends on.
--status S	PENDING (default), BACKLOG (parked) or PROPOSED (waits on its dependencies — requires --depends-on).
--queue DIR	Queue directory to create the order in (default: orders).

retry flags

Flag	Description
--role ROLE	Role to retry at (default: the role the order stalled in).
--reason TEXT	Why the order is being retried.
--force	Required to retry an order archived as COMPLETE, or one queued IN_PROGRESS.
--no-salvage	Re-run the role from scratch instead of reusing preserved work.
--salvage BRANCH	Reuse this specific preserved-work branch. Required when the choice is ambiguous — retry lists every candidate and refuses to guess.
--force-salvage	Reuse preserved work even when it is detected as stale (it would revert commits already on the voyage branch).

By default retry reuses the newest preserved-work (salvage/…) branch so work already done is not repeated. A running dispatcher picks the reopened order up on its next scan.

Dispatch order. When a crew slot frees up, a CRITICAL order in any queue goes first. Otherwise the queue directory decides, and priority breaks ties within a queue. mso status shows the next orders in exactly this order.

See mso docs orders-and-voyages and mso docs when-a-voyage-is-stuck.

mso bug

Shorthand for creating a BUG order.

mso bug "Login crashes on empty password" --project MSO [--priority CRITICAL]

Flag	Description
--project ACRONYM	Required. Project acronym.
--priority P	CRITICAL, HIGH (default), MEDIUM or LOW.

mso review

Human-review gate management — inspect, approve, revise or reject orders waiting at a gate. The Hub's review actions perform exactly the same operations.

mso review queue
mso review show BLD-MSO-2026-0001 [--editor CMD]
mso review approve BLD-MSO-2026-0001
mso review revise  BLD-MSO-2026-0001 --notes "..."   # --notes is required
mso review reject  BLD-MSO-2026-0001 --notes "..."   # --notes is required

Action	Description
queue	List orders awaiting review.
show ORDER-ID	Open the order's plan in $EDITOR (or --editor CMD), or print it.
approve ORDER-ID	Approve and advance the order to its next role.
revise ORDER-ID --notes TEXT	Send the order back to the planner with revision notes.
reject ORDER-ID --notes TEXT	Reject the order and archive it as FAILED.

All actions accept --project ACRONYM. See mso docs human-review-gates.

mso chart

Render or author a chart — the graph of how a voyage's orders and roles connect. Rendering is available on every tier; authoring requires Pro or above.

mso chart show VOY-MSO-2026-0144 [--format ascii|mermaid|json]
mso chart new --from-voyage VOY-MSO-2026-0144 [-o PATH]
mso chart validate PATH
mso chart validate --all

Action	Description
show TARGET	Render a voyage's chart, or a single order's role chain. --format is ascii (default), mermaid or json.
new --from-voyage VOY-ID	Compile a voyage into a chart file (Pro+). -o/--output PATH overrides the default location under charts/.
validate [FILE]	Validate a chart file against the chart schema rules. --all validates every chart in the workspace.

All actions accept --project ACRONYM. See mso docs charts.

---

Voyage PRs and releases

mso pr

Read and act on a voyage's pull request through whichever SCM and CI providers the workspace has configured (GitHub or Bitbucket; GitHub Actions or Jenkins). Every action works on the PR for the current voyage branch ($MAESTRO_VOYAGE_BRANCH) — there is no PR-number argument, by design. Nothing here merges, tags or publishes.

mso pr status
mso pr checks [--json]
mso pr ci-log "pytest (3.13)" [--max-lines N]
mso pr threads
mso pr reply THREAD-ID --body "Fixed in 1a2b3c4."
mso pr resolve THREAD-ID

Action	Description
status	The voyage PR: id, URL, head/base refs, head SHA, draft and merged state.
checks	CI checks on the voyage PR.
ci-log CHECK	The failed-step log of one check, named exactly as checks lists it. --max-lines N prints only the last N lines (default 400).
threads	Review threads, marking those opened by a configured review bot.
reply THREAD --body TEXT	Reply on a review thread.
resolve THREAD	Resolve a review-bot thread.

Every action accepts --json; the command accepts --project ACRONYM. See mso docs providers.

mso release

Release-readiness report and version-bump helper.

mso release preflight [--json]
mso release cut 5.14.0              # dry run — previews only
mso release cut 5.14.0 --execute    # bump version files + open the release PR

Action	Description
preflight	Read-only release-readiness report.
cut VERSION	Preview (default) or, with --execute, apply the version bump and attempt to open the release PR.

cut stops before the tag: the remaining steps (merge, tag, push, publish) are printed as text for a person to run. Neither action ever tags, pushes tags, creates a release, or publishes a package. Both resolve the repository root by walking up from the current directory.

mso verify

Post-voyage build and test verification of completed work.

mso verify [--voyage VOY-ID] [--skip-tests]

Flag	Description
--voyage VOY-ID	Voyage to verify.
--skip-tests	Reuse existing test results.
--project ACRONYM	Registered project.

---

Hub, resident LEAD, and Slack bridge

mso hub

Manage the Maestro Hub — the multi-workspace dashboard (Team/Enterprise).

mso hub start [--port 3847] [--open]
mso hub status
mso hub stop
mso hub setup [--mode local|docker] [--output-dir DIR] [--dry-run] [--force]

Action	Description
start	Start the Hub as a background process, serving the API and the dashboard on one port. No Docker or Node required.
status	Show whether the Hub is running, with its PID and URL.
stop	Stop the Hub.
setup	Provision the Hub from your project registry. --mode local (default) validates the registry and prints the start command, writing nothing. --mode docker generates a compose overlay and a container registry.

Flag	Applies to	Description
--port N	start	Port to bind (default 3847).
--open	start	Open the dashboard in a browser.
--force	start, setup	start: launch even if a stale PID record claims the Hub is already running. setup: overwrite existing generated files.
--mode local|docker	setup	Deployment mode (default local).
--output-dir DIR	setup --mode docker	Where to write the generated files.
--dry-run	setup --mode docker	Print both generated files without writing them.

For a walkthrough of local and Docker Hub setup, see Installation and configuration.

See mso docs hub.

mso lead

Manage the resident LEAD agent — a per-workspace background agent that runs fleet health checks on a schedule, watches fleet events, and carries out a small set of safe housekeeping actions (Pro/Team/Enterprise). It survives the dispatcher exiting and does not use a crew slot.

mso lead start | stop | restart | status
mso lead run --once
mso lead stand-down | resume
mso lead ack --fingerprint FP [--note TEXT] [--by NAME] [--days N]
mso lead unack --fingerprint FP

Action	Description
start	Start the LEAD agent for this workspace. --force launches even if a stale PID record claims it is already running.
stop	Stop the LEAD agent. Never tier-gated.
restart	Stop, then start.
status	Running state, heartbeat age, findings by severity, and last action.
run --once	Run a single check-and-act cycle in the foreground, without starting the background agent — see what it would do.
stand-down	Keep the agent running but skip its cycles until resumed. The setting persists across restarts. Never tier-gated.
resume	Resume a stood-down agent.
ack --fingerprint FP	Acknowledge an open finding so it stops being reported. --note records a reason, --by who acknowledged (default: current OS user), --days the expiry (default 7 — an acknowledgement always expires). Never tier-gated.
unack --fingerprint FP	Clear an acknowledgement early. Never tier-gated.

Finding fingerprints are shown by mso lead status and mso doctor --json. All actions accept --project ACRONYM. The LEAD agent is not started automatically — starting it is an operator decision.

mso bridge

Manage the Slack bridge (command poller plus Slack bot).

mso bridge setup
mso bridge start | stop | restart | status
mso bridge test --project MSO

Action	Description
setup	Interactive setup wizard — creates the bridge settings file.
start / stop / restart	Start, stop or restart both the poller and the Slack bot.
status	Show the status of each bridge component.
test	Send a test Slack notification. Requires --project ACRONYM.
poller-start / poller-stop	Start or stop only the command poller.
bot-start / bot-stop	Start or stop only the Slack bot.

See mso docs bridge-setup-guide.

---

Configuration

mso config

Inspect resolved Maestro configuration. Requires a sub-action.

mso config models      # the model assigned to each role, and where that assignment came from

mso roles

Inspect and validate role definitions and per-role overlays. Core role files ship with the package; your overlays live at .mso/config/roles/<CODE>.md and are merged on top.

mso roles list                              # all canonical roles with codes, names, models
mso roles show TST                          # effective (merged core + overlay) role config
mso roles show TST --core                   # core role only
mso roles show TST --overlay-only           # your overlay only (if present)
mso roles show TST --json                   # parsed role definition as JSON
mso roles validate                          # validate all role files + overlays; exit 0/1
mso roles diff TST                          # unified diff: core vs effective merged role
mso roles migrate-paths                     # guidance for migrating off legacy role-paths.json

Legacy role-paths.json is still read but deprecated. migrate-paths prints step-by-step migration guidance; it does not generate overlay files. See mso docs role-overlays.

mso packs

Discover, inspect and apply division packs.

mso packs list
mso packs show test-engineering [--json]
mso packs validate [PACK] [--path DIR]
mso packs apply test-engineering [--dry-run] [--force]

Action	Description
list	List built-in packs with tier and access badges.
show PACK	Print a pack's manifest, order types and shipped assets. --json prints the raw manifest.
validate [PACK]	Validate manifest, role overlays, persona, order templates, and gate/workspace defaults. Omit PACK to validate every built-in pack; --path DIR validates an arbitrary pack directory. Exits 0/1 — CI-usable.
apply PACK	Apply a pack to an existing workspace. PACK may be a built-in id, a custom pack directory, or an https:// URL to a signed custom-pack archive (Team/Enterprise). --dry-run shows the preview only; --force applies even if the enrolment profile locked the workspace to a different pack; --project ACRONYM targets a registered project.

mso providers

Configure the SDLC providers Maestro uses for each kind of integration: scm, ci, issues and deploy. The same settings are editable from mso setup and the Hub.

mso providers list
mso providers show scm
mso providers set scm bitbucket --config flavour=cloud --config workspace=acme
mso providers set ci jenkins --config baseUrl=http://jenkins.local --config token=env:JENKINS_TOKEN
mso providers unset scm
mso providers test scm

Action	Description
list	Every kind: installed provider ids, the configured id, and whether a policy bundle locks it.
show KIND	One kind's configured entry and resolved outcome.
set KIND ID	Configure a kind to a provider id. --config FIELD=VALUE is repeatable.
unset KIND	Remove a kind's configuration (reverts to the default).
test KIND	Resolve a kind now — the same result mso doctor --explain reports.

Every action accepts --json; the command accepts --project ACRONYM. A kind pinned by a signed policy bundle is reported as locked and cannot be changed here.

Credentials are never literal values. A config field that looks like a credential must be given as env:NAME (read from an environment variable) or secret://provider/namespace/key (Enterprise). A literal credential is refused before it reaches disk. See mso docs providers.

mso projects

List and manage the global project registry (~/.maestro/projects.json). Requires an action.

mso projects list            # all registered projects with paths
mso projects remove ACRONYM  # unregister a project

mso mcp

Manage the MCP server registry — which MCP servers crews may use, and in which roles.

mso mcp list
mso mcp show NAME
mso mcp add --name github --command npx --args @modelcontextprotocol/server-github \
            --allowed-roles BLD,TST --risk-level medium --env-required GITHUB_TOKEN
mso mcp add --json server-entry.json
mso mcp remove NAME
mso mcp validate

Action	Description
list	List all registered servers.
show NAME	Show one server's full entry.
add	Add a server (flags below), or import an entry with --json FILE.
remove NAME	Remove a server from the registry.
validate	Validate the registry and check required environment variables are set.

add flags

Flag	Description
--name NAME	Server name — must match the key in .claude/settings.json.
--command CMD	Executable name or full command.
--args ARG	Command argument (repeatable).
--allowed-roles LIST	Comma-separated role codes, or *.
--risk-level LEVEL	low, medium (default), high or critical.
--env-required VAR	Required environment variable name (repeatable).
--description TEXT	Human-readable purpose.
--notes TEXT	Operator notes or audit trail.
--json FILE	Import the entry from a JSON file.

All actions accept --project ACRONYM.

mso hooks

Install or uninstall Maestro's Claude Code hooks in ~/.claude/settings.json.

mso hooks install
mso hooks uninstall

mso migrate

Migrate a workspace's artefact layout.

mso migrate artefact-repo --dry-run
mso migrate artefact-repo [--dest DIR] [--name NAME] [--remote URL] [--clean-product]
mso migrate artefact-repo --rollback --dest DIR
mso migrate import-workspace SOURCE --into TARGET --sub-acronym POR [--dry-run]

Action	Description
artefact-repo	Move the workspace's durable .mso/ artefacts (orders, voyages, plans, reports, config) out of the product repo into a dedicated artefact repo. Takes a mandatory backup and verifies the copy.
import-workspace SOURCE	Merge an existing workspace into a target workspace, renaming imported IDs with a sub-acronym (<SOURCE>-* → <TARGET>-<SUB>-*) and rewriting cross-references.

artefact-repo flags

Flag	Description
--dest DIR	Destination artefact repo directory (default: a sibling <ACRONYM>-Platform).
--name NAME	Artefact repo name (default: <ACRONYM>-Platform).
--remote URL	Git remote to set as origin on the artefact repo.
--clean-product	After cutover, untrack .mso/ from the product repo in a sweep commit (files stay on disk).
--dry-run	Print the action table without changing anything.
--rollback	Undo a migration: delete the --dest repo and revert the registry to embedded mode.
--project ACRONYM	Project to migrate (needed when the registry holds more than one).

import-workspace flags

Flag	Description
--into TARGET	Required. Target workspace root (the directory containing .mso/).
--sub-acronym SUB	Required. Sub-acronym for the imported namespace (e.g. POR, WEB).
--target-acronym ACRONYM	Override the target acronym (default: read from the target workspace).
--dry-run	Print the action table and full rename map without changing anything.

See mso docs artefact-repo and mso docs multi-repo.

---

Usage reporting

mso usage

Token usage and cost reporting.

mso usage                        # workspace-wide summary (same as --summary)
mso usage --voyage VOY-MSO-2026-0001
mso usage --order FTR-MSO-2026-0001
mso usage --report [--output PATH]

Flag	Description
--summary	Workspace-wide summary. The default when no flag is given.
--voyage VOY-ID	Per-voyage breakdown.
--order ORDER-ID	Per-order breakdown.
--report	Generate a full Markdown report; --output PATH sets where it is written.
--project ACRONYM	Registered project. Also selects the matching Claude Code transcript directory.
--project-path PATH	Explicit Claude Code transcript directory, bypassing auto-detection.

--summary, --voyage, --order and --report are mutually exclusive.

---

Security and governance

mso security

OWASP/CWE security scanning and diff-aware security review.

mso security scan [--severity-threshold HIGH] [--json]
mso security review [--against origin/main | --staged] [--json]

scan flags

Flag	Default	Description
--severity-threshold LEVEL	INFO	Minimum severity to report: INFO, LOW, MEDIUM, HIGH, CRITICAL.
--since YYYY-MM-DD		Scan files modified since this date.
--order ORDER-ID		Tag the resulting report with this order.
--voyage VOY-ID		Tag the resulting report with this voyage.
--json		Output results as JSON.
--project ACRONYM		Registered project.

--order and --voyage only tag the report; the scan still covers all files modified by crews.

review flags

Flag	Default	Description
--against REF	origin/main	Diff base ref. Ignored with --staged.
--staged		Review staged changes instead of the branch diff.
--severity-threshold LEVEL	MEDIUM	Minimum severity to include.
--json		Output the report summary as JSON.
--project ACRONYM		Registered project.

mso security review writes a unified report to .mso/reports/security/REVIEW-*.md.

mso policy

Signed governance policy bundles (Enterprise) — Ed25519-signed guardrails an organisation can ship that a local engineer cannot silently relax.

mso policy pull [--url URL]
mso policy verify [--bundle PATH]
mso policy verify --ci --base origin/main
mso policy show
mso policy report [--json] [--output PATH]

Action	Description
pull	Fetch the signed bundle, verify its signature and version, and install it. --url overrides the source. Honours offline grace.
verify	Verify a bundle's signature without advancing the version floor (read-only). --bundle PATH checks a specific file.
verify --ci	CI enforcement backstop — re-evaluate a committed diff against the governed rules and exit non-zero on any violation, so a locally bypassed rule still fails the merge.
show	Show the installed bundle, pinned trusted keys and version floors.
report	Produce a compliance evidence document (policy inventory, evaluation/deny/break-glass statistics, bundle provenance) from live policy state and the audit log. --json prints raw evidence; --output PATH sets the Markdown path.

verify --ci flags

Flag	Description
--base REF / --against REF	Diff base for base...HEAD (default origin/main).
--head REF	Diff head (default HEAD).
--staged	Evaluate staged changes instead of a branch diff.
--diff-file PATH	Read a pre-computed unified diff (- for stdin).
--repo DIR	Repository directory to run git in.
--include GLOB / --exclude GLOB	Restrict or skip paths (repeatable).
--no-default-excludes	Do not apply the built-in documentation/pack exclude set.
--warn-only	Report violations but exit 0.
--json	Machine-readable report.

Authoring bundles. keygen, init, lint and sign are available on every tier; trust add/trust rotate, enable and publish require Team or Enterprise.

mso policy keygen --key-id acme-2026-q3 [--out DIR]
mso policy init --bundle-id acme-standard [--from protected-branch,secret-handling] [--out PATH] [--mode enforce|warn|off]
mso policy lint acme-policy.json
mso policy sign acme-policy.json --key-id acme-2026-q3 [--key-file PATH] [--out PATH]
mso policy publish acme-policy.json [--out PATH]
mso policy trust add --key-id acme-2026-q3 --public-key B64 [--status active|retiring|revoked] [--not-after ISO]
mso policy trust rotate --retire acme-2026-q2 --activate acme-2026-q3 [--public-key B64] [--not-after ISO]
mso policy enable --mode enforce|warn|off

Action	Description
keygen	Generate an org Ed25519 signing keypair. The private seed is refused inside a git tree or a .mso/ workspace; the public key prints to stdout.
init	Draft an unsigned bundle, optionally seeded from named built-in packs.
lint BUNDLE	Schema-validate an unsigned draft.
sign BUNDLE	Sign a draft with the org seed (--key-file, or MAESTRO_POLICY_SIGNING_KEY).
publish BUNDLE	Confirm a bundle is signed and copy it for HTTPS hosting.
trust add / trust rotate	Pin, retire and activate signing keys in your home trusted-key registry.
enable --mode MODE	Set the workspace's governed mode: enforce, warn or off.

See mso docs governance-trust-boundary.

mso identity

Identity, groups, ACLs and GDPR data-subject-rights tooling (Enterprise).

mso identity init [--encryption git-crypt|sops|none]
mso identity add-user --email alice@acme.com --display-name "Alice" [--group captains] [--public-key PATH]
mso identity add-group --name auditors
mso identity set-group --email alice@acme.com --group fleet_operators
mso identity remove-user --email alice@acme.com
mso identity show [--email alice@acme.com]
mso identity sign-acl --key-id acme-2026-q3 [--key-file PATH]
mso identity acl list [--principal group:captains]
mso identity acl set    --principal group:contributors --capability voyage.create --scope "*"
mso identity acl remove --principal group:contributors --capability voyage.create --scope "*"
mso identity rights export alice@acme.com
mso identity rights forget alice@acme.com [--execute]
mso identity rights restrict alice@acme.com
mso identity rights export-classification

Action	Description
init	Seed the identity store with default groups and access rules. --encryption selects optional at-rest encryption (default none).
add-user	Enrol a user. --group is repeatable.
add-group	Create a group.
set-group	Add a user to a group.
remove-user	Remove a user.
show	Show a user's effective capabilities (default: the current caller).
sign-acl	Sign the identity integrity manifest, required in governed enforce mode. The seed comes from --key-file or MAESTRO_IDENTITY_SIGNING_KEY.
acl list / acl show	List ACL entries, optionally filtered by --principal.
acl set / acl remove	Add or remove an ACL entry. Principal is user:<email> or group:<name>; scope is *, project:<acronym>, voyage:<id> or role:<code>.
rights export EMAIL	GDPR Article 15 — export all data held for a subject.
rights forget EMAIL	GDPR Article 17 — produce an erasure plan (dry run). --execute performs the identity-layer deletions; rewriting git history remains a manual step.
rights restrict EMAIL	GDPR Article 18 — restrict processing for a subject.
rights export-classification	Export a data-classification CSV for all user records.

Alternative grouped forms are also available: mso identity user add|remove|list, mso identity group add|remove|list (group add takes --capabilities LIST and --scope), and mso identity assign EMAIL --to-group GROUP. All actions accept --project ACRONYM.

mso audit

The hash-chained audit log (Enterprise).

mso audit tail [--lines 50] [--no-follow]
mso audit verify
mso audit export [--format json|jsonl|csv] [--since YYYY-MM-DD]
mso audit anchor [--provider s3|azure|s3-compat|fs] [--config FILE]
mso audit anchor --auto

Action	Description
tail	Live-tail the audit log. -n/--lines N sets how many lines to show first (default 20); --no-follow prints and exits.
verify	Walk the hash chain; exits non-zero if tampering is detected.
export	Dump entries to stdout. --format is jsonl (default), json or csv; --since filters by date.
anchor	Write the current root hash to external immutable storage. -p/--provider defaults to fs (filesystem — development/test only). --config FILE supplies provider settings; --auto reads provider and settings from workspace.json (for cron or Task Scheduler).

All actions accept --project ACRONYM.

mso secrets

Secrets-provider operator tooling (environment, OS keyring, AWS, Azure, Vault, 1Password) — Enterprise.

mso secrets doctor             # verify every secret:// reference in workspace config resolves
mso secrets list               # list secret keys (never values)
mso secrets rotate --key KEY   # start the rotation workflow for a key
mso secrets scrub              # scan config and logs for cleartext secrets

All actions accept --project ACRONYM.

mso data-flow

Generate a diagram of every outbound network destination the workspace calls, for data-residency review. Workspaces with an egress allowlist configured show only the allowed hosts.

mso data-flow [--format mermaid|graphviz] [--mode MODE] [--output PATH]

Flag	Default	Description
--format	mermaid	Diagram format: mermaid or graphviz.
--mode MODE		Render as if the egress mode were permissive, restrictive or air-gapped.
--output PATH	stdout	Write the diagram to a file.
--project ACRONYM		Registered project.

---

Licence, backup and restore

mso licence

Licence activation and management. license is accepted as an alias.

mso licence activate KEY       # or set MAESTRO_LICENCE_KEY and omit KEY
mso licence status [--json]
mso licence revalidate         # force an online re-check now
mso licence deactivate         # remove the local licence record and keychain entry

Action	Description
activate [KEY]	Activate a licence key or token. With no argument, reads MAESTRO_LICENCE_KEY.
status	Show the locally cached licence state, including any warning. --json for machine-readable output.
revalidate	Force an online re-check now, bypassing the 24-hour cache.
deactivate	Remove the local licence record and keychain entry.

mso licence --help also lists keygen and issue. These are licence-issuing tools for the Maestro vendor; customers never need them.

See mso docs licence.

mso backup

Create or list backups of workspace state.

mso backup [--project ACRONYM] [--output DIR]
mso backup --list

Flag	Description
--project ACRONYM	Back up only this project (default: all).
--output DIR	Output directory (default: ./maestro-backups/).
--list	List available backups instead of creating one.

mso restore

Restore workspace state from a backup ZIP.

mso restore BACKUP.zip [--dry-run] [--merge | --force] [--project ACRONYM]

Flag	Description
--dry-run	Print what would be written without writing anything.
--merge	Where a file exists on both sides, keep the newer one (by modification time).
--force	Overwrite existing files.
--project ACRONYM	Restore only files belonging to this project.

---

Global flags

Flag	Description
--debug	Show full tracebacks on unexpected errors (also enabled by MAESTRO_DEBUG=1). Sets MAESTRO_DEBUG=1 in child processes.

---

Environment variables

Variable	Purpose
MAESTRO_DIR	Override workspace dir resolution.
MAESTRO_PERSONA	Force persona ID (overrides workspace config).
MAESTRO_PROJECT	Project acronym for multi-project dispatcher awareness.
MAESTRO_SPRINT_BRANCH	Voyage branch the current crew must operate on.
MAESTRO_REPO_PATH	Per-crew managed repo / worktree path.
MAESTRO_CREW	Crew slot number (1–5).
MAESTRO_ITER_MANAGED	When set, the stop hook exits cleanly and the Python loop owns iteration control.
MAESTRO_BRANCH_GUARD_BYPASS	Escape hatch for manual recovery — disables the pretool branch guard.
MAESTRO_DEBUG	Show full tracebacks on unexpected errors (same as --debug).
MAESTRO_SKIP_AUTH	Skip licence check (used in CI).
MAESTRO_LICENCE_KEY	Activate licence non-interactively.

---

Exit codes

Code	Meaning
0	Success
1	General error — configuration problem, licence issue, or unexpected runtime error
2	Usage / argument error — mistyped subcommand, wrong flags, ambiguous input
3	No work — command ran cleanly but nothing to do (empty queue, no matching data)
130	Interrupted — Ctrl+C

Some commands define their own codes in addition — for example mso setup --check (2 = WARN) and mso doctor (non-zero on high-severity findings).

---

Error handling & troubleshooting

The mso CLI presents friendly error messages instead of raw Python tracebacks. Unexpected errors show a concise message with instructions to re-run with --debug for the full trace.

Did-you-mean suggestions — mistyped subcommands produce a difflib suggestion:

$ mso statsu
[Maestro] argument command: invalid choice: 'statsu'
  Did you mean: 'status'?
  Run: mso status --help

Disambiguation hints — bare positional project acronyms suggest the correct flag form:

$ mso usage MSO
[Maestro] 'usage' takes no positional argument 'MSO'.
  Did you mean: mso usage --project MSO

For real-world problems and fixes (broken installs, community-tier surprises, guard refusals, verify-gate holds, stalled orders) plus the full error taxonomy, debug mode reference, and Ctrl+C behaviour, see Troubleshooting & FAQ.