# CLI Authentication

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](https://bluebricks.co/docs/bricks-cli/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 you@company.com
```

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

Verify your authentication:

```bash
bricks whoami
```

### Troubleshooting

<details>

<summary>Browser doesn't open</summary>

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

</details>

<details>

<summary>Code expired</summary>

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

</details>

<details>

<summary>"Login was denied" error</summary>

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

</details>

{% hint style="info" %}
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.
{% endhint %}

## 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

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

### Environment variable (recommended for CI/CD)

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

### Configuration file

Add to `~/.bricks/environment.yaml`:

```yaml
api_key: "bbx_your_api_key_here"
```

See [API Authentication](https://bluebricks.co/docs/api/authenticate/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

```bash
bricks logout
```

## See also

* [Authenticate Using Long-Lived Tokens](https://bluebricks.co/docs/bricks-cli/authentication/authenticate-using-long-lived-tokens): embed tokens directly in the credentials file
* [API Authentication](https://bluebricks.co/docs/api/authenticate/authentication): create and manage API keys
* [Quick Start](https://bluebricks.co/docs/getting-started/quick-start): end-to-end onboarding walkthrough