Authentication

The BuildBear CLI authenticates all API requests with your personal API key. You can provide it through an environment variable or save it to a local config file.

auth setup

Interactive three-step wizard that guides you through creating an account and storing your API key.

buildbear auth setup

What it does:

1. Prompts you to create a BuildBear account at app.buildbear.io/signup
2. Guides you to generate an API key at app.buildbear.io/settings/api-keys
3. Asks for your API key (input is masked) and saves it to ~/.config/buildbear/config.json

[!NOTE] If the BUILDBEAR_API_KEY environment variable is already set, this command exits immediately — no wizard is shown.

auth login

Store or replace your API key without the guided wizard.

buildbear auth login

Prompts for your API key (masked) and saves it to the config file. Use this to rotate a key or switch accounts.

auth logout

Clear your stored credentials.

buildbear auth logout

Deletes ~/.config/buildbear/config.json. Subsequent commands will fail with an authentication error until you log in again.

auth status

Show your current authentication state.

buildbear auth status

Options:

Example output (human-readable):

✅ Authenticated (key stored at /home/you/.config/buildbear/config.json)

Example output (--json):

{
  "authenticated": true,
  "source": "config",
  "configFile": "/home/you/.config/buildbear/config.json"
}

Using an environment variable

Set BUILDBEAR_API_KEY in your shell or CI environment to bypass the config file entirely:

export BUILDBEAR_API_KEY=your-api-key-here
buildbear sandbox list

The environment variable takes precedence over the config file. This is the recommended approach for CI/CD pipelines.

Authentication priority

1. BUILDBEAR_API_KEY environment variable ← checked first
2. ~/.config/buildbear/config.json ← fallback

If neither is set you will see:

Not authenticated. Run 'buildbear auth setup' to get started, or set BUILDBEAR_API_KEY env var.