# 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](/docs/bricks-cli/bricks-cli.md) 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](/docs/bricks-cli/authentication/authenticate-using-long-lived-tokens.md): embed tokens directly in the credentials file
* [API Authentication](https://bluebricks.co/docs/api/authenticate/authentication): create and manage API keys
* [Quick Start](/docs/getting-started/quick-start.md): end-to-end onboarding walkthrough


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/bricks-cli/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.