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

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
CLICOLOR / CLICOLOR_FORCE	Compatibility flags for color-aware terminals	internal/ui/terminal.go#L43-L48
BD_NO_EMOJI	Turns off optional emoji glyphs in status symbols	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
BD_PAGER	Overrides the default pager program	internal/ui/pager.go#L44
BD_AGENT_MODE	Puts bd into agent mode for automation-friendly prompts	internal/ui/styles.go#L88
BD_GIT_HOOK	Enables special handling when invoked as a Git hook	internal/ui/terminal.go#L33
CLAUDE_CODE	Enables Claude-code UI integration (used by the Claude plugin)	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.
• 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.

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
BEADS_DOLT_SERVER_SOCKET	Overrides the Unix socket path	internal/storage/dolt/store.go#L864
BEADS_DOLT_SERVER_HOST	Hostname for the Dolt server (defaults to localhost)	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:

• 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.
• BEADS_DOLT_PORT / BEADS_DOLT_SERVER_PORT: Overrides the port used by the embedded Dolt server (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).
• BEADS_DOLT_MAX_CONNS: Caps the number of concurrent connections to Dolt (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.
• BEADS_EMBEDDED_DOLT_PROCS / BEADS_EMBEDDED_DOLT_ITERS: Fine-tune the embedded Dolt test harness (internal/storage/embeddeddolt/concurrency_test.go#L27-L30).
• BEADS_TEST_EMBEDDED_DOLT: Enables running embedded-Dolt integration tests (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):

• 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 (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).

Notion Integration

• NOTION_TOKEN: Token for Notion API access, parsed in internal/notion/auth.go#L35.

Practical Configuration Examples

Override the Default Pager and Disable Colors

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) and NO_COLOR from [internal/ui/terminal.go](https://github.com/gastownhall/beads/blob/main/internal/ui/terminal.go).

Run Beads with a Custom Database Location

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

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) and the test harness.

Enable OpenTelemetry Debugging

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).
• 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 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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}