Skip to main content

Mid-flight inspection

Once one or more executions are running, these verbs answer the three operator questions: where is every plate, who's holding what device, what variables are in scope.

All read-only. Won't change runtime state.

Where is every plate?​

orca labware list                          # every instance the runtime knows about
orca labware where <id-or-prefix>          # current location of one plate
orca labware history <id>                  # location history for one plate
orca labware journey <id>                  # moves + actions merged (full UUID required)

ID prefixes work — first 8 hex chars resolve as long as they're unique.

labware list​

ID              TYPE              LOCATION              EXECUTION    BARCODE
7a3f1c0e        cor96_falcon      shaker_01             7a3f1c0e     PLT-001
b29e0411        cor96_falcon      stacker_01[slot=3]    7a3f1c0e     PLT-002
9d8c33ee        tip_300_l         ml_star.deck.A1       —            —

Labware without an execution column (—) is deck-resident — defined in the topology, not spawned by a thread.

labware where​

$ orca labware where 7a3f1c
labware 7a3f1c0e on shaker_01 since 0:00:42 ago (thread sample_journey, in seal_step)

When the daemon doesn't know an ID locally (e.g. swarm-managed labware not in the local cache), where falls through to the cloud backend if one is configured — you get the same answer either way.

labware history​

A chronological list of every location change for one plate. Useful when a plate ended up somewhere unexpected.

TIMESTAMP                LOCATION              EVENT                ACTOR
2026-05-26 14:00:00      stacker_01[3]         initial              system
2026-05-26 14:00:12      shaker_01             move (sample_journey)transporter:robotic_arm
2026-05-26 14:00:45      sealer_01             move (sample_journey)transporter:robotic_arm

labware journey​

Same as history but merges in the actions that ran AT each location (e.g. "shake 30s @ 500rpm" between move-in and move-out). Works against both backends. Requires a full labware UUID (there is no list-instances endpoint to resolve a prefix against on every backend).

Who's holding what?​

orca reservation list --execution <exec-id>    # active reservations within one exec
orca reservation list --all                    # every active reservation across execs

Reservations are the engine's locking mechanism — every device, location, transporter, and method-scope shared resource is reserved before use and released after.

ID              THREAD_ID           LOCATION
r-8f2a1c0e      sample_journey      shaker_01
r-1c94b220      tips_journey        ml_star
r-33de7741      (transit)           robotic_arm

--all is cross-execution and prepends an EXECUTION column. Default scope is a single --execution.

Pitfalls​

  • Reservation wait times are normal and can be long. A shaker holding a 2-hour incubation will keep its reservation for the full duration. A long-held reservation does NOT mean a deadlock.
  • --all with many concurrent executions is verbose. Pipe through grep or use --json + jq to filter.

What variables are in scope?​

orca var list --execution <exec-id>           # variables visible to one execution
orca var list --all                           # cross-execution scope
orca var get <key> --execution <exec-id>      # one value

Three scopes, evaluated in order: per-execution override → deployment global → workflow VariableDefinition default.

KEY                 SCOPE          VALUE             SOURCE
plate_count         execution      4                 set via --vars at submit
reagent_batch       global         L7                set 2 days ago
shake_speed         default        500               from @orca.workflow VariableDefinition

get returns just the value (or --json for the full shape, including which scope answered):

$ orca var get plate_count --execution 7a3f1c0e
4

Omitting --execution on var list/var get defaults to the last execution in your CLI session (the CLI prints a hint when it does this).

Pitfalls​

  • --all includes globals. Use --execution <id> if you want only per-execution overrides without globals.
  • A variable that isn't defined anywhere returns EXIT_NOT_FOUND (20). The CLI doesn't fall through to a string default.