CLI Commands

BMO has both interactive and non-interactive entrypoints. Use the TUI for daily coding, and use the sections below for scripts, automation, integrations, and background services. For the complete Cobra tree (including every subcommand and flag), run bmo --help and bmo <command> --help locally; when adding a new top-level command, update the CLI reference inventory and internal/cmd/root.go together.

Maturity: Reference surface. Use this page after you know which operator, automation, integration, or maintainer workflow you are trying to drive.

Reference provenance: manual_reference_debt — curated inventory; exhaustive subcommands and flags live in Cobra help (docs/book/reference-provenance.json).

Top-level command inventory

These reflect the current top-level Cobra tree (interactive and headless entrypoints are described in the next section):

Command	Purpose	Primary source
bmo (root)	Interactive TUI (default)	internal/cmd/root.go
bmo arena	Maintainer Arena commands, including the detached bmo arena status posture surface for session candidate and workflow summaries	internal/cmd/arena.go
bmo auth	Provider auth bootstrap (copilot, hyper, openrouter)	internal/cmd/auth.go
bmo backfill	Maintainer-only offline backfill for messages.visible_text	internal/cmd/backfill.go
bmo bedrock	Bedrock operational resources such as inference profiles	internal/cmd/bedrock.go
bmo behavior-prune	Export behavior-prune candidate bundles	internal/cmd/behavior_prune.go
bmo cache	Optional provider prompt-cache helpers	internal/cmd/cache_gemini.go
bmo capture	Maintainer docs capture utilities such as ANSI pane frame export for book captures	internal/cmd/capture_cmd.go
bmo checkpoint	Session checkpoints and git undo	internal/cmd/checkpoint.go
bmo edit-capsules	Inspect and retry bounded edit-capsule rollback recovery	internal/cmd/edit_capsules.go
bmo cleanup	Maintainer cleanup planning, quorum artifacts, and approved apply flows	internal/cmd/cleanup.go
bmo completion	Shell completion script generation	Cobra completion command
bmo config	Curated configuration helpers	internal/cmd/config_cmd.go
bmo contract	Goal contract CRUD (governance / autopilot DB)	internal/cmd/contract.go
bmo daemon	Combined A2A + MCP server for self-deployed runtime	internal/cmd/daemon.go
bmo db	Read-only SQLite health and status utilities	internal/cmd/db_cmd.go
bmo diagnostics	Diagnostic utilities for testing and debugging (e.g. bmo diagnostics search-worker)	internal/cmd/diagnostics_search_worker.go
bmo dirs	Print config and data directory paths	internal/cmd/dirs.go
bmo donor-residue	Redacted local donor app residue mining	internal/cmd/donor_residue.go
bmo embedding	Download, inspect, and manage embedding models and indexes	internal/cmd/embedding.go
bmo enforcement	Operator-grade view and overrides for enforcement primitives (rate boundary, quarantine zone, evidence gate, capacity reservation)	internal/cmd/enforcement_cmd.go
bmo eval	Eval scenarios, reports, and shadow-eval tooling	internal/cmd/eval.go
bmo factory	Workspace-scoped Factory posture helpers	internal/cmd/factory.go
bmo fabric	Composed operator fabric dashboard readouts	internal/cmd/fabric.go
bmo findings	Workspace durable finding lifecycle (LSP/validation; not workstream review findings)	internal/cmd/findings_cmd.go
bmo host	Host saturation and co-tenant runtime status	internal/cmd/host.go
bmo service	Manage long-lived BMO service runtimes, including the Slack gateway	internal/cmd/service.go
bmo heritable-bundle	Sign / verify / extract / import heritable bundles	internal/cmd/heritable_bundle.go
bmo journal	Export or annotate the cross-subsystem journal	internal/cmd/journal.go
bmo logs	Tail the BMO log file	internal/cmd/logs.go
bmo memory	Inspect and manage persistent memory, including the operator-approve reflection queue (bmo memory reflections {pending,approve,reject})	internal/cmd/memory.go
bmo metabolism	ADM manifest validation, readiness checks, and promotion handoffs	internal/cmd/metabolism.go
bmo models	Browse and recommend models (includes bmo models recommend)	internal/cmd/models.go
bmo nanite (alias: bmo micro-run)	Background micro-runs in the separate nanite lane	internal/cmd/nanite.go
bmo ops	Operations surface (list, diagnostics, activate) — agent-native parity for the TUI Operations panels	internal/cmd/ops.go
bmo plan	Plan contract materialization (operator persistence)	internal/cmd/plan.go
bmo plugin	Install / list / update / remove plugins	internal/cmd/plugin.go
bmo preflight	Repository contract file preflights; list or run checks for touched contract files	internal/cmd/preflight_cmd.go
bmo projects	List tracked project workspaces	internal/cmd/projects.go
bmo providers	Provider diagnostics and parity helpers	internal/cmd/providers.go
bmo prune	Potentially destructive disk cleanup for stale agent artifacts	internal/cmd/prune.go
bmo quality-gate	Manual plan and prompt/recipe quality checks; use bmo config show-quality-gates for posture	internal/cmd/quality_gate.go, internal/cmd/config_show_quality_gates.go
bmo radar	Compatibility radar inspection and todo materialization	internal/cmd/radar.go
bmo recipe	Run/list/validate YAML recipes	internal/cmd/recipe.go
bmo rules	Review staged Fabric-Native Induction rule manifest proposals	internal/cmd/rules_cmd.go
bmo run	One-shot non-interactive agent run	internal/cmd/run.go
bmo runtime	Runtime diagnostics and incident capture, including runtime latency reports from redacted event files or run/run-event JSON	internal/cmd/runtime.go, internal/cmd/runtime_latency.go
bmo scaffold	Generate internal BMO repo scaffolds for new agent surfaces	internal/cmd/scaffold_agent.go
bmo schedule	Scheduler CRUD, daemon, cron help	internal/cmd/schedule.go
bmo schema	Print the configuration JSON schema	internal/cmd/schema.go
bmo acp	Start the ACP server for Zed editor integration	internal/cmd/acp.go
bmo session	Session management diagnostics, including session status budget and compaction posture	internal/cmd/session.go
bmo shell-status	Shell-related process inspection	internal/cmd/shell_status.go
bmo signal	Programmable workspace signal deposit and inspection	internal/cmd/signal.go
bmo stigmergy	Causal explanation of signal pressure, rule proposals, and stewardship guidance	internal/cmd/stigmergy_cmd.go
bmo stats	Usage and audit stats	internal/cmd/stats.go
bmo startup	Startup diagnostics, including cold-vs-warm daemon proof reports	internal/cmd/startup_proof.go
bmo team	Teams, tasks, and OCI team packages	internal/cmd/team.go
bmo tools	Inspect and invoke deterministic read-only agent tools (bmo tools call) without a model turn — used by the agent-native cross-surface parity check	internal/cmd/tools_cmd.go
bmo transcript	Export session transcript data	internal/cmd/transcript.go
bmo update-providers	Refresh provider / model metadata	internal/cmd/update_providers.go
bmo workspace-strategy	Inspect and control cross-session workspace strategy memory	internal/cmd/workspace_strategy.go
bmo workspace	Read-only workspace utilities (advisory snapshot, preflight checklist, dependency report)	internal/cmd/workspace_cmd.go
bmo workstream	List and manage workstreams (named epic context) for sessions	internal/cmd/workstream_cmd.go

