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>
3.1 KiB
3.1 KiB
| id | title | sidebar_position |
|---|---|---|
| advanced | Advanced Features | 3 |
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
# Schema info
bd info --schema --json
# Raw database query (advanced)
sqlite3 .beads/beads.db "SELECT * FROM issues LIMIT 5"
Custom Tables
Extend the database with custom tables:
// In Go code using beads as library
storage.UnderlyingDB().Exec(`
CREATE TABLE IF NOT EXISTS custom_table (...)
`)
See EXTENDING.md.
Event System
Subscribe to beads events:
# View recent events
bd events list --since 1h
# Watch events in real-time
bd events watch
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"
API Access
Use beads as a Go library:
import "github.com/steveyegge/beads/internal/storage"
db, _ := storage.NewSQLite(".beads/beads.db")
issues, _ := db.ListIssues(storage.ListOptions{
Status: "open",
})
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