beads/website/docs/reference/configuration.md
matt wilkie 7fe590d637
fix(docs): repair broken links failing Deploy Documentation CI (#3103)
- architecture/index.md: /docs/DOLT.md → #dolt-server-mode anchor
- core-concepts/index.md: /core-concepts/dolt-server and /dolt-sync → anchor links (pages never existed)
- reference/configuration.md: /docs/CONFIG.md → GitHub source link
- deploy-docs.yml: add lychee --remap to strip /beads/ baseUrl prefix from internal links
- Apply same fixes to versioned_docs/version-1.0.0/

Amp-Thread-ID: https://ampcode.com/threads/T-019d68c4-3efa-71bf-aa9d-6e25fc48fb9a

Co-authored-by: Amp <amp@ampcode.com>
2026-04-07 10:17:55 -07:00

3.2 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]
# Embedded mode (default): data stored in .beads/embeddeddolt/
# Server mode: connects to dolt sql-server (bd init --server)

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 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'