--- id: config title: bd config slug: /cli-reference/config sidebar_position: 420 --- Generated from `bd help --doc config` ## bd 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) - 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): Writes .beads/issues.jsonl after every write command (throttled). Enabled by default. Useful for viewers (bv), interchange, and backup. It is not cross-machine sync; use bd dolt push/pull with a Dolt remote. Keys: export.auto Enable/disable auto-export (default: true) 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: true) 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 false # Disable auto-export bd config set export.path "beads.jsonl" # Custom export filename 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 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 ``` ### bd config list List all configuration ``` bd config list ``` ### bd config set Set a configuration value ``` bd config set [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 ... [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 ``` ### 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 ```