Interactive and headless entrypoints

Command	Description
bmo	Start the interactive TUI agent
bmo run "<prompt>"	Run a single non-interactive prompt and exit (--operating-pack <pack> activates a session pack for that run)
bmo nanite run "<prompt>" (same as bmo micro-run run)	Nanite lane (options.nanite_max_threads, default preset nanite); bmo micro-run run is an alias. Use --session and the same data directory as the TUI to bind an existing parent for workstream last_nanite_*. Inspect with bmo workstream show <workstream-id> or bmo workstream show --session <parent-session-id>. When the parent is workstream-bound, after completion (and without --quiet) the CLI can print a line of the form workstream: … (inspect: bmo workstream show …); same phrases as bmo nanite run --help. See the Nanites behavior page for details.
bmo service start autopilot --listen 127.0.0.1:8080 --auth local	Start the composed long-lived runtime (HTTP + scheduler)
bmo service stop autopilot	Stop the managed autopilot runtime
bmo service start http --listen 127.0.0.1:8080 --auth token --token "$BMO_TOKEN"	Start the HTTP API server for programmatic access
bmo service start mcp	Start BMO as an MCP context server (stdio by default; HTTP when configured/overridden) for Zed, VS Code, and other MCP-aware editors
bmo service status gateway	Validate local Slack gateway config/store posture and show detached health metadata without contacting Slack by default
bmo service start gateway	Start the Slack DM gateway from [services.gateway]
bmo acp	Start the ACP server for Zed editor integration
bmo completion <shell>	Print shell completion scripts
bmo models recommend	Rank configured models using embedded (or --benchmark-file) benchmark scores and catalog cost hints

