Skip to main content
Last updated: 2026-09-06
orca is the command-line client for Orca. It covers the whole tenant surface the dashboard exposes: agents, runs, sessions, workflows, pools, skills, MCP servers, secrets, storage, memory, API keys, and billing. It is a single standalone binary with no Node.js dependency, and it is built to be driven by scripts and coding agents as comfortably as by people.

Installation

One-line installer, pinning a version, updating, and uninstalling.

Authentication

Browser and device-code login, API keys in CI, contexts for multiple tenants.

Output and scripting

JSON and NDJSON output, exit codes, pagination, and pipeline patterns.

Command reference

Every command, flag, and default.

​
Five minutes to a running agent

1

Install

Installs a checksum-verified binary to ~/.local/bin/orca. See Installation for other options.
2

Sign in

Opens the dashboard in your browser and stores a tenant API key in ~/.config/orca/config.json. On a machine with no browser, orca login --headless prints a one-time code instead. See Authentication.
3

Check the connection

whoami shows which tenant and role the stored key acts as. doctor runs connectivity and configuration checks and prints a fix for anything it finds.
4

Create an agent

Write an agent document:
agent.yaml
Then create it:
5

Run it

The run streams to your terminal until it finishes. Add --detach to print the run id and return immediately, then attach later with orca runs tail <id>.

​
How commands are organized

orca --help groups commands the same way this reference does. Every command takes the same three global flags: --json for machine-readable output, --context <name> to pick a saved context, and --api-url <url> to point at a different conductor. Details are in the reference overview.

​
Built for automation

The CLI follows the conventions of gh and kubectl:
  • --json on any command prints only JSON to stdout. Streaming commands emit NDJSON, one event per line.
  • When stdout is not a terminal, list commands print tab-separated rows with no header, so cut, awk, and grep work without flags.
  • Hints, warnings, prompts, and errors always go to stderr.
  • Exit codes are stable: 0 ok, 1 failure, 2 usage, 3 auth, 4 not found, 130 interrupted.
  • ORCA_API_KEY in the environment is enough to run in CI with no config file.
The same binary also runs an MCP server (orca mcp serve) that exposes the control plane to Claude Code, Cursor, Codex, and any other MCP client. See MCP server and the orca mcp reference.

​
Source and releases

The CLI is open source at github.com/okikorg/orca-cli. Binaries for macOS and Linux (arm64 and x64) and Windows (x64) are published on the releases page. This documentation is verified against cli-v0.5.0.