Authentication

Two methods

Method	When
OAuth	Interactive use — you're sitting at a terminal and want a browser flow
API key (bk_*)	Cron, CI, agent pipelines, anything non-interactive

OAuth login

betterness auth login

Opens a browser window. After consent, tokens are saved to ~/.betterness/tokens.json. They auto-refresh when expired.

API key login

Generate a key in the Console, then:

betterness auth login --key bk_your_key_here

Stored in ~/.betterness/credentials.json. Logging in with one method clears the other — only one auth is active at a time.

Verify

betterness auth whoami

Returns your name, email, and Betterness account ID. If this fails, your credentials are missing or expired.

Logout

betterness auth logout

Override per command

# Use a specific key for one call
betterness profile get --api-key bk_other_key

# Or via env var (useful in CI)
export BETTERNESS_API_KEY=bk_your_key
betterness profile get

Resolution order

1. --api-key flag (highest priority)
2. BETTERNESS_API_KEY environment variable
3. OAuth tokens from ~/.betterness/tokens.json
4. Stored API key from ~/.betterness/credentials.json

Common errors

Symptom	Cause	Fix
401 Unauthorized	No credentials or expired	betterness auth whoami to check; re-login
403 Forbidden	Key lacks scope for that tool	Generate a wider-scope key or update the consent grant in the Console
Browser doesn't open	Headless / SSH session	Use --key flow with an API key instead

Next

Run your first query.