* 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>
228 lines
6 KiB
Markdown
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.<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
|
|
```
|