> ## Documentation Index
> Fetch the complete documentation index at: https://beads.gascity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bd config

> Manage configuration settings

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](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](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]
```