mirror of
https://github.com/gastownhall/beads.git
synced 2026-09-14 20:17:24 +08:00
Chris Sells
d2f87d50de
* docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a regeneration from main's source onto the PR branch, so the squash landed a contradictory mix — the release-aligned hand-written docs plus a CLI reference re-documenting unreleased commands and flags, with docs.json referencing four pages (heartbeat, migrate-personal, reclaim, unclaim) whose files do not exist. That broken nav fails the docsync guard on main and on every branch cut from it. This restores the intended end state of #4874 and lands the pin that prevents the race from recurring. - Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's canonical pure-Go build), removing the unreleased commands/flags and fixing the dangling nav entries. - docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh builds and caches a canonical pure-Go bd from that tag, fetching the tag first in shallow CI checkouts. - generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh resolve bd through the pin and ignore a supplied binary while pinned (BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot now enforce docs-match-release instead of docs-match-main. - tools/docsmint detects the pre-overhaul Docusaurus staging layout that bd <= v1.1.0 emits and converts it to the generic form before its normal Mintlify transform (tested); removable once the pin reaches a release whose emitter writes build/cli-docs. - check-doc-flags.sh: run without timeout(1) on macOS instead of failing Check 4. - Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the beads-docs skill §8 updated to match. * lint: annotate gosec G705 false positive in the docsmint legacy bridge Same class as the existing nav-splice annotation: a developer tool writing repo Markdown, not a web-output sink.
241 lines
6.9 KiB
Markdown
241 lines
6.9 KiB
Markdown
---
|
|
title: "bd config"
|
|
description: "Manage configuration settings for external integrations and preferences."
|
|
---
|
|
|
|
{/* AUTO-GENERATED: do not edit manually */}
|
|
|
|
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
|
|
- 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"
|
|
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 [flags]
|
|
```
|
|
|
|
## 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 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]
|
|
```
|