Get Started

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.

bash
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.

bash
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)
bash
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).

Core API — agent, 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.
Skipping the auth gate in development
Set BRAINBASE_SKIP_AUTH=1 to bypass the auth check for local development against a stubbed backend. Commands that hit the API will still fail server-side without a valid credential.
Not every command needs auth
Auth-gated commands include template, skill, link, unlink, sync, publish, status, and token. Purely local commands such as agent env and run work even with an expired session.