CLI Authentication

The RevKeen CLI supports interactive OAuth (PKCE or device grant) for humans, and API keys for scripts and CI. Secrets prefer the OS keyring, with a ~/.revkeen/credentials.toml (mode 0600) fallback. Non-secret settings live in ~/.revkeen/config.toml.

Credential precedence

The CLI resolves credentials in this order:

1. --api-key flag (for a single invocation)
2. REVKEEN_API_KEY environment variable
3. API key / OAuth token from keyring or credentials.toml / config.toml

The CLI does not have its own role. Interactive OAuth uses the signed-in member's team role. API keys use that key's scopes intersected with the same team-role grants as the Dashboard. Empty scopes grant nothing.

Option 1 — OAuth PKCE (recommended for local interactive use)

revkeen login
# or
revkeen auth login

This runs OAuth 2.1 authorization-code + PKCE (S256) against Better Auth:

1. The CLI binds a loopback listener on http://127.0.0.1:<port>/callback
2. It opens (or prints) /api/auth/oauth2/authorize as public client cli_revkeen
3. You sign in and approve consent in the browser
4. The CLI exchanges the code at /api/auth/oauth2/token and stores the access token

Resource commands send Authorization: Bearer <access token> to the Engine API (rkoa_* OAuth access tokens).

revkeen login --no-browser   # print authorize URL only; still waits on loopback
revkeen auth status
revkeen auth logout          # clears stored credentials

Option 2 — OAuth device grant (SSH / Codespaces / headless)

revkeen login --device
revkeen login --device --no-browser

RFC 8628 device flow against /api/auth/device/code and /api/auth/device/token. Approve the user code on the dashboard /device page. Today this path stores a Better Auth session bearer (BA 1.6.x); the PKCE path issues OAuth access tokens.

Option 3 — API key (recommended for scripts & CI)

API keys start with rk_live_ (production) or rk_sandbox_ (staging).

revkeen login --api-key
# or
revkeen config set api-key rk_live_your_api_key
export REVKEEN_API_KEY=rk_live_your_api_key
revkeen --api-key rk_live_your_api_key customers list

Option 4 — Token from env / stdin

REVKEEN_ACCESS_TOKEN=rkoa_... revkeen login --with-token
echo 'rk_live_...' | revkeen login --with-token

Values starting with rk_ (except rkoa_) are treated as API keys; otherwise they are stored as OAuth bearer tokens.

Targeting staging

The CLI defaults to production (https://api.revkeen.com). Resource commands call the /v2 API prefix automatically.

revkeen config set environment staging
revkeen config set base-url https://staging-api.revkeen.com

Machine / agent mode

Use --agent (or --json) so the CLI never opens Huh forms or the Bubble Tea dashboard and always emits JSON suitable for tools and LLMs.

CI usage

Prefer API keys over interactive OAuth in CI:

- name: List invoices
  env:
    REVKEEN_API_KEY: ${{ secrets.REVKEEN_API_KEY }}
  run: revkeen invoices list --json

Security guidance

• Use sandbox keys for development; reserve live keys for production operations.
• Prefer environment variables or a secret manager over copy-paste on shared machines.
• Credentials files are written with owner-only permissions — keep them that way.
• Only approve device codes and consent screens on a device you control.
• Rotate keys regularly from the RevKeen dashboard and avoid echoing them into logs.

See also