Agent parity boundaries

• Process lifecycle mutation is gated: bmo service start|stop|restart, bmo schedule daemon, and adjacent daemon surfaces control host long-lived processes. Agents may use status/inspection tools (daemon_status, autopilot_status, schedule_inspect) by default. Starting, stopping, or restarting long-lived processes is available only when the operator starts BMO with BMO_ENABLE_PROCESS_LIFECYCLE_TOOLS, which registers the high-risk daemon_restart, autopilot_up, and autopilot_down tools.
• Plugin management has agent parity: bmo plugin install/remove/update/list map to plugin_install, plugin_remove, plugin_update, and plugin_list. Mutating plugin operations still require approval because they change the shared plugin directory.
• Provider auth bootstrap is human-only: bmo auth <platform> opens a browser or device-code handoff and requires the user to finish auth out of band. Agents should detect auth failures and ask the user to re-authenticate, not try to drive the bootstrap themselves.
• Scenario eval run/report are CLI-only: bmo eval run and bmo eval report are local workdir/report-file flows. Agent parity is the shared eval_shadow_* tool surface, not per-run scenario execution.
• Provider catalog refresh has agent parity: bmo update-providers maps to the config tool with action: "update_providers" plus optional source and path_or_url.
• Team package parity: bmo team package pull/list/remove/update map to team_package_pull, team_package_list, team_package_remove, and team_package_update tools.
• File picker / editor parity: The agent does not expose dedicated file-picker or editor-launch tools. Use send_message, view, edit, write, and apply_patch for attachment and file-edit outcomes.

Recipes and scheduling

Command	Description
bmo recipe run <recipe>	Run a YAML recipe non-interactively
bmo recipe list	List discovered recipes
bmo recipe validate <recipe>	Validate a recipe file
bmo schedule add <id> --cron "<expr>" --recipe <path>	Add a scheduled recipe job
bmo schedule list	List all scheduled jobs with their status
bmo schedule remove <id>	Remove a scheduled job
bmo schedule pause <id>	Pause a job (keeps it in the schedule, skips execution)
bmo schedule unpause <id>	Resume a paused job
bmo schedule run-now <id>	Trigger an immediate run of a scheduled job
bmo schedule runs <id>	Show recent run history for one scheduled job (sessions is an alias)
bmo schedule cron-help	Print the cron syntax guide BMO expects
bmo schedule daemon	Run the scheduler as a long-lived daemon process

Team commands

Command	Description
bmo team list	List active agent teams
bmo team status <id>	Show team status and task details
bmo team cleanup [team-id]	Remove stale team state and persisted teammate worktrees
bmo team package pull <ref>	Pull an OCI-packaged team definition into the local cache
bmo team package list	List cached team packages
bmo team package update <ref>	Refresh a cached team package from the registry
bmo team package remove <ref>	Remove a cached team package

Project, config, and utility commands

