> ## 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 overview

> The orca command-line tool: install it, sign in, and create and run agents from the terminal.

> **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.

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/cli/installation">
    One-line installer, pinning a version, updating, and uninstalling.
  </Card>

  <Card title="Authentication" icon="key" href="/cli/authentication">
    Browser and device-code login, API keys in CI, contexts for multiple tenants.
  </Card>

  <Card title="Output and scripting" icon="terminal" href="/cli/output-and-scripting">
    JSON and NDJSON output, exit codes, pagination, and pipeline patterns.
  </Card>

  <Card title="Command reference" icon="book" href="/cli/reference/overview">
    Every command, flag, and default.
  </Card>
</CardGroup>

## Five minutes to a running agent

<Steps>
  <Step title="Install">
    ```bash theme={"dark"}
    curl -fsSL https://orcapods.ai/install.sh | sh
    ```

    Installs a checksum-verified binary to `~/.local/bin/orca`. See [Installation](/cli/installation) for other options.
  </Step>

  <Step title="Sign in">
    ```bash theme={"dark"}
    orca login
    ```

    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](/cli/authentication).
  </Step>

  <Step title="Check the connection">
    ```bash theme={"dark"}
    orca whoami
    orca doctor
    ```

    `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.
  </Step>

  <Step title="Create an agent">
    Write an [agent document](/cli/agent-documents):

    ```yaml agent.yaml theme={"dark"}
    name: researcher
    runtime: vercel
    model: anthropic:claude-sonnet-4-6
    systemPrompt: |
      You are a research assistant. Be concise and cite sources.
    tools: ["@default", "web_search", "web_extract"]
    ```

    Then create it:

    ```bash theme={"dark"}
    orca agents create -f agent.yaml
    ```
  </Step>

  <Step title="Run it">
    ```bash theme={"dark"}
    orca run researcher "Summarize the three most cited papers on retrieval-augmented generation."
    ```

    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>`.
  </Step>
</Steps>

## How commands are organized

`orca --help` groups commands the same way this reference does.

| Group   | Commands                                                                                 | What they do                                                       |
| ------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Core    | `run`, `chat`, `agents`, `runs`                                                          | Define agents, start runs, stream output, talk to published agents |
| Observe | `stats`, `usage`, `sessions`, `doctor`, `topology`, `bundles`, `apps`                    | Metrics, spend, session history, health checks, platform inventory |
| Manage  | `workflows`, `pools`, `skills`, `mcp`, `secrets`, `storage`, `memory`, `keys`, `billing` | Everything an agent depends on, plus keys and billing              |
| Setup   | `auth`, `login`, `whoami`, `context`, `update`                                           | Credentials, contexts, and the CLI itself                          |

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](/cli/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](/agents/mcp) and the [orca mcp reference](/cli/reference/mcp).

## Source and releases

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