Skip to main content
Version: Next

bd config

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)
  • 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 [flags]

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]