CLI overview

orca is the operator surface for the Orca Framework runtime. It ships with the framework, so installing Orca Framework brings it in. Every operation the runtime exposes (submit a workflow, pause an execution, recover from an incident, send a raw command to a device) has a verb here.

The CLI is one of three control surfaces, all driven by the same operation set:

• In-process Python API: SystemRuntime calls from your own service code.
• Local daemon REST + SSE: orca.daemon on 127.0.0.1.
• orca CLI: what this section documents.

Everything below talks to the local daemon over its REST API. With --backend cloud (or ORCA_BACKEND=cloud) the same verbs route to a Swarm deployment instead.

Grammar

orca <lifecycle-verb> [args...]      # version, start, status, unload, shutdown, run
orca <noun> <verb>    [args...]      # topology mount, workflow load, execution, labware, device, ...

A "system" comes up in two steps: orca topology mount <module:build_topology> builds the instrument foundation, then orca workflow load <module:build_workflow> registers a workflow on it. There is no single orca load verb.

orca --help lists everything in the current installation. orca <noun> --help lists verbs under a noun. orca <noun> <verb> --help shows flags + examples.

Install + verify

Orca Framework ships the orca CLI. See Installation for the access-gated install steps, then verify:

orca version

version is a no-side-effect sanity check. It prints whatever's installed; no daemon required.

Global flags

Parsed by the root callback. Work on every verb.

Flag	Effect
--json	NDJSON instead of tables. Stable schema — same shape across CLI / REST / MCP.
--quiet / -q	Suppress stdout. Only the exit code matters.
--force / --yes / -y	Skip confirmation prompts on destructive verbs. PHYSICAL-danger verbs still require --reason.
--no-color	Disable ANSI. Honors the NO_COLOR env var as well.
--verbose	Print full tracebacks on errors.
--backend local|cloud	Pick the control plane. See backend resolution below.

Backend resolution

The CLI talks to one of two backends:

• local — the orca.daemon running on 127.0.0.1.
• cloud — a Swarm deployment via REST.

Precedence (first match wins):

1. --backend local|cloud flag.
2. ORCA_BACKEND=local|cloud env var.
3. ~/.orca/config.json "backend" key.
4. Auto-detect: loopback daemon reachable → local; otherwise → cloud (requires ORCA_CLOUD_URL + ORCA_CLOUD_API_KEY).

Cloud-only verbs are hidden from --help when running local-only, but stay invokable. The hiding rule mirrors auto-detect — --backend cloud shows them, --backend local hides them, env wins over auto-detect.

If nothing resolves the CLI exits with code 10 and tells you what to set.

Output shapes

Three modes, picked by global flag:

• Table (default) — Rich tables on stdout, status on stderr.
• --json — One JSON object on stdout (or one per line for streaming verbs). Use this in scripts. Schema is stable across CLI / REST / MCP.
• --quiet — Nothing on stdout. The exit code is the channel.

Exit codes

Stable contract. Scripts can switch on these.

Code	Name	Meaning
0	OK	Verb succeeded.
1	GENERIC	Something failed; check stderr.
2	USAGE	Bad flag, bad value, missing required argument.
10	NOT_CONNECTED	No daemon running, or no cloud creds.
20	NOT_FOUND	Entity (execution, labware, incident) doesn't exist.
21	AMBIGUOUS	ID prefix matched more than one entity.
30	CONFLICT	State conflict (e.g. submission to a non-ACCEPTING execution).
31	INVALID_STATE	The target isn't in a state where this verb applies.
40	CONFIRMATION_DENIED	Operator declined the confirmation prompt, or non-TTY without --force.
50	TIMEOUT	--wait deadline elapsed; nothing was actually aborted.
60	PLUGIN_ERROR	A registered plugin (e.g. cloud backend) failed to load.

ID prefixes

Long UUIDs are annoying. Labware, incident, and submission verbs accept the first 8 hex chars as a prefix:

orca labware where 7a3f1c
orca incident get 90b2

Two matches → exit 21 with the ambiguous-set listed. Zero matches → exit 20.

--reason and danger levels

Destructive verbs are classified by danger:

• OPERATOR — confirmable, recoverable. --force / --yes skips the prompt.
• PHYSICAL — operator must pass --reason STR. The reason becomes part of the audit trail. --force / --yes skips the interactive confirm prompt but does NOT skip --reason — it's a required option, so there's no way to make a PHYSICAL change without telling the system why.

Examples of --reason-required verbs: labware edit-location, labware reset-location, labware set-volume, execution thread skip-method, execution thread abort-method, execution thread insert-method, execution thread replace-method, reservation cancel, incident recoverable-timeout abort.

Reading order

The pages in this section walk the order an operator actually hits them:

1. Lifecycle: bring the daemon and a system up. Tear them down.
2. Inspect: read-only inventory of what's loaded.
3. Run: submit a workflow and track an execution.
4. Monitor: mid-flight inspection: where is every plate, who's holding what.
5. Control: operator interventions: pause, resume, skip, insert, set variables, override labware location, send raw device commands.
6. Recover: incident triage: acknowledge, decide retry/skip/abort, panic chain.
7. Forensics: audit log + execution history archive.
8. Deploy: the hosted code-repository surface (push, module, worktree, reload) plus typed reads and runtime status that work on both backends.

A typical first session is overview → lifecycle → inspect → run. Everything past that is reach-for-it-when-needed.