Busabase

CLI Accounts & Workspaces

Keep several Busabase accounts on one machine, and switch workspaces without signing in again.

CLI Accounts & Workspaces

busabase-cli can hold more than one account at a time, and each account can target any of the workspaces it belongs to. Two separate things:

  • Accounts — different credentials. A work account and a personal one, Cloud and a self-hosted server, or two logins on the same host.
  • Workspaces — one account usually belongs to several workspaces on Busabase Cloud. A self-hosted server has exactly one.

The CLI calls a workspace a space (--space-id, space use), matching the x-busabase-space API header. It is the same thing this documentation calls a workspace.

Several accounts

busabase-cli login --profile work   # add a second account, and switch to it
busabase-cli auth status            # list accounts, grouped by host (* = active)
busabase-cli auth switch            # pick one (automatic if there is a single alternative)
busabase-cli auth switch work       # …or name it
busabase-cli auth remove old        # delete a stored account
busabase-cli logout --profile work  # sign out of just that account

auth status groups by host for readability, but accounts are stored flat — two logins on the same host are just two accounts:

https://busabase.com
  * work      orgAbc123   (API key)
    personal  orgDef456   (OAuth, expires in 12d)
http://localhost:15419
    local     (not set)   (no auth)

Several workspaces, one account

busabase-cli space list               # every workspace this account can reach (* = targeted)
busabase-cli space use               # pick from a list
busabase-cli space use "Marketing"   # by name — slug and id also work

No re-login is needed. The choice is checked against the workspaces your credential can actually reach, so a typo fails immediately instead of surfacing as a 403 on your next command. A self-hosted server reports its single workspace and says so.

Where it is stored

~/.busabase/
├── .env                 credentials of the ACTIVE account (0600). Always present.
├── config.json          (optional) settings + which account is active.
└── profiles/            (optional) one file per account.
    ├── default.env
    └── work.env

Switching accounts rewrites ~/.busabase/.env from the account you chose. That is deliberate: the busabase agent skill, the curl snippets in these docs and any SDK reading that file all follow the switch automatically, without knowing accounts exist.

Because .env is rewritten on every switch, don't append a workspace to it by hand (echo BUSABASE_SPACE_ID=… >> ~/.busabase/.env) once you have more than one account — the edit would be lost at the next auth switch. Use busabase-cli space use instead, which records it on the right account.

If you only ever use one account, none of this appears: there is just ~/.busabase/.env, exactly as before, and no config.json or profiles/ is created.

Scripts, CI, and two terminals at once

FlagEnvironment variableEffect
--profile <name>BUSABASE_PROFILEUse that account for this command, reading its file directly. The shared .env is left alone, so two terminals can drive two accounts at the same time.
--config <path>BUSABASE_CONFIGRead credentials from any file you like, ignoring accounts entirely.
--api-key, --base-url, --space-idBUSABASE_API_KEY, …Override individual values; highest precedence of all.

Precedence is: individual flags → --config → --profile → the active account's .env → defaults. An exported environment variable always beats what is on disk.

Preferences

Settings that stay true whichever account you use live in config.json:

busabase-cli auth config set output json   # stop typing --output json every time
busabase-cli auth config list

On this page

CLI Accounts & WorkspacesSeveral accountsSeveral workspaces, one accountWhere it is storedScripts, CI, and two terminals at oncePreferences