> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/okikorg/orca-cli); this page is the machine contract.

## Install

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
orca doctor --json     # array of {name, status, message, fix?}; --strict promotes warnings
```