Command	Description
bmo checkpoint create [name]	Create a session checkpoint for the most recently updated top-level session by default (--session-id overrides)
bmo checkpoint list	List checkpoints for the most recently updated top-level session by default (--session-id overrides)
bmo checkpoint restore [checkpoint-id]	Restore a checkpoint; requires both --yes and --session-id
bmo checkpoint undo	Rewind the last git commit(s)
bmo config get <key>	Read a curated configuration key
bmo config set <key> <value>	Update a curated configuration key
bmo config unset <key>	Remove a curated key (restore default)
bmo service status autopilot --source config	Print the shared autopilot service status snapshot: posture, pillars, PID files, manifest, and recent autopilot.fired events
bmo config show-config-status	Print layered-config posture plus the detached/live boundary for recent mutation target resolution and reload aftermath; pair with --json for the shared status snapshot
bmo config show-slash-status	Print slash discovery posture plus the detached config-only boundary for recent slash-routing outcomes
bmo config show-rule-files	Print metadata-only rule-file resolution status: configured context paths, active matches, agent override posture, duplicate collapse, directory expansion, memport includes, and optional omit-default suppression
bmo config show-tpm-recovery	Print TPM / provider recovery state (see TPM recovery topic). Pass --runtime before deciding whether a terminal provider_recovery warrants an outer whole-run retry/backoff; the live posture includes config flags, hop bounds, local-last-resort target host, provider cooldowns, and the recent-event ring. Pair with --json for machine-parseable output.
bmo config show-journal	Print metadata-only Journal posture: state, shared-runtime partition binding, recent ring capacity/saturation, and the action × outcome histogram. See Journal posture.
bmo config show-artifacts	Print metadata-only artifact-family posture across typed output, workflows, eval/shadow, proposals, scheduler output, and A2A protocol
bmo config show-quality-gates	Print metadata-only Quality Gates posture, armed surfaces, judge model status, and recent decision counts
bmo config show-health	Print the shared health-check posture family: explicit live-vs-detached authority, subsystem rows, sticky-holding warnings, recent-failure counts, and pointers to /health, get_health_check_status, and GET /v1/health/posture
bmo config show-prompt-stack	Print metadata-only prompt-stack posture for the current process: ring capacity, recorded builds, and recent metadata-only build rows
bmo config show-lifecycle-transitions	Print lifecycle-transition posture: config-only/live/degraded/unavailable state, durable dormant/germinated row counts, bounded lifecycle_transition.* summaries, and parity references to /lifecycle-transitions, GET /v1/lifecycle-transitions/status, and the agent/MCP twins
bmo config show-tension-system	Print the inspect-only tension-system posture: config-only/live/degraded/unavailable state, external-evidence connector posture, bounded tension.* lifecycle summaries, and next drill-in surfaces such as bmo stigmergy explain
bmo config refresh-cli-models	Refresh the CLI passthrough / cliprovider model snapshot
bmo config check	Validate the active configuration
bmo config explain	Show merge provenance for each config field (—key, —json, —all)
bmo config list	Show curated config keys and their current values
bmo auth summary	Print the redacted credential mode for the configured large model
bmo auth bedrock	Print the redacted Bedrock credential mode for the configured large model
bmo cache gemini create --model <id> -f <file>	Create a Gemini cachedContents resource and print the provider TOML line
bmo cache gemini list	List explicit Gemini cachedContents resources visible to the current API key
bmo cache gemini delete <cached-name>	Delete one explicit Gemini cachedContents resource
bmo behavior-prune export	Print the behavior-prune candidate bundle JSON to stdout
bmo dirs	Print the config and data directories BMO uses
bmo dirs config	Print only the config directory
bmo dirs data	Print only the data directory
bmo embedding status	Print the shared code-corpus embedding posture as text or JSON without starting downloads or the sidecar
bmo host status	Print host saturation, live BMO co-tenant count, and the advisory heavy-lane admission decision
bmo host admit -- <command>	Run a heavy batch command after acquiring the shared data-dir admission token; use --force for defer-notify and block-unless-force decisions (not defer-silent)
bmo projects	List known project workspaces
bmo scaffold agent --name <name>	Generate a prompt-template scaffold, prompt-test stub, and wiring snippets for a new agent id (--with-tools also creates matching tool markdown and tool registration snippets)
bmo workspace preflight	Print a workspace-snapshot-derived preflight checklist
bmo workspace deps	Print direct dependency inventory plus bounded local health probes across Go, npm, Python, and Cargo; supports JSON, CycloneDX, SPDX, and optional OSV advisory lookup
bmo donor-residue scan	Mine local donor app residue for redacted implementation crumbs; defaults to known Cursor caches/bundles/session stores and emits JSON keys, SQLite schema, and signal counts rather than raw prompt/session values
bmo plugin install <git-url>	Install a plugin from a git repository
bmo plugin list	List installed plugins
bmo plugin update <name>	Update an installed plugin
bmo plugin remove <name>	Remove an installed plugin
bmo auth copilot / bmo auth hyper / bmo auth openrouter	Browser/device-code bootstrap
bmo models	Browse available models from configured providers
bmo update-providers [path-or-url]	Refresh provider/model catalog metadata (not the BMO binary)
bmo logs	Tail the BMO log file (--tail N, --follow)
bmo stats	Show usage statistics
bmo schema	Print the JSON schema for the configuration file
bmo eval run <path>	Run Goose-compatible eval scenarios (--operating-pack <pack> applies the same pack to every scenario run)
bmo eval report <file>	View a saved eval report
bmo eval compare <before> <after>	Compare two saved eval reports and fail on regressions
bmo eval posture	Print deterministic eval-gate guidance plus bounded shadow-eval summary, stale-evidence, proposal, and arena eval_shadow posture (--json for automation)
bmo eval promotion run <path>	Run Pattern Promotion Arena scenarios and score advisory promotion payloads
bmo eval promotion score <report>	Score a saved eval report against Pattern Promotion Arena scenario metadata
bmo eval shadow summary	Print a bounded summary of recent shadow-eval quality signals
bmo eval shadow list	List captured shadow-eval artifacts and replay runs
bmo eval shadow show <artifact-id>	Show one shadow artifact with linked runs and scorecards
bmo eval shadow export	Export shadow-eval rows as JSONL or CSV
bmo eval shadow proposals list	List promotion proposals (filter by state, task-class, target-surface)
bmo eval shadow proposals get <id>	Get one proposal
bmo eval shadow proposals generate	Generate proposals from comparable passing scorecards
bmo eval shadow proposals decide <id>	Record a decision (accepted, rejected, deferred, rolled_back)
bmo eval shadow promoted list	List promoted (derived) assets
bmo eval shadow promoted get <id>	Get one promoted asset
bmo eval shadow promoted promote <proposal-id>	Promote an accepted proposal (record target ref)
bmo eval shadow promoted rollback <asset-id>	Roll back an active promoted asset

