beads/website/docs/cli-reference/config.md
Jim Wordelman 278b24ab4b
fix(init): honor dolt local-only remote wiring (#4227)
* fix(init): honor dolt local-only remote wiring (ga-vjefud.1)

* docs: regenerate CLI reference for dolt.local-only config help

The dolt.local-only config-set example added in cmd/bd/config.go was not
reflected in the generated CLI docs, so the "Check doc flags freshness" CI
job failed on PR #4227. Regenerate from live bd help: docs/CLI_REFERENCE.md,
the website cli-reference page, the 1.0.0/1.0.4 versioned snapshots, and
llms-full.txt. Generated under LC_ALL=C to match CI's glob collation order.

_Claude Opus 4.7 (beads/investigator) on behalf of quad341_

* docs(config): tighten dolt.local-only help wording + cover isDoltLocalOnly()

Maintainer follow-up on #4227. Two non-blocking review nits:

- The config-set example said "Suppress Dolt remote wiring and sync", but
  dolt.local-only only gates remote wiring at `bd init` time; it does not
  gate runtime `bd dolt push`/`pull`. Reword to "Skip wiring a Dolt sync
  remote during bd init" so the help matches the implemented scope.
  Mirrored into the five generated CLI-reference artifacts.

- Add TestIsDoltLocalOnly to exercise the new isDoltLocalOnly() config
  reader through the env path (BD_DOLT_LOCAL_ONLY). The existing
  TestLocalOnlyInitSkipsConfigureButPersistsExplicitRemote passed localOnly
  directly and never covered the config-reading helper.

Doc artifacts verified fresh with CGO_ENABLED=0 -tags gms_pure_go (matching
CI): check-doc-flags.sh, check-doc-freshness.sh, and both generate-*.sh
--check all pass.

Agent-Signature: claude-opus-4-8-high on behalf of maphew

---------

Co-authored-by: Jim Wordelman <jim@wordelman.name>
Co-authored-by: matt wilkie <maphew@gmail.com>
2026-05-28 15:41:38 -07:00

243 lines
6.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)
- import.* JSONL import 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):
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.&lt;slug&gt;
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"
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
```
### 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
```