Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.
git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).
Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.
Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
4.1 KiB
| title |
|---|
| Advanced Features |
Advanced beads functionality.
Issue Rename
Rename issues while preserving references:
bd rename bd-42 bd-new-id
bd rename bd-42 bd-new-id --dry-run # Preview
Updates:
- All dependencies pointing to old ID
- All references in other issues
- Comments and descriptions
Issue Merge
Merge duplicate issues:
bd merge bd-42 bd-43 --into bd-41
bd merge bd-42 bd-43 --into bd-41 --dry-run
What gets merged:
- Dependencies → target
- Text references updated across all issues
- Source issues closed with merge reason
Database Compaction
Reduce database size by compacting old issues:
# View compaction statistics
bd admin compact --stats
# Preview candidates (30+ days closed)
bd admin compact --analyze --json
# Apply agent-generated summary
bd admin compact --apply --id bd-42 --summary summary.txt
# Immediate deletion (CAUTION!)
bd admin cleanup --force
When to compact:
- Database > 10MB with old closed issues
- After major milestones
- Before archiving project phase
Restore from History
View deleted or compacted issues from git:
bd restore bd-42 --show
bd restore bd-42 --to-file issue.json
Database Inspection
bd sql requires Dolt server mode (bd dolt start, see Performance Tuning
below); it is not available against the default embedded-mode database.
# Schema info
bd info --schema --json
# Raw database query (server mode only)
bd sql "SELECT * FROM issues LIMIT 5"
Extension Data
For Dolt-backed projects, keep extension state outside the beads database and connect it to beads through stable CLI surfaces:
# Query issues for integration workflows
bd list --json
bd query "status=open AND priority<=2" --json
# Run direct SQL for inspection (server mode only)
bd sql "SELECT id, title, status FROM issues LIMIT 5"
Custom tables through direct storage access are a legacy SQLite-only pattern. See the bd-example-extension-go example only if you are maintaining a SQLite-backed extension.
Audit Data
Beads records issue lifecycle events in the database for audit and recovery
workflows. There is no standalone bd events command; inspect current issue
state through JSON output, or query the audit tables directly when needed:
# Current issue state
bd show bd-a1b2 --json
# Recent stored events for one issue (server mode only)
bd sql "SELECT event_type, actor, created_at FROM events WHERE issue_id = 'bd-a1b2' ORDER BY created_at DESC LIMIT 20"
Events:
issue.createdissue.updatedissue.closeddependency.addedsync.completed
Batch Operations
Create Multiple
# Bootstrap a new database from JSONL
bd init --from-jsonl issues.jsonl
Update Multiple
bd list --status open --priority 4 --json | \
jq -r '.[].id' | \
xargs -I {} bd update {} --priority 3
Close Multiple
bd list --label "sprint-1" --status open --json | \
jq -r '.[].id' | \
xargs -I {} bd close {} --reason "Sprint complete"
Integration Access
Use the CLI as the supported integration boundary:
# Machine-readable issue data
bd show bd-a1b2 --json
# Ready-work queue for automation
bd ready --json
# Direct SQL inspection against the active Dolt database (server mode only)
bd sql "SELECT id, priority, status FROM issues WHERE status != 'closed'"
The storage packages under internal/ are not a public Go API.
Performance Tuning
Large Databases
# Enable WAL mode
bd config set database.wal_mode true
# Increase cache
bd config set database.cache_size 10000
Many Concurrent Agents
Beads uses Dolt server mode to handle concurrent access from multiple agents. The server manages transaction isolation automatically.
# Start the Dolt server
bd dolt start
# Check server health
bd doctor
CI/CD Optimization
In CI/CD environments, beads uses embedded mode by default (no server required):
# Just run commands directly — no special flags needed
bd list