Maintained review prompts

Maintained review prompts are workspace-meta artifacts: they live outside the BMO git tree in a separate maintainer workspace. Load bodies with the view tool against paths in that workspace or open files in the TUI, then send via send_message or a normal submit. Commands and recipes still use /run or bmo recipe run. The prompt corpus is not part of the published BMO repository.

Common examples

# Run one task without the TUI
bmo run "Explain the service boundaries in this repo"

# Run with a one-off agent or prompt override
bmo run --agent task --system-prompt-prefix "Prefer terse summaries." "Summarize the current diff"

# Cap a prompt run. If combined with --preset, the explicit cap wins.
bmo run --max-turns 2 "Summarize the current diff"

# Smoke-test one configured provider/model without tool access.
# Uses openai_chat, chat mode, JSON output, and no staged-workflow prompt by default.
bmo run --profile provider-smoke --model openrouter/openai/gpt-4o-mini "Reply with exactly: provider-ok"

# Discover loaded models for a NIM deployment.
bmo models discover openai-compat --profile nim

# Discover installed models in a local Ollama daemon.
bmo models discover ollama

# Run once under a session operating pack
bmo run --operating-pack packs/observability-diagnostics/pack.toml "Summarize the current diff"

# Inspect the operating-pack gate, discovery, presets, and redacted posture
bmo config show-operating-mode --session-id sess-123

# Inspect artifact-family posture without reading artifact bodies
bmo config show-artifacts --json

# Start a local-only background automation surface
bmo service start autopilot --listen 127.0.0.1:8080 --auth local

# Stop the managed autopilot runtime
bmo service stop autopilot

# Manage schedules
bmo schedule add nightly-tests --cron "0 0 2 * * *" --recipe recipes/nightly.yaml
bmo schedule runs nightly-tests

# Inspect shadow-eval captures and export comparable runs
bmo eval shadow summary
bmo eval shadow list --agent-type coder
bmo eval shadow export --format csv --comparability comparable

# Compare two deterministic eval reports
bmo eval compare before.json after.json

# Run and score Pattern Promotion Arena scenarios
bmo eval promotion run eval/scenarios/pattern-promotion --tag semantic-ready
bmo eval promotion score pattern-promotion-eval.json --scenarios eval/scenarios/pattern-promotion

