beads/website/docs/cli-reference/config.md
matt wilkie b2a4d1d04a
docs: generate CLI reference from live help (#3704)
* docs: generate CLI reference from live help

* docs(cli): move bd version stamp from per-command pages to index only

Drops the `(bd version X.Y.Z)` suffix from the auto-generated header on
every per-command CLI reference page (writeSingleCommandDoc) and the
docs/CLI_REFERENCE.md preamble (writeAllHelp). The version label now
lives only on the index page emitted by scripts/generate-cli-docs.sh:

- Dev tree (website/docs/cli-reference/index.md, docs/CLI_REFERENCE.md):
  labelled "Latest"
- Versioned snapshots (website/versioned_docs/version-X.Y.Z/...):
  labelled with the explicit semver tag parsed from the directory name

This eliminates the 100+-file no-signal diff a release version bump
otherwise produces, restoring the "regen as a separate small commit"
workflow PR #3704 enables. After this change a version bump alone
yields zero diff on the dev tree; only the new versioned snapshot
created at release-cut time carries the new tag. No datestamps are
introduced anywhere — scripts/generate-cli-docs.sh --check remains
deterministic across CI runs.

Refs: mybd-afb, PR #3704

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 19:43:49 -07:00

227 lines
5.9 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) 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.&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
```