Reference

Environment variables

Environment variables let you point the CLI at a different backend, relocate its state, or authenticate without an interactive login. All are optional.

Hosts

Variable	Purpose
`BRAINBASE_WEB_URL`	Override the web app URL used by `login` (default `https://new.usekafka.com`).
`BRAINBASE_CONTROL_PLANE_URL`	Override the MAS control-plane host. The CLI appends `/v2/cli` (default host `https://api.brainbaselabs.com`).
`BRAINBASE_API_URL`	Legacy API host override. When no control-plane override is set, control-plane requests use its `/api/cli` surface. It is also the fallback override for registry and model-proxy traffic.
`BRAINBASE_REGISTRY_URL`	Override the registry API host independently.
`BRAINBASE_PROXY_URL`	Override the model-proxy host used when harness tracking is enabled.

Host resolution

Agent and orchestration control-plane operations resolve their base URL in this order:

BRAINBASE_CONTROL_PLANE_URL + /v2/cli.
Legacy BRAINBASE_API_URL + /api/cli.
https://api.brainbaselabs.com/v2/cli.

BRAINBASE_CONTROL_PLANE_URL wins when both variables are set. Declarative machine_kind / default_model writes, orchestration creation, and schedule-trigger writes require the MAS /v2/cli control plane; the legacy KLS /api/cli surface cannot perform them.

Registry requests resolve BRAINBASE_REGISTRY_URL, then legacy BRAINBASE_API_URL, then the server stored by brainbase login, then https://api.v1.brainbaselabs.com.

Model-proxy requests use the same order, with BRAINBASE_PROXY_URL as the first choice instead of BRAINBASE_REGISTRY_URL. This separation lets you point CLI control traffic at MAS without rerouting harness model traffic.

Authentication

Variable	Purpose
`BRAINBASE_TOKEN`	A long-lived PAT (`bbpat_…`). Overrides `~/.brainbase/token.json` and the browser session.
`BRAINBASE_SKIP_AUTH`	Set to `1` to bypass the auth gate for local development.

CI & automation

Variable	Purpose
`BRAINBASE_NON_INTERACTIVE`	Set to `1` to force non-interactive mode: prompts auto-resolve to their defaults instead of waiting for input. For CI and agent-driven runs.
`BRAINBASE_RUN_ENTRYPOINT`	Set to `1` to make `agent pull` execute the agent entrypoint (equivalent to passing `--run-entrypoint`).

State & debugging

Variable	Purpose
`BRAINBASE_HOME`	Override the local config dir (default `~/.brainbase`).
`CODEX_HOME`	Codex global root, used by the `codex` harness (default `~/.codex`).
`BRAINBASE_DEBUG`	Set to print full stack traces on error.

Credential precedence

Precedence depends on which API the command talks to. On the control plane path (agent, orchestration, link, sync): BRAINBASE_TOKEN env, then the ~/.brainbase/auth.json JWT — token.json is not consulted here. On the registry path (template, skill, token): BRAINBASE_TOKEN env, then the auth.json JWT, then the ~/.brainbase/token.json PAT (a live login session outranks a stored PAT). See Authentication.