Orcho CLI Reference for Operators

This map is maintained against the current argparse surface; orcho <command> --help is always authoritative. Running bare orcho prints the grouped quick help.

Run

orcho run executes one project as an inspectable delivery pipeline: plan → implement → review/repair → final QA → evidence.

orcho run --project ./api --task "Add health endpoint" --profile feature --output live
orcho run --project ./api --task-file add-login-validation.md --no-interactive
orcho run --resume            # bare: resume the latest run

Flag	Meaning
--project, -p	Project directory to run against. Optional on --resume.
--task, -t / --task-file	Task text, or a .md file; bare NAME.md resolves from .orcho/.task-files. Mutually exclusive.
--profile	Work kind: auto-detect, feature, small_task, complex_feature, planning, delivery_audit, code_review, research, refactor, migration, or a custom installed profile. Required for fresh non-interactive runs.
--mode	Verification strictness: fast, pro, or governed. Overrides the profile’s default mode; governed is opt-in only.
--session-mode	How implement and repair share agent session state: auto, stateless, chain, hybrid.
--session-split PHASE=SPLIT	Per-run override of a phase’s prompt-session split (stateless, per_phase, per_role, common). May repeat.
--max-rounds N	Maximum implement/review/repair rounds per project (default: 1).
--no-interactive	Never prompt on stdin; fall through to a resumable pending-decision state (MCP / CI / UI transports).
--resume [RUN_ID]	Resume an existing run, skipping completed phases. Bare --resume or latest picks the most recent run.
--from-run-plan RUN_ID_OR_DIR	Start a new run that inherits a parent run’s parsed plan and starts at implement. Mutually exclusive with --resume.
--decision TARGET=DECISION	Override an operator-decision target (e.g. contract_check=run). May repeat.
--decision-feedback TEXT	Free-form feedback attached to a single --decision.
--dry-run	Print intent without running agents.
--mock	Use mock agents: no real API calls.
--workspace, -w	Workspace directory. Falls back to $ORCHO_WORKSPACE / cwd discovery.
--output-dir	Run output directory. Defaults to the active workspace run dir.
--output / --stream-output	Transcript mode; see Output modes.

On a fresh interactive run without --profile, a TTY shows a work-kind picker with auto-detect as the first entry. On --resume / --from-run-plan the profile defaults to the persisted meta.profile; an explicit --profile switches deliberately.

Per-phase models and runtimes

Flag	Meaning
--model	Default implementation model.
--model-plan / --model-implement / --model-review-changes / --model-repair-changes	Per-phase model override.
--runtime-plan / --runtime-implement / --runtime-review-changes / --runtime-repair-changes	Per-phase runtime override: claude, codex, or gemini.

Attachments

Flag	Meaning
--attach PATH	Attach a file as prompt context; kind auto-detected. May repeat.
--attach-text PATH	Force TEXT kind regardless of extension.
--attach-image PATH	Force IMAGE kind (.png / .jpg / etc.). Runtime support may vary.
--attach-binary PATH	Force BINARY kind (passthrough; runtime decides handling).

Cross-project

orcho cross keeps one feature coherent across multiple projects: cross-plan → per-project runs → contract check → evidence. It shares the run flags above (task input, run control, workspace/resume, output, models, attachments) plus:

orcho cross --task "Add telemetry" --projects api:./api web:./web --profile feature
orcho cross --task "Add telemetry" --projects api:./api web:./web --mode plan

Flag	Meaning
--projects, -p	Project aliases and paths, e.g. api:./api web:./web. Optional on --resume.
--mode	full = run end-to-end; plan = stop after writing the plan (cross_plan.json + cross_plan.md).
--plan-file	Pre-existing cross_plan.json (the canonical JSON, not the .md render), typically from a prior --mode plan run.
--profile	Work kind with cross policy. Non-interactive fresh runs require it.

Read Cross-project mode before making this your first multi-project delivery path.

Observe a run

All observation commands accept --workspace and default to the latest run when run_id is omitted (except diff, which requires it).

Command	Job	Key flags
orcho status [RUN_ID]	Status of the latest or a specific run.	--verbose, -v for full session JSON.
orcho history	List recent runs.	--last, -n (default: 10).
orcho metrics [RUN_ID]	Token/time metrics: single-run detail, or history.	--last, -n (default: 10).
orcho evidence [RUN_ID]	Compose the v1 evidence bundle (plan + phases + gates + commands + artifacts + metrics + errors).	--format json|md, --out DIR (writes evidence.json + evidence.md), --diff [preview|stat|full], --debug.
orcho diff RUN_ID	Print the run’s captured diff.patch artifact.	--full (default, raw patch), --preview, --stat, --path PATH, --max-bytes N, --no-color.

