CLI overview

orca is the command-line surface for the Orca Framework runtime: submit a workflow, follow an execution, step in when something needs a person. This page covers what holds for every verb, and which of the other eight pages answers a given question.

Which page do I want

You want to	Page
Start the daemon, mount a topology, shut it all down	Lifecycle
See which devices, locations and workflows are loaded	Inspect
Submit a workflow and wait for it to finish	Run
Find where a plate is, or what is in it	Monitor
Work out why a thread is not moving	Monitor
Pause, resume, close or stop an execution	Control
Skip, insert or replace a method inside a running thread	Control
Correct where the system thinks a plate is	Control
Send a command straight to a device by hand	Control
Change a grip height, a teachpoint or an arm default	Control
Decide what happens to a thread paused on an error	Recover
Handle a device command that overran its timeout	Recover
Read who changed what, and why	Forensics
Read everything that happened to one plate	Forensics
Push workflow or topology code to a hosted deployment	Deploy

orca 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. See Runtime.
• 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 an Orca AI deployment instead. The source-available build ships no cloud backend, so there --backend cloud exits 2 with no cloud backend is installed. topology mount and workflow load check their argument first: with --backend cloud they expect a source file, and a module:function spec gets that error instead. The exit code is still 2.

In the CLI, orca execution thread ... operates on a labware thread, the subject of Threads.

Grammar

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

Six verbs sit at the top level: start, shutdown, unload, status, version and run. Everything else is a noun followed by a verb.

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

topology mount takes a --sim flag, and it is not a run mode. It turns on the daemon's sim diagnostics and marks the mount; which world a workflow reaches is decided per submission by orca run --run-mode. See the --sim flag on a mount.

orca --help lists what is visible in the current installation. orca <noun> --help lists the verbs under a noun. orca <noun> <verb> --help shows its flags.

The nouns

Noun	What it covers
execution	Executions, their threads, and thread-level surgery. Holds the execution thread sub-app.
submission	Multi-group and batched submissions against a workflow. See Submissions.
workflow / method / thread / location	Template and location inventory. workflow load and method execute also live here.
describe	One-screen detail for a named system, workflow, method, thread, location or device.
device	Device inventory, capabilities, lifecycle and direct invocation. Holds the device registry sub-app.
labware	Labware instances, the labware-definition catalog, and operator overrides on both. See Labware.
teachpoints	Per-transporter teachpoints. Holds the teachpoints labware sub-app for per-labware exceptions at one position.
deck-layouts	Per-liquid-handler deck layouts.
access-configs	Deployment-wide access configs.
grip-profiles	How each labware type is held. See Move parameters.
move-defaults	What one transporter's moves start from.
var	Global, execution-scope and submission-scope variables. See Variables.
reservation	Resource reservations: list and cancel.
manual-step	Operator manual steps: list and confirm.
incident	Non-action error records. Holds the incident recoverable-timeout sub-app.
state	state unsettled: everything nobody has settled, and the operation that settles each. See State.
audit	The audit trail of confirmed dangerous actions.
ops-history	The per-execution operations archive plus cross-execution search.
topology	Mount, read and delete the deployment topology.
runtime	Runtime status and reload.
module	Read and delete deployment-package module source.
worktree	Browse the on-disk deployment_package worktree.

What --help shows

Hiding is a help-rendering decision only. Every verb stays invokable on both backends; one that cannot work on the resolved backend fails clean and tells you which backend it needs.

• Hidden when the backend is cloud: var, reservation, submission, teachpoints, access-configs, deck-layouts, thread, location, describe.
• Hidden when the backend is local: module, worktree, and the two cloud-only verbs topology delete and runtime reload.

The rule mirrors backend resolution, with one exception: when nothing at all resolves the backend, both sets stay visible because the operator has not picked a side yet.

Install and 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 is installed; no daemon required.

Global flags

Parsed by the root callback. Work on every verb.

Flag	Effect
--json	JSON on stdout instead of tables (one object per line for streaming verbs).
--quiet / -q	Suppress stdout. Only the exit code matters.
--force / --yes / -y	Skip confirmation prompts. Verbs that require --reason still require it.
--no-color	Disable ANSI. Sets NO_COLOR for the process.
--verbose	Print full tracebacks on errors.
--backend local|cloud	Pick the control plane. See backend resolution below.
--system-module SPEC	Legacy loader spec. Accepted and ignored; the daemon owns system loading.

Status and error lines always go to stderr, so --quiet and --json never swallow them.

Backend resolution

