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

158 lines
3.2 KiB
Markdown

---
id: configuration
title: Configuration
sidebar_position: 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
```bash
# 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
```toml
[database]
# Embedded mode (default): data stored in .beads/embeddeddolt/
# Server mode: connects to dolt sql-server (bd init --server)
```
### ID Generation
```toml
[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:
```bash
# 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](https://github.com/gastownhall/beads/blob/main/docs/CONFIG.md) for migration guidance and full details.
### Import
```toml
[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
```toml
[export]
path = ".beads/issues.jsonl" # Default export file path (for bd export command)
```
### Git
```toml
[git]
auto_commit = true # Auto-commit on sync
auto_push = true # Auto-push on sync
commit_message = "bd: auto-commit" # Default commit message
```
### Hooks
```toml
[hooks]
pre_commit = true # Enable pre-commit hook
post_merge = true # Enable post-merge hook
pre_push = true # Enable pre-push hook
```
### Deletions
```toml
[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
```bash
# Override database
bd --db /tmp/test.db list
```
## Example Configuration
`.beads/config.toml`:
```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
```bash
bd info --json | jq '.config'
```