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

# orca auth, login, whoami, and context

> Sign the CLI in, inspect the stored credential, and switch between named contexts.

> **Last updated: 2026-09-06**

`orca auth` signs the CLI in and manages the stored key; `orca login` is a top-level alias for `orca auth login`. `orca whoami` asks the server who the stored key acts as. `orca context` switches between named CLI contexts, each of which pairs an API URL with a key (not to be confused with the platform's [session contexts](/concepts/contexts)). This page is the command reference; the narrative guide, including how flags, environment variables, the config file, and the baked-in defaults take precedence, lives at [Authentication](/cli/authentication).

Every subcommand accepts the [global flags](/cli/reference/overview#global-flags). `orca context use` opens an interactive picker when the name is omitted in a terminal; in a pipe or script the name is required (exit code 2).

## Config file

The CLI stores contexts in one JSON file. The directory is resolved in this order:

1. `$ORCA_CONFIG_DIR`, when set.
2. `$XDG_CONFIG_HOME/orca`, when `XDG_CONFIG_HOME` is set and non-empty.
3. `~/.config/orca`.

The file is `config.json` inside that directory. Every save creates the directory with mode `0700` and writes the file with mode `0600` (re-applied on each save, since the key lives in it). On non-Windows platforms a file readable by group or other prints a `chmod 600` warning on every load; `orca doctor` reports the same condition as a failing check.

```json theme={"dark"}
{
  "currentContext": "default",
  "contexts": {
    "default": {
      "apiUrl": "https://api.orcapods.ai",
      "dashboardUrl": "https://app.orcapods.ai",
      "gatewayUrl": "https://...",
      "apiKey": "ao_...",
      "keyId": "key_..."
    }
  }
}
```

All fields of a context are optional. `keyId` is the server-side id of the key minted by `orca auth login`, stored so `orca auth logout --revoke` can delete it; it is absent when the key was pasted or passed with `--with-token`. A context is selected with `--context <name>` or `ORCA_CONTEXT`, falling back to `currentContext`, then `default`. Outside of `orca auth login`, naming a context that is not in the file is a usage error (exit code 2) unless `ORCA_API_KEY` and `ORCA_API_URL` are both set, which makes the file irrelevant.

## orca auth login

```bash theme={"dark"}
orca auth login [--api-url <url>] [--dashboard-url <url>] [--gateway-url <url>] [--label <label>] [--with-token <token>] [--headless] [--browserless] [--no-browser]
orca login  # identical flags and behavior
```

Signs the CLI in by obtaining a tenant API key and saving it to the selected context, which also becomes `currentContext`. Passing `--context <name>` for a name that is not in the file creates that context, which is how a second context (for example a self-hosted conductor) is set up. `orca login` registers the identical option surface and action. The API URL comes from `--api-url` (the login flag or the global one), then `ORCA_API_URL`, then the context file, then the baked-in production default `https://api.orcapods.ai`; when none of those resolve, a terminal prompts for it and a script exits 2. URLs must start with `http://` or `https://`.

| Flag                    | Type    | Default                                                                     | Description                                                                                                                                         |
| ----------------------- | ------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--api-url <url>`       | string  | see above                                                                   | Conductor API base URL                                                                                                                              |
| `--dashboard-url <url>` | string  | `ORCA_DASHBOARD_URL`, then the context file, then `https://app.orcapods.ai` | Dashboard base URL; needed only by the browser flow                                                                                                 |
| `--gateway-url <url>`   | string  | unchanged                                                                   | Public chat gateway base URL, saved to the context for `orca chat`                                                                                  |
| `--label <label>`       | string  | `<prefix>-<user>@<host>`                                                    | Label for the minted key, shown in the dashboard. The prefix is `cli`, or `claude-code`, `cursor`, `ci`, or `ssh` when that environment is detected |
| `--with-token <token>`  | string  | none                                                                        | Use this API key; skips the login flow entirely (for CI)                                                                                            |
| `--headless`            | boolean | `false`                                                                     | Use the device-code flow: print a code and URL, approve on any device                                                                               |
| `--browserless`         | boolean | `false`                                                                     | Alias for `--headless`                                                                                                                              |
| `--no-browser`          | boolean | browser flow on                                                             | Same as `--headless` (kept for compatibility)                                                                                                       |

The flow is chosen in this order:

1. **`--with-token`**: no flow at all. The token is used as given.
2. **Device code**: when `--headless`, `--browserless`, or `--no-browser` is passed, when stdin or stdout is not a TTY, or when a coding-agent, CI, or SSH environment is detected (`CLAUDECODE` or `CLAUDE_CODE`, `CURSOR_TRACE_ID`, `CI`, `SSH_CONNECTION` or `SSH_TTY`). The CLI calls `POST /api/device/code` with the key label, prints the one-time code and verification URL on stderr, and polls `POST /api/device/token` until the code is approved in the dashboard, denied (exit code 3), or expires (exit code 1; the code is valid for 15 minutes). A conductor that answers 404 does not support device login; pass `--with-token` instead.
3. **Browser loopback** (the default in a terminal): the CLI binds an ephemeral port on `127.0.0.1`, opens `<dashboard-url>/cli-auth` in the browser, and waits up to five minutes for the dashboard to post the minted key back. While waiting it also accepts a key pasted directly into the terminal. On timeout it falls back to a masked paste prompt; Ctrl-C exits 130. This flow requires a dashboard URL (exit code 2 without one).

In every flow the key is verified with a read of `GET /api/profiles` before it is saved, so a bad key fails with exit code 3 and nothing is written. A key without the `ao_` prefix prints a warning but is still accepted.

```bash theme={"dark"}
orca login
orca login --headless --label build-box
orca login --with-token "$ORCA_API_KEY" --api-url https://conductor.example.com
```

With `--json` the final output is a single object: `context`, `apiUrl`, `apiKey` (masked), `role`, `org`, `keyId`, and `stored` (the config file path). `role`, `org`, and `keyId` are `null` when the flow did not deliver them (a pasted key or `--with-token`). In the device-code flow, one NDJSON line is written to stdout first, before polling starts, so a script can surface the code immediately:

```json theme={"dark"}
{"event":"device_code","userCode":"BCDF-GHJK","verificationUri":"https://app.orcapods.ai/cli-auth","verificationUriComplete":"https://app.orcapods.ai/cli-auth?code=BCDF-GHJK","expiresIn":900,"interval":5}
```

The final login object follows on its own line once the key is approved.

## orca auth status

```bash theme={"dark"}
orca auth status
```

Shows the active context and verifies that its key works with a read of `GET /api/profiles`. Fails with exit code 3 when the context has no API URL or no key. Values that came from a baked-in production default rather than a flag, environment variable, or the config file are marked `(default)`.

```bash theme={"dark"}
orca auth status --json
```

With `--json` the output is `context`, `apiUrl`, `gatewayUrl`, `dashboardUrl`, `apiKey` (masked), `defaults` (the list of fields that fell through to a baked-in default), and `valid: true`. Plain (piped) output is labeled lines for the context, API URL, gateway, dashboard, and masked key.

## orca auth logout

```bash theme={"dark"}
orca auth logout [--revoke] [--yes]
```

Removes the stored API key and key id from the selected context in the config file; other fields (URLs) are kept. Without `--revoke` the key stays valid on the server. With `--revoke`, the key is first deleted with `DELETE /api/api-keys/<keyId>`; this is best-effort, so an unreachable server or an already-deleted key prints a warning and the local key is cleared anyway. When the context has no stored `keyId` (a pasted key), `--revoke` warns and clears locally only.

| Flag       | Type    | Default | Description                                             |
| ---------- | ------- | ------- | ------------------------------------------------------- |
| `--revoke` | boolean | `false` | Revoke the key on the server before clearing it locally |
| `--yes`    | boolean | `false` | Skip the confirmation prompt for `--revoke`             |

Unlike other destructive commands, `--revoke` without `--yes` in a script does not refuse: the prompt is skipped and the revoke proceeds. This command always prints text; `--json` has no effect.

```bash theme={"dark"}
orca auth logout --revoke --yes
```

## orca whoami

```bash theme={"dark"}
orca whoami
```

Asks the server who the stored key acts as with `GET /api/whoami`: the tenant id and name, the role, the credential kind (`api_key`, `session`, or `run_token`), and the key id. Fails with exit code 3 when the context has no API URL or no key. Against a conductor that predates `/api/whoami` (404), the CLI instead verifies the key with a read of `GET /api/profiles` and reports the local context with the server fields unknown.

```bash theme={"dark"}
orca whoami --json
```

With `--json` the output is `context`, `apiUrl`, `apiKey` (masked), `tenantId`, `tenantName`, `role`, `authKind`, `keyId`, and `serverSupportsWhoami`. The server-sourced fields are `null` (and `serverSupportsWhoami` is `false`) on the 404 fallback; `keyId` then falls back to the value stored in the context, if any.

## orca context list

```bash theme={"dark"}
orca context list
```

Lists the contexts in the config file, sorted by name, marking the current one. Reads the file only; no request is made.

```bash theme={"dark"}
orca context list --json
```

With `--json` the output is an array of `{ "name", "current", "apiUrl", "gatewayUrl", "hasKey" }`. Plain (piped) output is one tab-separated row per context: `*` for the current context (else empty), `name`, `apiUrl` (or `-`), masked key (or `-`). An empty config prints a hint on stderr and nothing on stdout.

## orca context use

```bash theme={"dark"}
orca context use [name]
```

Sets `currentContext` in the config file. A name that is not in the file is a usage error (exit code 2), as is an empty config. This command always prints text; `--json` has no effect.

```bash theme={"dark"}
orca context use staging
```

## orca context show

```bash theme={"dark"}
orca context show
```

Shows the effective context after environment overrides are applied (`ORCA_API_URL`, `ORCA_API_KEY`, `ORCA_GATEWAY_URL`, `ORCA_DASHBOARD_URL`), so it works in environment-only setups with no config file. Values that fell through to a baked-in default are marked `(default)`. A context with nothing set explicitly (no key and only default URLs) is reported as not configured (exit code 2). No request is made.

```bash theme={"dark"}
orca context show --json
```

With `--json` the output is `name`, `apiUrl`, `gatewayUrl`, `dashboardUrl`, `apiKey` (masked or `null`), and `defaults`. Plain (piped) output is labeled lines for the context, API URL, gateway, dashboard, and masked key.

<Note>
  Verified against orca-cli `cli-v0.5.0`.
</Note>