Command Reference

brainbase auth

Open the web app and connect this device. Stores the session at ~/.brainbase/auth.json.

bash

brainbase login
brainbase login --web https://app.brainbaselabs.com

Flag	Default	Description
`--web <url>`	`https://app.brainbaselabs.com`	Web app URL to open for the login flow.

brainbase logout

Clear the local session (~/.brainbase/auth.json). No flags.

bash

brainbase logout

brainbase whoami

Show which credential is active and the current user. An expired session is renewed first; if renewal fails, a usable saved PAT can take over. Exits non-zero when no usable credential remains.

bash

brainbase whoami
brainbase whoami --json

JSON field	Meaning
`credential`	`env_pat`, `session`, `stored_pat`, or `null`.
`authenticated`	Whether the active credential can authenticate. False with no credential, and for a PAT that is malformed or that the server rejected — which is still reported as `credential`, because it is what would be sent.
`control_plane`	Whether the active credential is usable against the control plane.
`email` / `user_id`	Who the active credential belongs to: the session's user, or the PAT's owner once the server has confirmed it. `null` when unknown.
`expires_at`	When the session's access token expires. `null` unless `credential` is `session`.
`token_prefix`	The leading characters of the PAT in use, for `env_pat` or `stored_pat`. `null` for a session.
`control_plane_url`	The control-plane base URL requests go to. With a PAT this is the default host or your override, not a stale session's host.
`session.present` / `session.expired`	Whether a session is saved, and whether its access token is expired.
`session.refreshable`	True only for an expired session with the information needed to renew it and no recorded permanent refusal. Always false while the session is valid, including just after a successful renewal.
`session.refresh_error`	The last renewal failure, or `null`.
`stored_pat`	`{ present, name }` describes the saved PAT, even when another credential wins.
`reason`	An explanation and next step when a credential cannot be used, otherwise `null`. It can describe a failed session even when a saved PAT works.