# A/B a deterministic eval suite under two operating packs
bmo eval run scenarios/ --operating-pack packs/collaborator-narrowing/pack.toml --output before.json
bmo eval run scenarios/ --operating-pack packs/observability-diagnostics/pack.toml --output after.json
bmo eval compare before.json after.json

Shadow eval filters

The bmo eval shadow commands share a small filter vocabulary:

• Summary: summary supports --limit and optional --json for machine-readable output
• Artifacts/runs: list supports --limit, --session-id, --agent-type, --route-source, --artifact-id, --status, --candidate-model, and --comparability; show takes one artifact-id; export supports --format jsonl|csv and the same run filters as list
• Proposals: proposals list supports --limit, --proposal-id, --state, --task-class, --target-surface; proposals decide takes --outcome, --reviewer, --rationale. Proposal records are append-only audit artifacts; there is no delete/archive command.
• Promoted assets: promoted list supports --limit, --asset-id, --proposal-id, --state, --target-type; promoted promote takes --target-type, --target-id, --version-ref, --activated-by; promoted rollback takes --rationale

See Shadow Evals for the capture model, replay behavior, proposals, and promoted assets.

Session notes

• Resume or switch sessions from the TUI with /session.
• The root CLI does not provide a global --session flag.

Workstream commands

Workstreams are stable named rows in the local BMO database. Sessions attach to a workstream so tooling can group context across sessions. Use bmo workstream for CRUD; use bmo preflight repo --workstream <id> to persist preflight results against a workstream.

Git hints (advisory): a workstream may store optional git_branch and worktree_path metadata (epic-level; not proof that the repo is on that branch or that the path is a worktree). Set with bmo workstream set-git or the HTTP API. Per-session branch_name may still differ; attaching a session can copy the workstream branch when the session has no branch set. Implementation notes: Workstream git facet on GitHub.

Headless subcommands that mutate session attachment require --session; there is no implicit active session outside the interactive TUI.

With bmo service start http --auth token --token "$BMO_TOKEN" authenticated API access, GET /v1/workstreams and GET /v1/workstreams/{id} return roi_mission_id, git_branch, and worktree_path when set, and after a nanite run finishes with a workstream-attached parent session, optional last_nanite_at, last_nanite_status, last_nanite_child_session_id, last_nanite_agent_id, and last_nanite_excerpt (omitted when unset; same shape as the MCP workstream list tool). To enqueue a nanite (same lane as bmo nanite run) over HTTP, use POST /v1/sessions/{id}/nanite with {"prompt":"...","preset":""}; MCP clients use opt-in bmo_nanite_enqueue (see MCP Server). PATCH /v1/workstreams/{id} accepts any combination of:

• {"roi_mission_id":"..."} — set or update the ROI mission link; {"roi_mission_id":""} clears (same as bmo workstream set-roi-mission).
• {"git_branch":"..."} and {"worktree_path":"..."} — set strings; null or "" clears a field. Omitted fields are unchanged (partial update).

