# Configuration Management

The Bricks CLI reads settings from files in `~/.bricks/`, environment variables, and CLI flags. This page explains each configuration source, the keys you can set, and the order in which values are resolved.

## Configuration directory

The CLI creates the `~/.bricks/` directory automatically on first run. It contains two configuration files and a logs directory:

```
~/.bricks/
├── config.yaml         # Persistent user preferences
├── credentials.yaml    # Authentication token and user identity
└── logs/               # Daily log files (when logging is enabled)
```

## config.yaml

This file stores persistent user preferences. The CLI loads it at startup and applies the values on top of built-in defaults.

| Key                  | Default  | Description                         |
| -------------------- | -------- | ----------------------------------- |
| `telemetry`          | `true`   | Send anonymous usage analytics      |
| `log`                | `false`  | Write logs to `~/.bricks/logs/`     |
| `log_level`          | `"info"` | Log verbosity: `info`, `debug`      |
| `log_format`         | `"json"` | Log format: `json`, `text`, `none`  |
| `skip_version_check` | `false`  | Skip the update check on startup    |
| `non_interactive`    | `false`  | Suppress interactive prompts        |
| `api_key`            | `""`     | API key for headless authentication |

```yaml
# ~/.bricks/config.yaml
telemetry: true
log: false
log_level: "info"
log_format: "json"
skip_version_check: false
non_interactive: false
api_key: ""
```

You do not need to edit this file by hand. The CLI provides commands that update it for you:

| Command                    | Effect                                       |
| -------------------------- | -------------------------------------------- |
| `bricks logger enable`     | Sets `log: true`                             |
| `bricks logger disable`    | Sets `log: false`                            |
| `bricks logger status`     | Shows whether logging is on or off           |
| `bricks logger cleanup`    | Deletes all log files from `~/.bricks/logs/` |
| `bricks telemetry enable`  | Sets `telemetry: true`                       |
| `bricks telemetry disable` | Sets `telemetry: false`                      |
| `bricks telemetry status`  | Shows whether telemetry is on or off         |

{% hint style="info" %}
For more on what data the CLI collects, see [Telemetry](https://bluebricks.co/docs/bricks-cli/telemetry).
{% endhint %}

## credentials.yaml

This file holds your authentication token and user identity. It is managed by the `bricks login` and `bricks logout` commands.

```yaml
# ~/.bricks/credentials.yaml
token: Bearer YOUR_API_TOKEN
userid: user@example.com
```

{% hint style="warning" %}
Never share or commit `credentials.yaml`. It contains your session token. If you suspect it has been exposed, run `bricks logout` and re-authenticate.
{% endhint %}

See [Authentication](https://bluebricks.co/docs/bricks-cli/authentication) for the browser-based login flow, or [Long-Lived Tokens](https://bluebricks.co/docs/bricks-cli/authentication/authenticate-using-long-lived-tokens) for CI/CD scenarios.

## Environment variable overrides

Every config key can be overridden with an environment variable by adding the `BRICKS_` prefix and uppercasing the key name.

| Variable                    | Overrides            |
| --------------------------- | -------------------- |
| `BRICKS_API_KEY`            | `api_key`            |
| `BRICKS_NON_INTERACTIVE`    | `non_interactive`    |
| `BRICKS_TELEMETRY`          | `telemetry`          |
| `BRICKS_LOG`                | `log`                |
| `BRICKS_LOG_LEVEL`          | `log_level`          |
| `BRICKS_SKIP_VERSION_CHECK` | `skip_version_check` |

{% hint style="success" %}
Environment variables are the recommended way to configure the CLI in CI/CD pipelines. Pair `BRICKS_API_KEY` with `BRICKS_NON_INTERACTIVE=true` for fully headless runs.
{% endhint %}

## Global CLI flags

These flags apply to any command and override both config files and environment variables:

| Flag                | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| `--config <path>`   | Use a custom config file instead of `~/.bricks/config.yaml` |
| `--api-key <key>`   | Authenticate with an API key for this invocation            |
| `--non-interactive` | Suppress interactive prompts for this invocation            |

```bash
bricks blueprint publish --api-key "$BRICKS_KEY" --non-interactive
```

See the [CLI Reference](https://bluebricks.co/docs/bricks-cli/cli-reference) for the full list of commands and flags.

## Configuration loading order

The CLI resolves configuration in the following order. Each layer overrides the previous one:

1. **Built-in defaults** (hardcoded in the CLI binary)
2. **config.yaml** (`~/.bricks/config.yaml`)
3. **credentials.yaml** (`~/.bricks/credentials.yaml`)
4. **Environment variables** (`BRICKS_` prefix)
5. **CLI flags** (`--config`, `--api-key`, `--non-interactive`)

{% @mermaid/diagram content="flowchart LR
A\[Defaults] --> B\[config.yaml]
B --> C\[credentials.yaml]
C --> D\[Env vars]
D --> E\[CLI flags]
style E fill:#4CAF50,color:#fff" %}

A value set by a CLI flag always wins.

## Log files

When logging is enabled, the CLI writes one log file per day to `~/.bricks/logs/`:

```
~/.bricks/logs/bricks_09_03_2026.log
```

The file name follows the pattern `bricks_DD_MM_YYYY.log`. Use `bricks logger enable` and `bricks logger disable` to toggle logging, or `bricks logger cleanup` to remove old files. See the full command list in [config.yaml](#config-yaml) above.

{% hint style="info" %}
Log files stay on your local machine. They are not sent to Bluebricks.
{% endhint %}