orcho evidence --format md
orcho evidence --format json --diff stat
orcho diff 20260514_120000 --preview
orcho diff 20260514_120000 | git apply --check

evidence --diff augments stdout: a ## Diff section in markdown, or a {"evidence": ..., "diff": ...} wrapper in JSON. --out always writes the canonical schema-validated bundle regardless of --diff. diff --full output is colorless so it stays pipeable to git apply.

Economics

Command	Job	Key flags
orcho cost	API-equivalent cost report over a sliding window of runs.	--window, -w (30d / 7d / 24h / all; default 30d), --top, -n (default: 5).
orcho pricing show	Print the effective pricing table (user override + snapshot).	—
orcho pricing refresh	Scrape a public pricing source into ~/.orcho/pricing.local.toml.	--provider openai|pricepertoken, --dry-run.

--provider openai scrapes the official pricing page (fragile parser); pricepertoken is a third-party aggregator with a more reliable scrape but not authoritative. Verify the written rates either way.

Verification

orcho verify runs the project’s declared verification contract against a run and persists receipts under the run directory.

Command	Job	Key flags
orcho quality-gates	Inspect the normalized scheduled-gate matrix without executing commands.	--profile, --paths, --project (default: current directory).
orcho verify list	Print each declared command with its env, required marker, and placeholder-resolved run text. Executes nothing.	--project, -p, --run-id, --workspace, -w.
orcho verify run [NAMES...]	Execute declared verification commands in the run worktree; one command-receipt each.	--name NAME, --required, --include-manual, --project, -p, --run-id, --workspace, -w.
orcho verify env	Execute one verification_env’s assertions and write an env-receipt.	--env (default: contract’s default_env), --project, -p, --run-id, --workspace, -w.

With no names, verify run runs the normal declared commands, excluding manual/operator opt-in commands; --include-manual restores the full sweep and --required runs exactly the contract’s required set. Failing checks exit 1; resolution errors (project/run mismatch, unknown command) exit 2 with nothing written.

Workspace

Command	Job
orcho workspace init [PROJECT_OR_GROUP]	Connect an existing project in place, or initialize an explicit shared workspace for a project group. Defaults to the current directory.
orcho workspace fine-tune [PROJECT_DIR]	Inspect a project by its repo markers and print a candidate verification contract. Read-only.

cd ~/www/my-project
orcho workspace init

# Advanced shared product workspace:
orcho workspace init ~/work/my-product

workspace init flags: --workspace-name (logical name, default MCP server suffix), --mcp-config PATH (create or merge a .mcp.json; omitted = snippet printed only), --mcp-server-name NAME, --orcho-mcp-command CMD (default: orcho-mcp on PATH), --force (continue without a detected runtime and replace a conflicting MCP entry), --workspace-dir PATH (override the managed workspace location for a project), --dry-run, --no-interactive (skip the undetected-folder prompt in CI), and --no-scaffold (skip extension-point scaffold files).

A project target is registered in place and receives an external deterministic managed workspace. A non-project directory creates workspace-orchestrator/ below that root and discovers child repositories for the shared topology. See Workspace model.

Catalogues

Command	Job
orcho profiles list	List available execution profiles with kind, variant, phase steps, and [internal] chips.
orcho workflows list	Same catalogue through the workflow lens.
orcho prompts --list	List all available core prompts; add --project DIR to include project/workspace overrides and show the winning layer.
orcho prompts NAME	Show the resolution chain for one prompt (e.g. tasks/build); --verbose prints the resolved template contents.

Maintenance

orcho repair-state RUN_ID diagnoses a run’s durable state against its event-derived projection and, with --apply, safely heals known torn shapes. Dry-run is the default; nothing is written. It refuses to flip an active, undecided handoff. --json emits a single JSON object instead of the text report.

orcho repair-state 20260514_120000          # inspect only
orcho repair-state 20260514_120000 --apply  # apply the proposed repair

Output modes

--output applies to run and cross. The default is configurable via cli.output_mode in config.local.json or the ORCHO_OUTPUT_MODE env var.

Mode	Behavior
summary	Compact progress, default.
live	Summary plus live agent transcript; best first UX.
debug	Live plus trace/vdump/full previews.

--stream-output is an alias for --output live; --verbose / -v is an alias for --output debug. When multiple output-mode flags are present, the last one on the command line wins.

Deep reference

The canonical engineering doc lives with the code:

• docs/user/02_commands.md — the in-repo command guide

Related

• Configuration reference
• Profile reference
• Artifact reference
• Event stream reference
• Workspace model
• Unattended runs and CI
• Cross-project mode