Authentication

There are two ways to authenticate the CLI: an interactive browser login for everyday use, and long-lived personal access tokens (PATs) for CI and unattended scripts.

Browser login

brainbase login opens the web app, connects this device, and stores the session at ~/.brainbase/auth.json (mode 0600). It carries full scopes. When the access token expires, the CLI refreshes it automatically using the stored refresh token. The CLI has its own session, so browser refreshes do not consume its refresh token.

brainbase login          # connect this device
brainbase whoami         # print the current user
brainbase logout         # clear the local session

Personal access tokens (PATs)

For CI or unattended use, issue a long-lived token with token create. Tokens are prefixed bbpat_…. Set one as BRAINBASE_TOKEN and the CLI skips the on-disk session entirely.

Scopes are set with --scopes (a comma-separated list; --scope is an accepted alias). Allowed scopes are read, publish, and admin; the default is read,publish. Only publish is ever checked — see PAT scopes for which endpoints check it, and what read and admin do today.

brainbase token create --scopes read,publish   # issue a PAT (these are the defaults)
brainbase token list                            # show active tokens
brainbase token revoke <id>                     # revoke a token server-side
brainbase token clear                           # forget the local PAT (does not revoke)

export BRAINBASE_TOKEN=bbpat_xxxxxxxxxxxxxxxx
brainbase agent push   # runs without `brainbase login`

Credential precedence

Control-plane, runtime and registry commands use the same credential order:

1. BRAINBASE_TOKEN environment variable (a bbpat_… PAT).
2. ~/.brainbase/auth.json: a valid login session, or an expired session the CLI can renew.
3. ~/.brainbase/token.json: the PAT saved by token create, when the session cannot be used.

A saved PAT belonging to a different account from the login session is not used. Older token files without an account id are still accepted. When the CLI falls back from a session to a saved PAT, it prints a notice on stderr. Run brainbase whoami --json to see the active credential and any renewal failure.

Integrations commands, and the provider operations of agent surface — GitHub and Linear setup, the Linear manifest and disconnect, and phone search, purchase and release — require a login session and do not accept PATs. Unset BRAINBASE_TOKEN before using them. Creating, renaming and revoking PATs also require a session; listing tokens accepts a user-level PAT.

Service routing

Authentication is shared, but the CLI talks to three service surfaces. Agent and orchestration control-plane operations use MAS at https://api.brainbaselabs.com/v2/cli by default — every endpoint on that surface is listed in the control-plane API reference. Registry operations and harness model-proxy traffic use the registry and model gateway at https://api.v1.brainbaselabs.com. Integrations and the surface provider operations above call the web app itself, at BRAINBASE_WEB_URL or the console you logged in through.