Output and scripting

Last updated: 2026-09-06

Every orca command decides how to print based on two things: whether --json was passed, and whether stdout is a terminal. The rules never vary by command, so a script that works with one command works with all of them.

Output modes

Mode	When	What stdout carries
JSON	`--json` is set	Pretty-printed JSON, and nothing else
Plain	stdout is not a terminal	Tab-separated rows, no header, no color
Terminal	stdout is a terminal	Tables and panels with color and hints

Plain mode follows the gh convention: one record per line, fields separated by a tab, in a fixed column order documented on each command’s reference page. Nothing needs stripping before cut, awk, or grep sees it.

orca agents list | cut -f1              # names only
orca runs list --agent researcher | awk -F'\t' '$3 == "error"'

Hints, warnings, progress, prompts, and errors always go to stderr, in every mode. Redirect 2>/dev/null if you want a silent pipeline; stdout stays parseable either way.

JSON

--json works on every command that reports something, including login, doctor, and update. The two exceptions are auth logout and context use, which print a short text confirmation regardless.

Lists print a JSON array of records (the page you asked for, or every record with --all).
Single-resource commands print one object.
Mutations print the updated record where the API returns one, or a small confirmation object such as { "name": "researcher", "deleted": true }.
Interactive pickers and confirmation prompts are never shown in JSON mode; a missing argument is a usage error instead.

orca agents get researcher --json | jq -r .model
orca sessions list --all --json | jq 'length'

Streams (NDJSON)

Commands that follow a live run print newline-delimited JSON under --json: one event object per line, flushed as it arrives, until the stream reaches a terminal state.

orca runs tail "$RUN_ID" --json | while read -r event; do
  echo "$event" | jq -r '.type'
done

Streaming commands: orca run (unless --detach), orca runs tail, orca workflows tail, and orca chat. The device-code login also emits one NDJSON event under --json before its final result, see Authentication.

Exit codes

Code	Meaning
`0`	Success. For a tailed run, the run finished with status `ok`
`1`	Failure: an API error, a network error, a server-side 5xx, or a tailed run that finished with any status other than `ok`
`2`	Usage: bad arguments, an invalid flag value, a missing positional in non-interactive mode, an invalid agent document, or a destructive command without `--yes` in a script
`3`	Authentication: no API key configured, or the API returned 401 or 403
`4`	Not found: the API returned 404 for a named resource
`130`	Interrupted with Ctrl-C. Interrupting a tail detaches it only: the run keeps going server-side, and the error names the `runs tail` and `runs cancel` commands to reattach or stop it

Errors print as orca: <message> on stderr, followed by indented detail lines where there is a fix to suggest:

orca: no API key configured for context "default"
  Run: orca auth login
  Or set ORCA_API_KEY.

Pagination

List commands share one set of paging flags:

Flag	Default	Description
`--limit <n>`	`10`	Page size
`--offset <n>`	`0`	Page offset
`--all`	off	Fetch every page. Cannot be combined with `--limit` or `--offset`

When more records exist than the page shows, terminal and plain modes print Showing X of Y on stderr. --all walks the collection in windows of 200 (the server’s per-request cap) and stops at 10,000 records with a warning; narrow the query if you hit that. Commands with their own paging: orca agents changes caps client-side with --limit (unlimited by default), orca storage ls defaults to 100 and orca storage browse to 1000 (both max 1000), orca memory list has its own --limit and --offset, and orca keys list does not page.

Interactive versus scripted

The CLI decides it is interactive when both stdin and stdout are terminals. That switches three behaviors:

Optional positionals such as orca agents get [name] or orca runs tail [id] open a picker when omitted in a terminal. In a script they are required, and omitting one exits 2.
Destructive commands (delete, remove, rm, unpublish, keys revoke, workflows cancel, billing cap set) confirm in a terminal. In a script, pass --yes or the command refuses with exit 2. The exceptions are runs cancel and agents keys revoke, which never prompt, and auth logout --revoke, which proceeds without --yes in a script.
Prompts that read values, such as orca secrets set without --value, read from stdin when it is a pipe and show a hidden prompt when it is a terminal.

orca login follows the same rule: no terminal means the device-code flow.

Patterns

Start a run, do other work, then collect the result.

RUN_ID=$(orca run researcher "Draft the changelog" --detach)   # stdout is only the run id
# ...
orca runs tail "$RUN_ID" --json > events.ndjson
orca runs get "$RUN_ID" --json | jq -r .status

With --json, --detach prints the full create response instead, including runId and sessionId. Fail a CI job when the agent fails. orca run and orca runs tail exit 1 when the run ends in any status other than ok, so no parsing is needed:

orca run release-checker "Verify build $BUILD_ID" || exit 1

Capture a minted key without exposing it. Key-minting commands print only the token to a piped stdout:

CHAT_KEY=$(orca agents keys create support-bot --label website)

Create an agent from a template.

sed "s/{{ENV}}/production/" agent.tmpl.yaml | orca agents create -f - --json

Run the same script locally and in CI. Keep ORCA_API_KEY in CI secrets and rely on orca login locally. Flags beat environment variables, which beat the config file, so nothing in the script needs to change between the two. Feed a coding agent. The MCP server built into the CLI gives Claude Code, Cursor, and Codex the same control plane as typed tools, without shelling out. For agents that do shell out, the --json contract above is the whole interface; see CLI for agents.

Using the CLI

Command reference

Output and scripting

Output modes

JSON

Streams (NDJSON)

Exit codes

Interactive versus scripted

Patterns

​Output modes

​JSON

​Streams (NDJSON)

​Exit codes

​Pagination

​Interactive versus scripted

​Patterns

Output modes

JSON

Streams (NDJSON)

Exit codes

Pagination

Interactive versus scripted

Patterns