The orca CLI was built to be driven by scripts and agents, not just humans. This page is the machine contract in one screen; the full documentation lives in the CLI section and the command reference.
Install
Standalone binary (macOS and Linux, arm64 and x64), no Node required, SHA256-verified, installed to ~/.local/bin. Details: Installation.
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 run, orca runs tail, orca workflows 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.
- Optional positionals that open a picker for humans are required in a non-TTY (exit 2). Destructive commands need
--yes in a non-TTY (exit 2).
Exit codes
0 ok, 1 failure (API or network, or a tailed run that ended in any status other than ok), 2 usage, 3 auth (401, 403, no key configured), 4 not found, 130 interrupted. Full table: Output and scripting.
Zero-config CI
No config file needed:
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. Details: Authentication and contexts.
Golden path
Health
Prefer MCP when you can
The same binary runs an MCP server: orca mcp serve. It exposes the control plane as typed tools and reuses the CLI’s credentials, so a coding agent does not need to shell out at all. See MCP server.
Next
Build it with your coding agent puts these commands in order: the ask, the two files, the create, the test, and the loop that fixes whatever the test finds. Last modified on September 6, 2026
