CLI Authentication

Authenticate the bricks CLI with your Bluebricks account using browser-based login or long-lived tokens for CI/CD

Bricks CLI supports two authentication methods: interactive login for local development, and API key authentication for automation and CI/CD pipelines.

Interactive login

Bricks CLI uses a device authorization flow to authenticate. The CLI generates a one-time code, opens your browser, and waits for you to approve.

1. Install the Bricks CLI if you haven't already

2. Run bricks login

3. Your browser opens automatically to the verification page with a pre-filled code. If the browser doesn't open, copy the URL and code from the terminal and open it manually.

4. Sign in and approve the CLI

The terminal confirms authentication:

✓ Logged in successfully as [e-mail]

Your token is saved to ~/.bricks/credentials.yaml.

Verify your authentication:

bricks whoami

Troubleshooting

Browser doesn't open

Copy the verification URL and code printed in your terminal and open the URL manually in any browser.

Code expired

Verification codes expire after approximately 10 minutes. Run bricks login again to get a new code.

"Login was denied" error

This happens when you sign in with a personal account instead of an organization account. Run bricks login again and select your organization account.

Run bricks logger enable then retry the sign-in to generate detailed logs in ~/.bricks/bricks-cli.log. If you can't resolve the issue, contact the Bluebricks team.

API key authentication

For automation and CI/CD, use long-lived API tokens instead of interactive login. There are three ways to provide an API key:

CLI flag

bricks collection create --name "my_collection" --api-key "bbx_your_api_key_here"

Environment variable (recommended for CI/CD)

export BRICKS_API_KEY="bbx_your_api_key_here"
bricks collection create --name "my_collection"

Configuration file

Add to ~/.bricks/environment.yaml:

api_key: "bbx_your_api_key_here"

See API Authentication for how to create and manage API keys.

Authentication priority

Bricks CLI checks authentication sources in this order:

1. CLI flag (--api-key)

2. Environment variable (BRICKS_API_KEY)

3. Configuration file (~/.bricks/environment.yaml)

4. JWT token from bricks login (~/.bricks/credentials.yaml)

Logout

bricks logout

See also

• Authenticate Using Long-Lived Tokens: embed tokens directly in the credentials file

• API Authentication: create and manage API keys

• Quick Start: end-to-end onboarding walkthrough