beads/website/docs/reference/configuration.md
Amp a333dcaa75 fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522)
Systematic cleanup of stale documentation references left over from the
Dolt migration:

- Replace all 'bd sync' → 'bd dolt push' / 'bd dolt pull' across 40+ files
- Replace all 'bd import' → 'bd init --from-jsonl' or remove
- Replace 'bd init --branch' → note about refs/dolt/data separation
- Fix AGENT_INSTRUCTIONS.md (highest impact: agents read this directly)
- Fix npm-package, claude-plugin, integrations, examples, website docs

Add scripts/check-doc-flags.sh to catch stale doc references:
- Checks for removed commands (bd sync, bd import)
- Checks for removed flags (bd init --branch)
- Warns on legacy SQLite/beads.db references
- Compares CLI_REFERENCE.md against bd help --all

Add CI job (check-doc-flags) and Makefile target (check-docs) to gate
PRs against doc freshness.

Prior art: feat/help-doc-generator branch has bd help --doc/--list for
generating docs FROM CLI output. This script validates docs AGAINST CLI
output — complementary approaches.

Amp-Thread-ID: https://ampcode.com/threads/T-019cde77-0722-7353-b63a-1779a5773ca6
Co-authored-by: Amp <amp@ampcode.com>
2026-03-11 13:25:40 -07:00

3.1 KiB

id title sidebar_position
configuration Configuration 1

Configuration

Complete configuration reference for beads.

Configuration Locations

  1. Project config: .beads/config.toml (highest priority)
  2. User config: ~/.beads/config.toml
  3. Environment variables: BEADS_*
  4. Command-line flags: (highest priority)

Managing Configuration

# Get config value
bd config get import.orphan_handling

# Set config value
bd config set import.orphan_handling allow

# List all config
bd config list

# Reset to default
bd config reset import.orphan_handling

Configuration Options

Database

[database]
path = ".beads/beads.db"     # Database file location

ID Generation

[id]
prefix = "bd"                 # Issue ID prefix
hash_length = 4               # Hash length in IDs

Issue ID mode controls whether new issues get hash-based or sequential IDs:

# Use sequential IDs: bd-1, bd-2, bd-3, ...
bd config set issue_id_mode counter

# Use hash-based IDs (default): bd-a3f2, bd-7f3a8, ...
bd config set issue_id_mode hash
Mode Example ID Best for
hash (default) bd-a3f2 Multi-agent, multi-branch workflows
counter bd-1 Single-writer, project-management UIs

Counter IDs are sequential and human-friendly. Hash IDs are collision-free across concurrent branches. See docs/CONFIG.md for migration guidance and full details.

Import

[import]
orphan_handling = "allow"     # allow|resurrect|skip|strict
dedupe_on_import = false      # Run duplicate detection after import
Mode Behavior
allow Import orphans without validation (default)
resurrect Restore deleted parents as tombstones
skip Skip orphaned children with warning
strict Fail if parent missing

Export

[export]
path = ".beads/issues.jsonl"  # Default export file path (for bd export command)

Git

[git]
auto_commit = true            # Auto-commit on sync
auto_push = true              # Auto-push on sync
commit_message = "bd: auto-commit"  # Default commit message

Hooks

[hooks]
pre_commit = true             # Enable pre-commit hook
post_merge = true             # Enable post-merge hook
pre_push = true               # Enable pre-push hook

Deletions

[deletions]
retention_days = 30           # Keep deletion records for N days
prune_on_sync = true          # Auto-prune old records

Environment Variables

Variable Description
BEADS_DB Database path
BEADS_LOG_LEVEL Log level
BEADS_CONFIG Config file path

Per-Command Override

# Override database
bd --db /tmp/test.db list

Example Configuration

.beads/config.toml:

[id]
prefix = "myproject"
hash_length = 6

[import]
orphan_handling = "resurrect"
dedupe_on_import = true

[git]
auto_commit = true
auto_push = true

[deletions]
retention_days = 90

Viewing Active Configuration

bd info --json | jq '.config'