Command	Description
bmo workstream list	List all workstreams
bmo workstream create --label <name>	Create a new workstream
bmo workstream from-issue <issue-ref>	Preview or --apply a deterministic branch/worktree/workstream plan from a GitHub issue reference
bmo workstream pr-review	Preview or --apply a GitHub PR comment/review mutation for the current branch PR or an explicit --pr reference
bmo workstream pr-summary	Render deterministic PR-ready markdown from the current branch; --create-pr opens a GitHub PR and can infer #issue + title from issue/<n>-slug branches
bmo workstream verify-git <id>	Verify the stored workstream branch/worktree facet against the current checkout and registered git worktrees
bmo workstream show [id]	Show a workstream by id, or pass --session <id> to look up by session (includes git / worktree when set)
bmo workstream use <id> --session <s>	Attach a session to a workstream
bmo workstream clear --session <s>	Detach a session from its workstream
bmo workstream delete <id> --yes	Delete a workstream (sessions’ workstream_id becomes NULL)
bmo workstream set-plan <id>	Bind a plan path / ref kind / skill id to a workstream (--clear to remove)
bmo workstream set-roi-mission <id> <mission>	Bind an ROI mission id to a workstream (--clear to remove)
bmo workstream set-git <id>	Set or clear git_branch and/or worktree_path (--branch, --worktree, --clear, --clear-branch, --clear-worktree)
bmo workstream sync-roi	One-shot copy of roi_mission_id between a session and its linked workstream (--session, --to-workstream or --to-session)
bmo workstream findings list <id> [--open]	List durable workstream-scoped review findings
bmo workstream findings add <id> --file <path> --title <t>	Add one review finding (--severity, --line, --body, and --status optional)
bmo workstream findings resolve <id> <finding-id>	Mark a finding resolved, accepted_risk, or duplicate with an optional note
bmo workstream findings delete <id> <finding-id> --reason <text>	Delete one finding and record an audit reason
bmo workstream findings import <id> --file <path.json>	Import a JSON array of review findings
bmo workstream findings deletions <id>	List the deletion audit log (deleted findings and their recorded reasons) for a workstream
bmo workstream verify-run <id> <cmd> [args]	Run a shell command and record exit code + elapsed time on the workstream (not available on Windows)
bmo workstream verify-record <id>	Manually record a verification result (exit code, duration, excerpt) on a workstream

Workspace finding lifecycle commands

When options.finding_lifecycle.enabled is true, bmo findings reads durable workspace-scoped rows (LSP diagnostics and verify-run validation failures). This is not bmo workstream findings, which stores human/agent review rows on a workstream.

Command	Description
bmo findings list [--open] [--json] [--limit N]	List durable workspace findings (newest activity first); default table on stdout

Requires -D / data dir and a configured project like other app-backed commands. Use bmo workstream findings … for review-finding CRUD on a workstream id.

Scripting: exit codes and streams

Most commands return 0 on success and 1 on failure via the root exitCodeFromError helper (internal/cmd/root.go). Exceptions scripts should know about:

Exit code	Command family	Meaning
0	all	Success
1	most	Generic failure (validation, I/O, agent error)
2	bmo journal …	Validation error (unknown --filter, bad --format, missing --session on export)
3	bmo journal export	Partition fail-closed (shared-capable runtime without mesh.partition_id)

Journal codes 2 and 3 are signaled via journalExitFn in internal/cmd/journal.go (message on stderr, then process exit). Other commands return typed errors to Cobra instead of calling os.Exit directly.

Streams (defaults):

• stdout — machine payloads (--json, --format, export bodies) and human tables when not redirected
• stderr — debug logs (-d), bmo run --verbose slog, startup progress bar on TTY, journal validation lines
• stdin — bmo run, bmo nanite run, and recipe paths prepend piped stdin when stdin is not a TTY (MaybePrependStdin in internal/cmd/root.go)

For JSON piping from bmo run, use --output-format=json with --quiet and without --verbose so stderr stays quiet.

bmo run --max-turns <n> applies to direct prompt runs. It is rejected with --recipe; recipe runs must set their turn budget in recipe settings. Build budget presets fill missing direct-run budget fields, but an explicit --max-turns or runtime cap on the command line remains authoritative for that prompt invocation.

Machine-readable output flags

Most commands share helpers in internal/cmd/cli_format.go:

Pattern	Example commands	Values / notes
--format + --json	config list, schedule list, preflight repo, findings list, session list, workstream findings …, signal …	--format is text or json (default varies by command); --json is shorthand for --format=json
--format (multi-value)	journal export, transcript export, contract get, workspace deps	Allowed set per command (md/json, text/json/cyclonedx/spdx, etc.); --json shorthand when json is allowed
--output-format / -o + --format + --json	bmo run	Primary selector is --output-format (text stream or json at end); --format aliases it; --json shorthand for JSON
JSON only (no flag)	bmo workstream evidence <id>	Always indented JSON on stdout

Read bmo <cmd> --help for the allowed --format values on that command.

Export commands may also take --out <path> (openCmdOutput in internal/cmd/output.go): empty means stdout, otherwise truncating file write.

Global flags

Flag	Description
-d, --debug	Enable verbose debug logging
-y, --yolo	Automatically accept all permission prompts
-c, --cwd	Override the working directory
-D, --data-dir	Override the data directory; relative paths resolve against the working directory
-v, --version	Print the BMO version