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.

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.

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

When more than one credential is present, the resolution order depends on which code path a command takes. A live login session (auth.json) always beats a stored PAT (token.json).

Control plane — agent, orchestration, link, and sync resolve credentials in this order:

1. BRAINBASE_TOKEN environment variable (a bbpat_… PAT).
2. ~/.brainbase/auth.json — the JWT session from brainbase login.

On this path ~/.brainbase/token.json is never consulted.

Registry — template, skill, and token resolve credentials in this order:

1. BRAINBASE_TOKEN environment variable (a bbpat_… PAT).
2. ~/.brainbase/auth.json — the JWT session from brainbase login.
3. ~/.brainbase/token.json — a PAT saved by token create.

Service routing

Authentication is shared, but the CLI talks to two service surfaces. Agent and orchestration control-plane operations use MAS at https://api.brainbaselabs.com/v2/cli by default. Registry operations and harness model-proxy traffic use the registry and model gateway at https://api.v1.brainbaselabs.com.