Review follow-ups on the pool-claim feature: - The proxied-server (uow) claim path has its own CAS (issueSQLRepositoryImpl.Claim) and did not get the pool predicate, so in dolt.mode=proxied-server a pool-assigned issue was still refused as "already claimed by <pool>". It now resolves claim.pools through the same issueops.ClaimPoolAliasesInTx and extends its predicate identically, and ClaimRowResult carries CurrentAssigneeIsPool so the use-case layer reports a status conflict instead of a held-by-pool refusal on CAS loss. Covered by three new subtests in the domain/db suite (pool take + lease, unconfigured alias protected, status conflict flagged). - claim.* is now a recognized config namespace: bd config set claim.pools previously warned "not a recognized config key" on the feature's own setup command. The embedded pool test now fails on that warning (the exit code alone missed it), and the recognizer unit test pins claim.pools. - bd config --help documents the key (Claim Pools section + example), including the reclaim caveat: an expired pool take returns to the unassigned pool, not to the pool alias it was dispatched to. CLI reference regenerated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
257 lines
7.7 KiB
Markdown
257 lines
7.7 KiB
Markdown
---
|
|
title: "bd config"
|
|
description: "Manage configuration settings"
|
|
---
|
|
|
|
{/* 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
|
|
- gitlab.* GitLab integration settings
|
|
- ado.* Azure DevOps integration settings
|
|
- notion.* Notion integration settings
|
|
- custom.* Custom integration settings
|
|
- status.* Issue status configuration
|
|
- claim.* Claim arbitration settings (pool-aware claiming)
|
|
- 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).
|
|
|
|
Claim Pools:
|
|
A dispatcher can pre-assign issues to a pool pseudo-assignee (e.g.
|
|
"fable-crew") and let any actor take them with --claim. List the pool
|
|
aliases in the claim.pools config key, comma-separated:
|
|
|
|
bd config set claim.pools "fable-crew,night-crew"
|
|
|
|
Issues assigned to a real actor (or to an alias not in the list) keep
|
|
their anti-steal protection. Pool takes carry the normal lease; note
|
|
that if a taker's lease expires, bd reclaim returns the issue to the
|
|
unassigned pool, not to the pool alias it was dispatched to.
|
|
|
|
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 claim.pools "fable-crew,night-crew" # Pool aliases claimable by any actor
|
|
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 [command]
|
|
```
|
|
|
|
## 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]
|
|
```
|