Configuration

Complete configuration reference for beads.

beads has two complementary configuration systems:

1. Tool-level configuration (YAML, managed by Viper) — startup flags and tool behavior, stored in config.yaml files.
2. Project-level configuration (managed by bd config) — integration credentials, status maps, and project-specific settings, stored in the Dolt database. Some keys are routed to config.yaml instead (see YAML-only keys below).

For a deeper treatment of every namespace and its semantics, see docs/CONFIG.md.

Configuration Locations

config.yaml is searched in this order, with later files overriding earlier ones:

1. ~/.beads/config.yaml (legacy user-level, lowest priority)
2. ~/.config/bd/config.yaml (XDG user-level)
3. <repo>/.beads/config.yaml (project-level, walked up from the current directory)
4. $BEADS_DIR/config.yaml (highest priority, when BEADS_DIR is set)

A config.local.yaml next to the project config.yaml is also merged in last for machine-specific overrides that should not be committed.

Precedence

For Viper-managed (YAML) keys, highest to lowest:

1. Command-line flags (e.g. --json, --db, --actor)
2. Environment variables (BD_*, plus a small set of legacy BEADS_* names — see below)
3. config.yaml files (in the order listed above)
4. Built-in defaults

Project-level keys written via bd config set (Jira, Linear, GitHub, status maps, etc.) live in the Dolt database. They are read at command time and have no env var override.

Managing Configuration

# Set a value (auto-routes to config.yaml or the database)
bd config set jira.url "https://company.atlassian.net"
bd config set validation.on-create warn   # YAML-only key

# Set many values in one go
bd config set-many jira.url=https://example.atlassian.net jira.project=PROJ

# Get a value
bd config get jira.url

# List all database-stored config (with override warnings)
bd config list

# Show all effective config with provenance (env / config.yaml / default / database)
bd config show
bd config show --source config.yaml
bd config show --json

# Validate sync-related configuration
bd config validate

# Remove a value
bd config unset jira.url

bd config set automatically routes the write to the right location: keys in the YAML namespace (see below) are written to the project config.yaml; everything else is written to the Dolt database. beads.role is stored in git config.

YAML-only Keys (Startup Settings)

These keys must live in config.yaml, not the database, because they are read before the database is opened. Writing them with bd config set automatically updates config.yaml.

The full namespaces routed to YAML are:

routing.*, sync.*, git.*, directory.*, repos.*, external_projects.*, validation.*, hierarchy.*, ai.*, backup.*, export.*, dolt.*, federation.*

Plus these individual keys:

no-db, json, db, actor, identity, no-push, no-git-ops, create.require-description, github.token, linear.api_key, linear.oauth_client_id, linear.oauth_client_secret.

Secrets in this list are refused on git-tracked config.yaml files unless you pass --force-git-tracked; export the value as an environment variable instead (e.g. LINEAR_API_KEY).

Tool-Level Settings (config.yaml)

bd config show is the source of truth for what's currently effective on your machine, including provenance.

Project-Level Settings (Database)

These are written to the Dolt database by bd config set and have no env var override. Common namespaces:

Issue prefix (issue_prefix) is not settable via bd config set — use bd init --prefix, bd bootstrap, or bd rename-prefix.

Environment Variables

The Viper env prefix is BD_. Config keys map to env vars by upper-casing and replacing . and - with _ (e.g. dolt.auto-commit → BD_DOLT_AUTO_COMMIT, validation.on-create → BD_VALIDATION_ON_CREATE).

Selected commonly-used variables:

Secrets like API tokens follow integration-specific conventions: LINEAR_API_KEY, GITHUB_TOKEN, ANTHROPIC_API_KEY, AZURE_DEVOPS_PAT. These are preferred over storing the value in config.yaml for git-tracked projects.

bd config show will display the source of every effective key, making overrides explicit.

Example .beads/config.yaml

# Default JSON output for scripting
json: true

# Dolt history & sync
dolt:
  auto-commit: on    # Create a Dolt commit after each successful write
  auto-push: false   # Opt-in for single-writer setups

# Issue creation policies
create:
  require-description: true

validation:
  on-create: warn    # Warn when creating issues missing required sections
  on-close: none
  on-sync: none

# Git commit signing for beads commits (GH#600)
git:
  author: "beads-bot <[email protected]>"
  no-gpg-sign: true

# Periodic Dolt-native backup to .beads/backup/
backup:
  enabled: true
  interval: 15m

# Auto-export issues.jsonl after writes (default settings shown for clarity)
export:
  auto: true
  path: issues.jsonl
  interval: 60s
  git-add: true

# Optional Dolt federation
federation:
  remote: dolthub://myorg/beads
  sovereignty: T2

# Directory-aware label scoping for monorepos (GH#541)
directory:
  labels:
    packages/maverick: maverick
    packages/agency: agency

# Cross-project dependency resolution (bd-h807)
external_projects:
  beads: ../beads
  other-project: /absolute/path/to/other-project

output:
  title-length: 255

For machine-specific overrides that should not be committed, drop them in .beads/config.local.yaml; it is merged in last.

Per-Command Override

bd --db /tmp/test.db list           # Override database for one command
bd --json --actor "ci-bot" create "Fix things"  # Multiple flags

Viewing Active Configuration

bd config show                # Effective config with provenance
bd config show --json         # Machine-readable
bd config list                # Database-stored config
bd info --json | jq '.config' # Quick snapshot