beads/website/docs/cli-reference/config.md
matt wilkie 0c47b3c5ac
fix(init): use git origin as default Dolt remote (#3909)
* fix(init): wire git origin as Dolt remote

Default bd init now treats a git origin as the Dolt remote, persists sync.remote, and still skips synthesis in --stealth. JSONL auto-export/import paths now warn or skip based on sync.remote so exports do not masquerade as cross-machine sync.

Docs and generated agent/CLI references now state that Dolt is canonical, refs/dolt/data is the sync channel, and .beads/issues.jsonl is export/interchange/backup only.

_codex-gpt-5-xhigh on behalf of maphew_

* test: keep embedded command stderr out of parsed stdout

Embedded command tests parse IDs and JSON from command output. The new auto-export warnings correctly go to stderr, but several tests used CombinedOutput and treated warnings as stdout, which broke CI shards that parse issue IDs or JSON lists. Capture stdout separately on success while preserving combined output for error diagnostics.\n\n_codex-gpt-5-medium on behalf of CI Bot_

---------

Co-authored-by: CI Bot <ci@beads.test>
2026-05-13 07:02:39 -07:00

228 lines
6 KiB
Markdown

---
id: config
title: bd config
slug: /cli-reference/config
sidebar_position: 420
---
<!-- 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), 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.&lt;slug&gt;
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
```