bd config

Generated from bd help --doc config

Manage configuration settings for external integrations and preferences.

Configuration is stored per-project in the beads database and is version-control-friendly.

Common namespaces:

export.* Auto-export settings (stored in config.yaml)
import.* JSONL import settings (stored in config.yaml)
jira.* Jira integration settings
linear.* Linear integration settings
github.* GitHub integration settings
custom.* Custom integration settings
status.* Issue status configuration
doctor.suppress.* Suppress specific bd doctor warnings (GH#1095)

Auto-Export (config.yaml): Optional JSONL export to .beads/issues.jsonl after write commands (throttled). Useful for viewers (bv), interchange, and issue-level migration; not a backup. It is not cross-machine sync; use bd dolt push/pull with a Dolt remote. Disabled by default. Enable only for integrations that need fresh JSONL. Auto-staging is separate and disabled by default.

Keys: export.auto Enable/disable auto-export (default: false) export.path Output filename relative to .beads/ (default: issues.jsonl) export.interval Minimum time between exports (default: 60s) export.git-add Auto-stage the export file (default: false)

Auto-Import (config.yaml): Reads .beads/issues.jsonl by default when a JSONL import path is implied. Use a relative filename/path so the import stays within the project .beads/ directory and remains portable across machines.

Keys: import.path Input filename relative to .beads/ (default: issues.jsonl)

Custom Status States: You can define custom status states for multi-step pipelines using the status.custom config key. Statuses should be comma-separated.

Example: bd config set status.custom "awaiting_review,awaiting_testing,awaiting_docs"

This enables issues to use statuses like 'awaiting_review' in addition to the built-in statuses (open, in_progress, blocked, deferred, closed).

Suppressing Doctor Warnings: Suppress specific bd doctor warnings by check name slug: bd config set doctor.suppress.pending-migrations true bd config set doctor.suppress.git-hooks true Check names are converted to slugs: "Git Hooks" → "git-hooks". Only warnings are suppressed (errors and passing checks always show). To unsuppress: bd config unset doctor.suppress.<slug>

Examples: bd config set export.auto true # Enable auto-export for viewer integrations bd config set export.path "beads.jsonl" # Custom export filename bd config set import.path "beads.jsonl" # Custom import filename bd config set export.git-add true # Also stage the export file bd config set jira.url "https://company.atlassian.net" bd config set jira.project "PROJ" bd config set status.custom "awaiting_review,awaiting_testing" bd config set doctor.suppress.pending-migrations true bd config set dolt.debug true # Enable Dolt sql-server debug mode (loglevel=debug, --prof cpu) bd config set dolt.local-only true # Skip wiring a Dolt sync remote during bd init bd config get export.auto bd config list bd config unset jira.url

bd config

bd config apply

Reconcile actual system state to match declared configuration.

Runs drift detection and then fixes any mismatches it finds:

hooks Reinstall git hooks if missing or outdated
remote Add/update Dolt origin remote to match federation.remote
server Start Dolt server if dolt.shared-server is enabled

This command is idempotent — safe to run multiple times. Use --dry-run to preview what would change without making modifications.

Examples: bd config apply bd config apply --dry-run bd config apply --json

bd config apply [flags]

Flags:

      --dry-run   Show what would change without making modifications

bd config drift

Detect drift between declared configuration and actual system state.

This is a read-only diagnostic that answers "is my environment consistent with my config?" — no mutations are performed.

Checks:

hooks Git hooks installed and up-to-date
remote Dolt remote matches federation.remote config
server Server state matches dolt.shared-server config

Exit codes: 0 No drift detected (all checks ok/info/skipped) 1 Drift detected (at least one check has status "drift")

Examples: bd config drift bd config drift --json

bd config drift

bd config get

Get a configuration value

bd config get <key>

bd config list

List all configuration

bd config list

bd config set

Set a configuration value

bd config set <key> <value> [flags]

Flags:

      --force-git-tracked   Allow writing secret keys to git-tracked config files (use with caution)

bd config set-many

Set multiple configuration values at once with a single auto-commit and auto-push.

Each argument must be in key=value format. All values are validated before any writes occur. This is faster and less noisy than separate 'bd config set' calls, especially in CI.

Examples: bd config set-many ado.state_map.open=New ado.state_map.closed=Closed bd config set-many jira.url=https://example.atlassian.net jira.project=PROJ

bd config set-many <key=value>... [flags]

Flags:

      --force-git-tracked   Allow writing secret keys to git-tracked config files (use with caution)

bd config show

Display a unified view of all effective configuration across all sources with annotations showing where each value comes from.

Sources (by precedence for Viper-managed keys):

env Environment variable (BD_* or BEADS_*)
config.yaml Project config file (.beads/config.yaml)
default Built-in default value

Additional sources:

metadata Connection settings from .beads/metadata.json
database Integration config stored in the Dolt database
git Git config (e.g., beads.role)

Examples: bd config show bd config show --json bd config show --source config.yaml

bd config show [flags]

Flags:

      --source string   Filter by source (e.g., config.yaml, env, default, metadata, database, git)

bd config unset

Delete a configuration value

bd config unset <key>

bd config validate

Validate sync-related configuration settings.

Checks:

federation.sovereignty is valid (T1, T2, T3, T4, or empty)
federation.remote is set for Dolt sync
Remote URL format is valid (dolthub://, gs://, s3://, az://, file://)
routing.mode is valid (auto, maintainer, contributor, explicit)

Examples: bd config validate bd config validate --json

bd config validate