ContextQMD
Back to Beads

bd config

website/docs/cli-reference/config.md

1.0.45.8 KB
Original Source
<!-- AUTO-GENERATED: do not edit manually -->

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) and git-based sync.

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 <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