Skip to main content

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

Import​

[import]
orphan_handling = "allow"     # allow|resurrect|skip|strict
dedupe_on_import = false      # Run duplicate detection after import
ModeBehavior
allowImport orphans without validation (default)
resurrectRestore deleted parents as tombstones
skipSkip orphaned children with warning
strictFail if parent missing

Export​

[export]
path = ".beads/issues.jsonl"  # Export file location
auto_export = true            # Auto-export on changes
debounce_seconds = 5          # Debounce interval

Daemon​

[daemon]
auto_start = true             # Auto-start daemon
sync_interval = "5s"          # Sync check interval
log_level = "info"            # debug|info|warn|error
mode = "poll"                 # poll|events (experimental)

Git​

[git]
auto_commit = true            # Auto-commit on sync
auto_push = true              # Auto-push on sync
commit_message = "bd sync"    # 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​

VariableDescription
BEADS_DBDatabase path
BEADS_NO_DAEMONDisable daemon
BEADS_DAEMON_MODEDaemon mode (poll/events)
BEADS_LOG_LEVELLog level
BEADS_CONFIGConfig file path

Per-Command Override​

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

# Disable daemon for single command
bd --no-daemon create "Task"

Example Configuration​

.beads/config.toml:

[id]
prefix = "myproject"
hash_length = 6

[import]
orphan_handling = "resurrect"
dedupe_on_import = true

[daemon]
auto_start = true
sync_interval = "10s"
mode = "events"

[git]
auto_commit = true
auto_push = true

[deletions]
retention_days = 90

Viewing Active Configuration​

bd info --json | jq '.config'