Skip to main content
Last updated: 2026-09-06
orca runs inspects and controls runs, the individual executions of an agent. Starting a run is orca run, documented on orca run and orca chat. Every subcommand accepts the global flags. Subcommands that take an optional [id] open a picker over the 10 most recent runs when the id is omitted in a terminal; in a pipe or script the id is required (exit code 2). Exit codes are listed on Output and scripting.

​
orca runs list

Lists recent runs. With --agent the request goes to that agent’s own runs endpoint, so the paging total reflects only its runs.
Plain (piped) output is one tab-separated row per run: id, agent, status, started, duration (- while the run is still running). --json prints an array of run summaries (id, subTask, status, startedAt, finishedAt). A run status is one of running, ok, error, cancelled, or interrupted. When there are no runs, stdout stays empty and a hint goes to stderr.

​
orca runs get

Shows one run with its full event transcript. With --json the full run object is printed, including its events. The plain view prints Run, Agent, Title, Status, Started, and Duration (once finished), then one line per event, then a Tokens line that sums the run’s usage events.

​
orca runs cancel

Cancels an in-flight run. There is no confirmation prompt. A tail attached to the run ends with status cancelled and exit code 1.

​
orca runs tail

Attaches to a run’s event stream and follows it until the run reaches a terminal status. The stream replays buffered events first, so tailing a finished run prints its whole transcript. A dropped connection reconnects with backoff and skips events already delivered, so nothing prints twice; a rejected subscription (bad key, unknown run) fails immediately. In a terminal the tail renders a live transcript with a final status line (status, run id, elapsed time, token usage). When stdout is a pipe, each event is one plain text line: assistant text as is, tool <name> <input> for a call, its result indented beneath it (prefixed error when the tool failed), error: <message> for run errors, and progress or result messages; usage events never print. In both non-terminal modes a run <id> finished: <status> line goes to stderr. With --json every run event is written to stdout as one JSON object per line (NDJSON). Each line has a type of progress, result, error, assistant, tool_call, tool_result, or usage, plus whichever of message, ts, toolCallId, toolName, input, output, isError, and usage apply to that type. A usage object carries inputTokens, outputTokens, cacheReadTokens, and cacheCreateTokens.
The exit code follows the run’s terminal state: 0 for ok, 1 for error, cancelled, or interrupted. Ctrl-C detaches the tail only (exit code 130); the run keeps going server-side, and stderr prints the commands to reattach (orca runs tail <id>) or stop it (orca runs cancel <id>).
Verified against orca-cli cli-v0.5.0.