Configuration Management

Understand how the Bricks CLI stores and loads configuration from ~/.bricks, including config.yaml, credentials.yaml, environment variables, and global flags

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

# ~/.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

For more on what data the CLI collects, see Telemetry.

credentials.yaml

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

# ~/.bricks/credentials.yaml
token: Bearer YOUR_API_TOKEN
userid: [e-mail]

Never share or commit credentials.yaml. It contains your session token. If you suspect it has been exposed, run bricks logout and re-authenticate.

See Authentication for the browser-based login flow, or 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

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.

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

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

See the 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)

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 above.

Log files stay on your local machine. They are not sent to Bluebricks.