# Complete Guide to Beads Environment Variables: Configuration Reference for the bd CLI

> Master Beads environment variables to configure UI rendering, Dolt connections, tests, telemetry, and integrations. Explore the comprehensive `bd` CLI configuration reference.

- Repository: [Gas Town Hall/beads](https://github.com/gastownhall/beads)
- Tags: api-reference
- Published: 2026-04-27

---

**Beads (the `bd` CLI) recognizes over 30 environment variables that control UI rendering, Dolt database connections, test execution, telemetry export, and third-party integrations, each parsed at specific locations in the gastownhall/beads source tree.**

The gastownhall/beads repository relies heavily on environment variables for runtime configuration. Understanding which **Beads environment variables** are available allows you to customize everything from color output and pager behavior to database credentials and AI service integrations without modifying configuration files.

## Core CLI and UI Configuration

Beads respects standard POSIX conventions alongside custom `BD_*` prefixed variables for terminal interaction. These are read during early initialization in the UI layer.

### Color and Terminal Output

| Variable | Purpose | Source Location |
|----------|---------|-----------------|
| `NO_COLOR` | Disables ANSI color output entirely | [`internal/ui/terminal.go#L38`](https://github.com/gastownhall/beads/blob/main/internal/ui/terminal.go#L38) |
| `CLICOLOR` / `CLICOLOR_FORCE` | Compatibility flags for color-aware terminals | [`internal/ui/terminal.go#L43-L48`](https://github.com/gastownhall/beads/blob/main/internal/ui/terminal.go#L43) |
| `BD_NO_EMOJI` | Turns off optional emoji glyphs in status symbols | [`internal/ui/terminal.go#L61`](https://github.com/gastownhall/beads/blob/main/internal/ui/terminal.go#L61) |

### Pagination and Agent Mode

| Variable | Purpose | Source Location |
|----------|---------|-----------------|
| `BD_NO_PAGER` | Sends output directly to terminal, bypassing `less` or `more` | [`internal/ui/pager.go#L29`](https://github.com/gastownhall/beads/blob/main/internal/ui/pager.go#L29) |
| `BD_PAGER` | Overrides the default pager program | [`internal/ui/pager.go#L44`](https://github.com/gastownhall/beads/blob/main/internal/ui/pager.go#L44) |
| `BD_AGENT_MODE` | Puts `bd` into agent mode for automation-friendly prompts | [`internal/ui/styles.go#L88`](https://github.com/gastownhall/beads/blob/main/internal/ui/styles.go#L88) |
| `BD_GIT_HOOK` | Enables special handling when invoked as a Git hook | [`internal/ui/terminal.go#L33`](https://github.com/gastownhall/beads/blob/main/internal/ui/terminal.go#L33) |
| `CLAUDE_CODE` | Enables Claude-code UI integration (used by the Claude plugin) | [`internal/ui/styles.go#L92`](https://github.com/gastownhall/beads/blob/main/internal/ui/styles.go#L92) |

## Global Beads Directory and Database Settings

These variables define where Beads stores its metadata and database files.

- **`BEADS_DIR`**: Overrides the default location of the `.beads` repository directory. Parsed in [`internal/utils/path.go#L39`](https://github.com/gastownhall/beads/blob/main/internal/utils/path.go#L39).
- **`BEADS_DB`**: Points the CLI to a specific Beads DB file; useful for testing or sandboxing separate environments.
- **`BEADS_ACTOR`** (with fallback `BD_ACTOR`): Sets the identity of the "actor" (user or automation) that creates tracks and events.
- **`BEADS_HOOK_TIMEOUT`**: Extends the default timeout for Git-hook based operations.

### MCP Integration Context

The following variables manage per-command context sets for the Model Context Protocol (MCP) integration:

- `BEADS_WORKING_DIR`
- `BEADS_CONTEXT_SET`
- `BEADS_REQUIRE_CONTEXT`

These are documented in [`integrations/beads-mcp/CONTEXT_MANAGEMENT.md#L30-L47`](https://github.com/gastownhall/beads/blob/main/integrations/beads-mcp/CONTEXT_MANAGEMENT.md#L30).

## Dolt Database Connection Variables

Beads uses Dolt for version-controlled database operations. These variables configure the embedded or remote Dolt server connection.

### Server Configuration

| Variable | Purpose | Source Location |
|----------|---------|-----------------|
| `BEADS_DOLT_SERVER_DATABASE` | Selects a specific Dolt database name | [`internal/storage/dolt/store.go#L832`](https://github.com/gastownhall/beads/blob/main/internal/storage/dolt/store.go#L832) |
| `BEADS_DOLT_SERVER_SOCKET` | Overrides the Unix socket path | [`internal/storage/dolt/store.go#L864`](https://github.com/gastownhall/beads/blob/main/internal/storage/dolt/store.go#L864) |
| `BEADS_DOLT_SERVER_HOST` | Hostname for the Dolt server (defaults to `localhost`) | [`internal/storage/dolt/store.go#L868`](https://github.com/gastownhall/beads/blob/main/internal/storage/dolt/store.go#L868) |

### Authentication

When connecting to a remote Dolt server, Beads checks these credentials in [`internal/storage/dolt/store.go#L922-L930`](https://github.com/gastownhall/beads/blob/main/internal/storage/dolt/store.go#L922):

- `BEADS_DOLT_PASSWORD`
- `DOLT_REMOTE_USER`
- `DOLT_REMOTE_PASSWORD`

## Test Mode and CI Configuration

The test harness uses a dedicated set of **Beads environment variables** to control deterministic behavior and resource limits.

### Core Test Flags

- **`BEADS_TEST_MODE`**: Switches the code into deterministic test mode, forcing Dolt to listen on a sentinel port. Used throughout the test suite, e.g., in [`tests/regression/regression_test.go#L52`](https://github.com/gastownhall/beads/blob/main/tests/regression/regression_test.go#L52).
- **`BEADS_DOLT_PORT`** / **`BEADS_DOLT_SERVER_PORT`**: Overrides the port used by the embedded Dolt server ([`internal/storage/dolt/store.go#L832`](https://github.com/gastownhall/beads/blob/main/internal/storage/dolt/store.go#L832)).
- **`BEADS_DOLT_AUTO_START`**: Disables automatic Dolt server start-up, useful for CI environments ([`internal/storage/dolt/open.go#L142`](https://github.com/gastownhall/beads/blob/main/internal/storage/dolt/open.go#L142)).
- **`BEADS_DOLT_MAX_CONNS`**: Caps the number of concurrent connections to Dolt ([`internal/storage/dolt/open.go#L228`](https://github.com/gastownhall/beads/blob/main/internal/storage/dolt/open.go#L228)).

### Embedded Dolt Tuning

- **`BEADS_TEST_SKIP`**: Comma-separated list of test categories to skip (e.g., `dolt,slow`). Parsed in [`internal/testutil/testdoltserver.go#L85`](https://github.com/gastownhall/beads/blob/main/internal/testutil/testdoltserver.go#L85).
- **`BEADS_EMBEDDED_DOLT_PROCS`** / **`BEADS_EMBEDDED_DOLT_ITERS`**: Fine-tune the embedded Dolt test harness ([`internal/storage/embeddeddolt/concurrency_test.go#L27-L30`](https://github.com/gastownhall/beads/blob/main/internal/storage/embeddeddolt/concurrency_test.go#L27)).
- **`BEADS_TEST_EMBEDDED_DOLT`**: Enables running embedded-Dolt integration tests ([`internal/storage/embeddeddolt/schema_test.go#L16`](https://github.com/gastownhall/beads/blob/main/internal/storage/embeddeddolt/schema_test.go#L16)).

## Telemetry and Observability

Beads supports OpenTelemetry metric export through these variables, parsed in [[`internal/telemetry/telemetry.go`](https://github.com/gastownhall/beads/blob/main/internal/telemetry/telemetry.go)](https://github.com/gastownhall/beads/blob/main/internal/telemetry/telemetry.go):

- **`BD_OTEL_METRICS_URL`**: If set, enables exporting metrics to the given endpoint (line 54).
- **`BD_OTEL_STDOUT`**: When set to `"true"`, prints telemetry data to STDOUT for debugging (lines 55-84).

## Third-Party Integration Keys

Beads consumes API keys for various integrations through environment variables, typically mapped via Viper configuration.

### AI Services

- **`ANTHROPIC_API_KEY`**: API key for Anthropic's Claude model (consumed via `ai.api_key` config path).
- **`OPENAI_API_KEY`**: API key for OpenAI models (same pattern as above).

### Project Management

- **`LINEAR_API_KEY`**: API key for Linear issue-tracking integration, documented in [`examples/linear-workflow/README.md`](https://github.com/gastownhall/beads/blob/main/examples/linear-workflow/README.md) (line 25).
- **`AZURE_DEVOPS_PAT`**, **`AZURE_DEVOPS_ORG`**, **`AZURE_DEVOPS_PROJECT`**, **`AZURE_DEVOPS_URL`**: Azure DevOps authentication and endpoint configuration (see [`docs/ADO_CONFIG.md`](https://github.com/gastownhall/beads/blob/main/docs/ADO_CONFIG.md)).

### Notion Integration

- **`NOTION_TOKEN`**: Token for Notion API access, parsed in [`internal/notion/auth.go#L35`](https://github.com/gastownhall/beads/blob/main/internal/notion/auth.go#L35).

## Practical Configuration Examples

### Override the Default Pager and Disable Colors

```bash
export BD_PAGER=cat
export NO_COLOR=1
bd log --oneline

```

This sends output directly to the terminal without pagination or ANSI colors, reading `BD_PAGER` from [[`internal/ui/pager.go`](https://github.com/gastownhall/beads/blob/main/internal/ui/pager.go)](https://github.com/gastownhall/beads/blob/main/internal/ui/pager.go) and `NO_COLOR` from [[`internal/ui/terminal.go`](https://github.com/gastownhall/beads/blob/main/internal/ui/terminal.go)](https://github.com/gastownhall/beads/blob/main/internal/ui/terminal.go).

### Run Beads with a Custom Database Location

```bash
export BEADS_DB=/tmp/my-beads.db
export BEADS_DIR=/tmp/custom-beads
bd status

```

This operates on the temporary database file and repository directory rather than the defaults.

### Configure CI Testing with Embedded Dolt

```bash
export BEADS_TEST_MODE=1
export BEADS_DOLT_PORT=12345
export BEADS_DOLT_AUTO_START=false
export BEADS_TEST_SKIP=slow,dolt
go test ./...

```

These settings disable auto-start for the Dolt server and skip specific test categories, as implemented in [[`internal/storage/dolt/open.go`](https://github.com/gastownhall/beads/blob/main/internal/storage/dolt/open.go)](https://github.com/gastownhall/beads/blob/main/internal/storage/dolt/open.go) and the test harness.

### Enable OpenTelemetry Debugging

```bash
export BD_OTEL_METRICS_URL=https://otel-collector.example.com/v1/metrics
export BD_OTEL_STDOUT=true
bd run my-task

```

This configuration exports metrics to your collector while echoing telemetry to the console for verification.

## Summary

- **UI Control**: Use `NO_COLOR`, `BD_PAGER`, and `BD_NO_EMOJI` to customize terminal output according to [[`internal/ui/terminal.go`](https://github.com/gastownhall/beads/blob/main/internal/ui/terminal.go)](https://github.com/gastownhall/beads/blob/main/internal/ui/terminal.go).
- **Data Locations**: Set `BEADS_DIR` and `BEADS_DB` to relocate repository metadata and database files.
- **Dolt Configuration**: Control the embedded database with `BEADS_DOLT_PORT`, `BEADS_DOLT_AUTO_START`, and credential variables in the `internal/storage/dolt/` package.
- **Testing**: Enable deterministic behavior with `BEADS_TEST_MODE` and tune the embedded server with `BEADS_EMBEDDED_DOLT*` variables.
- **Observability**: Export metrics via `BD_OTEL_METRICS_URL` and debug with `BD_OTEL_STDOUT`.
- **Integrations**: Provide API keys for Anthropic, OpenAI, Linear, Azure DevOps, and Notion through standard environment variable patterns.

## Frequently Asked Questions

### How do I disable colors in Beads output?

Set the `NO_COLOR` environment variable to any value. Beads checks this in [`internal/ui/terminal.go#L38`](https://github.com/gastownhall/beads/blob/main/internal/ui/terminal.go#L38) and disables all ANSI escape sequences. You can also use `BD_NO_EMOJI` to remove emoji glyphs while keeping text colors.

### What variable changes the Beads database location?

Use `BEADS_DB` to specify an alternative path to the Beads database file, and `BEADS_DIR` to change the location of the `.beads` repository metadata. These are read during CLI initialization in [[`internal/utils/path.go`](https://github.com/gastownhall/beads/blob/main/internal/utils/path.go)](https://github.com/gastownhall/beads/blob/main/internal/utils/path.go) and affect where Beads stores its state.

### Which Beads environment variables are essential for CI/CD pipelines?

For continuous integration, set `BEADS_TEST_MODE=1` to enable deterministic behavior, `BEADS_DOLT_AUTO_START=false` to manage the Dolt server lifecycle externally, and `BEADS_TEST_SKIP` to exclude slow or database-dependent tests. These variables ensure reliable, reproducible builds in automated environments.

### How do I configure OpenTelemetry metrics export in Beads?

Set `BD_OTEL_METRICS_URL` to your collector endpoint (e.g., `https://otel-collector.example.com/v1/metrics`) to enable metric export. Add `BD_OTEL_STDOUT=true` to echo telemetry data to the console for debugging purposes. The telemetry initialization logic resides in [`internal/telemetry/telemetry.go#L54`](https://github.com/gastownhall/beads/blob/main/internal/telemetry/telemetry.go#L54).