Skip to main content
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
  • gitlab.* GitLab integration settings
  • ado.* Azure DevOps integration settings
  • notion.* Notion 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 [command]

​
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 [flags]

​
bd config get

Get a configuration value 
bd config get <key> [flags]

​
bd config list

List all configuration 
bd config list [flags]

​
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> [flags]

​
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 [flags]