CLI for agents

The orca CLI’s machine contract: JSON everywhere, NDJSON streams, stable exit codes, env-only auth.

The orca CLI was built to be driven by scripts and agents, not just humans. Full reference lives in the okikorg/orca-cli README; this page is the machine contract.

Install

curl -fsSL https://orcapods.ai/install.sh | sh

Standalone binary (macOS and Linux, arm64 and x64), no Node required, SHA256-verified, installed to ~/.local/bin.

Output contract (gh-style)

• --json on any command: machine-readable JSON on stdout. Nothing else is ever printed to stdout in this mode.
• Streaming commands (orca runs tail, orca chat) emit NDJSON: one JSON object per line, exiting when the stream ends.
• Without --json, a non-TTY stdout gets plain tab-separated lines; a TTY gets rich output.
• All errors and hints go to stderr.

Exit codes

Code	Meaning
0	ok
1	failure (API or network, or a tailed run that ended error or cancelled)
2	usage (bad arguments, missing input in non-interactive mode)
3	auth (401, 403, no key configured)
4	not found
130	interrupted

Zero-config CI

No config file needed:

ORCA_API_KEY=... orca agents list --json

Contexts (orca context use prod) live in ~/.config/orca/config.json, kubectl-style; ORCA_CONTEXT selects one per invocation. Precedence everywhere: flag, then environment, then config file, then baked-in production defaults.

Golden path

orca login                                        # device flow when headless
orca whoami --json
orca agents create -f agent.yaml --json
orca run my-agent "do the thing" --json --detach  # prints run id, exits
orca runs tail <runId> --json                     # NDJSON until terminal
orca billing wallet --json

Health

orca doctor --json     # array of {name, status, message, fix?}; --strict promotes warnings