Authentication and contexts

Last updated: 2026-09-06

The CLI authenticates with a tenant API key (an ao_ token, see API keys). The tenant and role come from the key; there is no separate tenant flag. orca login mints a key for you through the dashboard and stores it locally. In CI you skip the login and supply a key through the environment.

Signing in

orca login

orca login and orca auth login are the same command. It picks one of three flows:

Browser (default)
Device code
Token

In an interactive terminal on a machine with a browser, the CLI binds a loopback port on 127.0.0.1, opens https://app.orcapods.ai/cli-auth with a one-time state value, and waits for the dashboard to post the minted key back. Sign in, confirm the request, and the key lands in the CLI without ever appearing on screen.If the callback does not arrive within five minutes, the CLI falls back to a masked paste prompt so you can copy the key from the dashboard by hand. Ctrl-C exits with code 130.

orca login --headless

The CLI asks the conductor for a device code and prints it with a verification URL:

First, copy your one-time code: BCDF-GHJK
Then open: https://app.orcapods.ai/cli-auth?code=BCDF-GHJK
Waiting for approval... (expires in 15 minutes, Ctrl-C to cancel)

Open the URL on any device, sign in, check that the code matches, and approve. The CLI polls until the key is issued. Codes are single-use and expire after 15 minutes.This flow is selected automatically, without --headless, whenever the terminal is not interactive or the CLI detects a coding agent, CI, or SSH session (CLAUDECODE, CURSOR_TRACE_ID, CI, SSH_CONNECTION, or SSH_TTY in the environment). --browserless and --no-browser are accepted as synonyms.With --json, the first stdout line is an NDJSON event carrying the code, the verification URL, and the expiry, so a script or agent can relay it; the final login record follows once approved.

orca login --with-token ao_live_...

No browser, no prompt. The CLI verifies the key against the API and stores it. Use this when you already have a key, for example one minted in the dashboard under Settings, then API Keys, or by orca keys create on another machine.

Every flow verifies the key against the API before saving it, and every flow accepts these flags:

Flag	Description
`--label <label>`	Name for the minted key as shown in the dashboard. Defaults to `cli-<user>@<host>`, or `claude-code-<user>@<host>` and similar when a coding agent is driving the login
`--api-url <url>`	Conductor API base URL. Defaults to `https://api.orcapods.ai`
`--dashboard-url <url>`	Dashboard base URL for the browser flow. Defaults to `https://app.orcapods.ai`
`--gateway-url <url>`	Public chat gateway base URL used by `orca chat`
`--with-token <token>`	Supply a key directly and skip the login flow
`--headless`, `--browserless`, `--no-browser`	Force the device-code flow

The minted key inherits the role of the user who approved it. The approval screen shows the key label, so you can see which terminal or agent asked.

Checking who you are

orca whoami
orca auth status
orca doctor

whoami asks the server which tenant, role, and key the stored credential resolves to. auth status shows the local view: the active context, its URLs, and a masked key, and verifies the key against the API. doctor runs a full set of connectivity and configuration checks and prints a fix for each problem it finds.

Where credentials live

Credentials and contexts are stored in one JSON file:

~/.config/orca/config.json

The directory is created with mode 0700 and the file with 0600; the CLI re-applies 0600 on every save and warns on load if the file is readable by other users. The location follows ORCA_CONFIG_DIR if set, otherwise $XDG_CONFIG_HOME/orca, otherwise ~/.config/orca.

{
  "currentContext": "default",
  "contexts": {
    "default": {
      "apiUrl": "https://api.orcapods.ai",
      "dashboardUrl": "https://app.orcapods.ai",
      "apiKey": "ao_live_...",
      "keyId": "key_01J..."
    }
  }
}

keyId is the server-side id of the minted key, recorded so orca auth logout --revoke can revoke it. It is absent when the key was pasted or passed with --with-token.

Contexts

Contexts work like kubectl contexts: each holds a key and the URLs for one tenant or one deployment, and one of them is current. Use them to switch between organizations, or between the hosted platform and a self-hosted conductor.

orca login --context staging --api-url https://conductor.staging.example.com
orca context list
orca context use staging
orca context show

orca login writes into the context named by --context (or ORCA_CONTEXT), creating it if needed, and makes it current. context use switches the current context; context show prints the effective configuration after environment overrides, marking values that came from baked-in defaults. For one command at a time, pass --context <name> or set ORCA_CONTEXT.

Precedence

Every setting resolves in the same order, per field:

A command-line flag (--api-url, --context)
An environment variable
The current context in the config file
The baked-in production default

Variable	Overrides
`ORCA_API_KEY`	The tenant API key
`ORCA_API_URL`	Conductor API base URL
`ORCA_CONTEXT`	Which context is used
`ORCA_DASHBOARD_URL`	Dashboard URL for the browser login flow
`ORCA_GATEWAY_URL`	Public chat gateway URL for `orca chat`
`ORCA_CHAT_KEY`	Chat key for `orca chat` (a published-agent key, not a tenant key)
`ORCA_TENANT`	Tenant id (`org_...`) the agent was published under, for `orca chat`
`ORCA_CONFIG_DIR`	Config directory
`ORCA_NO_UPDATE_CHECK`	Set to any value to disable the update hint on `orca --version`
`ORCA_ASCII`	Set to `1` to force ASCII glyphs in terminal output
`NO_COLOR`	Disables color, per the no-color.org convention
`GITHUB_TOKEN`	Used for GitHub API calls made by `orca update` and the update check

Contexts that predate cli-v0.5.0 may hold the old raw Railway hostname as apiUrl. The CLI transparently treats that exact value as https://api.orcapods.ai and rewrites it on the next login; custom URLs are never touched.

CI and other headless environments

No config file is needed. Set the key in the environment and every command works:

export ORCA_API_KEY=ao_live_...
orca agents list --json
orca run deployer "Roll out build 4211" --json --detach

ORCA_API_URL is only required for self-hosted or local conductors. When both ORCA_API_KEY and ORCA_API_URL are set, a --context name that does not exist in the config file is accepted rather than rejected, so the same script runs on a developer machine and in CI. Mint a key for a pipeline from a machine that is already signed in:

orca keys create ci-deploy --expires 2027-01-01T00:00:00Z

The token is printed exactly once. When stdout is a pipe, only the token is written, so CI_KEY=$(orca keys create ci-deploy) captures it cleanly. See the orca keys reference.

Signing out

orca auth logout            # forget the key locally
orca auth logout --revoke   # revoke it on the server first, then forget it

--revoke asks for confirmation in a terminal; add --yes to skip the prompt in scripts. If the server-side revoke fails, the CLI warns and still clears the key locally. Errors on a missing or rejected credential are consistent: no key configured exits 3 with the hint Run: orca auth login or Or set ORCA_API_KEY; a 401 or 403 from the API also exits 3. See exit codes.

For the agent-oriented summary of these flows, see Headless authentication.

Using the CLI

Command reference

Authentication and contexts

Signing in

Checking who you are

Where credentials live

Contexts

Precedence

CI and other headless environments

Signing out

​Signing in

​Checking who you are

​Where credentials live

​Contexts

​Precedence

​CI and other headless environments

​Signing out

Signing in

Checking who you are

Where credentials live

Contexts

Precedence

CI and other headless environments

Signing out