beads/website/versioned_docs/version-1.0.0/reference/advanced.md
Isaac Karrer 7f0a165f4e
feat(docs): version Docusaurus site and align llms-full with snapshots (#3033)
* feat(docs): version Docusaurus site and align llms-full with snapshots

Add docs version 1.0.0, version dropdown, lastVersion defaulting to stable,
merged markdown config, and RELEASING steps for future doc snapshots.
generate-llms-full.sh reads the latest entry in versions.json.

README links the published documentation site.

Closes #2644

Made-with: Cursor

* fix(docs): update org URLs to gastownhall and refresh 1.0.0 snapshot

- Update default orgName in docusaurus.config.ts from steveyegge to
  gastownhall to match the repo's new home
- Update hardcoded steveyegge URLs in generate-llms-full.sh
- Refresh versioned_docs 1.0.0 snapshot to include quickstart changes
  from #3032 which merged after the original snapshot was taken
- Regenerate llms-full.txt with corrected URLs and updated content

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: matt wilkie <maphew@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06 21:12:54 -07:00

3.2 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 — requires dolt sql-server running)
bd dolt sql "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.created
  • issue.updated
  • issue.closed
  • dependency.added
  • sync.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/embeddeddolt"

store, _ := embeddeddolt.New(ctx, ".beads", "beads", "main")
defer store.Close()
issue, _ := store.GetIssue(ctx, "bd-a1b2")

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