orca auth, login, whoami, and context

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). 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. Every subcommand accepts the 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:

$ORCA_CONFIG_DIR, when set.
$XDG_CONFIG_HOME/orca, when XDG_CONFIG_HOME is set and non-empty.
~/.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.

{
  "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 [--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:

--with-token: no flow at all. The token is used as given.
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.
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.

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:

{"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

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

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

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.

orca auth logout --revoke --yes

orca whoami

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.

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

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.

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

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.

orca context use staging

orca context show

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.

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.

Verified against orca-cli cli-v0.5.0.

Using the CLI

Command reference

orca auth, login, whoami, and context

Config file

orca auth status

orca auth logout

orca whoami

orca context list

orca context use

orca context show

​Config file

​orca auth login

​orca auth status

​orca auth logout

​orca whoami

​orca context list

​orca context use

​orca context show

Config file

orca auth login

orca auth status

orca auth logout

orca whoami

orca context list

orca context use

orca context show