> For the complete documentation index, see [llms.txt](https://bluebricks.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluebricks.co/docs/bricks-cli/configuration-management.md).

# 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](/docs/bricks-cli/telemetry.md).
{% 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](/docs/bricks-cli/authentication.md) for the browser-based login flow, or [Long-Lived Tokens](/docs/bricks-cli/authentication/authenticate-using-long-lived-tokens.md) 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](/docs/bricks-cli/cli-reference.md) 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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/configuration-management.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.