The CLI talks to one of two backends:

• local: the orca.daemon running on 127.0.0.1.
• cloud: an Orca AI deployment over REST.

Precedence (first match wins):

1. --backend local|cloud flag.
2. ORCA_BACKEND=local|cloud env var.
3. ~/.orca/config.json, top-level "backend" key.
4. Auto-detect.

Auto-detect probes the loopback daemon and the cloud credentials together. Cloud credentials set with no daemon answering gives cloud; a daemon answering GET /health gives local. If neither holds, the CLI exits 10 and prints both setup paths.

There is no silent cross-backend fallback. Asking for cloud without ORCA_CLOUD_URL and ORCA_CLOUD_API_KEY exits 2 rather than dialing the daemon, and asking for local with no daemon running exits 10 rather than dialing the cloud.

Output shapes

Three modes, picked by global flag:

• Table (default): Rich tables and key-value blocks on stdout, status on stderr.
• --json: One JSON document on stdout, or one compact object per line for streaming verbs. Use this in scripts.
• --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, or a verb pointed at the wrong backend.
10	NOT_CONNECTED	No daemon running, no backend resolved at all, or the connection dropped mid-request. A dropped request may or may not have completed.
20	NOT_FOUND	Entity (execution, labware, incident) does not exist.
21	AMBIGUOUS	ID prefix matched more than one entity.
30	CONFLICT	State conflict, for example mounting a topology while one is already mounted or still mounting.
31	INVALID_STATE	The target is not in a state where this verb applies.
40	CONFIRMATION_DENIED	Operator declined the prompt, or stdin is not a TTY and --force was not passed.
50	TIMEOUT	A deadline elapsed: run --wait, the start health probe, or a daemon request that got no answer in time. A timed-out request may still complete, so run orca status before retrying.
60	PLUGIN_ERROR	A registered plugin (for example a cloud backend) failed to load.

Errors that come back from the daemon map by HTTP status: 400 to 2, 404 to 20, 409 to 30, everything else to 1.

ID prefixes

Long UUIDs are annoying. Verbs that take an execution, thread, submission, labware, incident or reservation id accept an unambiguous prefix of at least 4 characters:

orca execution detail 7a3f
orca incident get 90b2

Shorter than 4 characters exits 2. Zero matches exits 20. Two or more matches exits 21 and lists the matching ids.

Execution ids also accept the literal last, which resolves to the most recent execution this CLI submitted. It is cached in ~/.orca/last.json, so it survives across shell sessions on the same machine.

orca execution detail last

Confirmation and --reason

Every mutation the runtime exposes carries a danger level, and the CLI picks its prompt from that level.

Level	Prompt
SAFE	None. Reads and idempotent calls.
OPERATOR	y/N, defaulting to no.
CRITICAL	Type a phrase verbatim, for example stop 7a3f1c0e. Mutates a running execution.
PHYSICAL	Type the phrase. Can move hardware or overwrite calibration.

Every confirmed call at any level is written to the audit trail, whichever surface made it.

--force (--yes, -y) skips the prompt at every level. Without a TTY and without --force, a prompt-carrying verb exits 40 rather than hanging.

--reason is a separate requirement from the danger level. Some actions demand a written justification that lands in the audit trail, and --force does not waive it: forcing without a reason exits 2. These verbs require --reason STR today:

Verb	Level
labware edit-location	PHYSICAL
labware reset-location	PHYSICAL
labware set-volume	PHYSICAL
labware set-tips	PHYSICAL
labware mark-tips-used	PHYSICAL
device release-hold	PHYSICAL
execution thread skip-method	CRITICAL
execution thread abort-method	CRITICAL
execution thread insert-method	CRITICAL
execution thread replace-method	CRITICAL
execution thread skip-action	CRITICAL
execution thread insert-action	CRITICAL
execution thread replace-action	CRITICAL
reservation cancel	CRITICAL
incident recoverable-timeout abort	CRITICAL
incident recoverable-timeout mark-complete	CRITICAL

PHYSICAL verbs that are not in that list still prompt for the typed phrase. orca audit list reads the trail back.

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 is loaded.
3. Run: submit a workflow and track an execution.
4. Monitor: mid-flight inspection: where is every plate, who is 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 plus the operations 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.

See also

• Installation: how orca gets onto the machine.
• Lifecycle: the first verbs of any session, in the order you run them.
• Runtime: what the CLI is driving, and the same operations from Python.
• Submissions: groups, batching and run modes, behind orca run.
• Glossary: every term these pages use.