beads/docs/cli-reference/admin.md
Chris Sells 4ea6fa3ac0 docs(emitter): emit Mintlify CLI reference and generated docs.json nav
bd help --docs-root now additionally writes docs/cli-reference/ in Mintlify
form (frontmatter title as H1, extensionless root-relative links, JSX
auto-generated markers since Mintlify parses .md through MDX) and rewrites
the CLI Reference pages array inside docs/docs.json via a textual splice
that leaves the rest of the file byte-identical — the ~113 nav entries are
never hand-maintained. The Docusaurus outputs (docs/CLI_REFERENCE.md,
website/docs/cli-reference/, versioned snapshots) are unchanged.

generate-cli-docs.sh --check seeds docs/docs.json and docs/cli-reference/
into its scratch root and diffs both; check-cli-docs-drift.sh adds them to
GEN_PATHSPECS and the regeneration fingerprint; docs-autofix-push.sh
allowlists the new generated paths; check-doc-flags.sh scans the new
docs/ subdirectories and requires command coverage in docs/cli-reference/.

Includes the initial docs/docs.json scaffold (nav mirrors the Docusaurus
sidebar IA) and the generated docs/cli-reference/ pages.

TDD: new emitter behavior covered in cmd/bd/help_all_test.go
(Mintlify page format, nav splice correctness + idempotence, bare-root
generation without docs.json).
2026-07-12 10:37:07 -07:00

5.4 KiB

title description
bd admin Administrative commands for database maintenance

{/* AUTO-GENERATED: do not edit manually */}

Generated from bd help --doc admin.

Administrative commands for beads database maintenance.

These commands are for advanced users and should be used carefully: cleanup Delete closed issues (issue lifecycle) compact Compact old closed issues to save space (storage optimization) reset Remove all beads data and configuration (full reset)

For routine maintenance, prefer 'bd doctor --fix' which handles common repairs automatically. Use these admin commands for targeted database operations.

bd admin [flags]

bd admin cleanup

Delete closed issues to reduce database size.

This command permanently removes closed issues from the database.

NOTE: This command only manages issue lifecycle (closed -> deleted). For general health checks and automatic repairs, use 'bd doctor --fix' instead.

By default, deletes ALL closed issues. Use --older-than to only delete issues closed before a certain date.

EXAMPLES: bd admin cleanup --force # Delete all closed issues bd admin cleanup --older-than 30 --force # Only issues closed 30+ days ago bd admin cleanup --ephemeral --force # Only closed wisps (transient molecules) bd admin cleanup --dry-run # Preview what would be deleted

SAFETY:

  • Requires --force flag to actually delete (unless --dry-run)
  • Supports --cascade to delete dependents
  • Shows preview of what will be deleted
  • Use --json for programmatic output

SEE ALSO: bd doctor --fix Automatic health checks and repairs (recommended for routine maintenance) bd admin compact Compact old closed issues to save space

bd admin cleanup [flags]

Flags:

      --cascade          Recursively delete all dependent issues
      --dry-run          Preview what would be deleted without making changes
      --ephemeral        Only delete closed wisps (transient molecules)
  -f, --force            Actually delete (without this flag, shows error)
      --older-than int   Only delete issues closed more than N days ago (0 = all closed issues)

bd admin compact

Compact old closed issues using semantic summarization.

Compaction reduces database size by summarizing closed issues that are no longer actively referenced. This is permanent graceful decay - original content is discarded.

Modes:

  • Analyze: Export candidates for agent review (no API key needed)
  • Apply: Accept agent-provided summary (no API key needed)
  • Auto: AI-powered compaction (requires ANTHROPIC_API_KEY or ai.api_key, legacy)
  • Dolt: Run Dolt garbage collection (for Dolt-backend repositories)

Tiers:

  • Tier 1: Semantic compression (30 days closed, 70% reduction)
  • Tier 2: Ultra compression (90 days closed) - planned, not yet implemented

Dolt Garbage Collection: With auto-commit per mutation, Dolt commit history grows over time. Use --dolt to run Dolt garbage collection and reclaim disk space.

--dolt: Run Dolt GC on .beads/dolt directory to free disk space. This removes unreachable commits and compacts storage.

Examples:

Dolt garbage collection

bd compact --dolt # Run Dolt GC bd compact --dolt --dry-run # Preview without running GC

Agent-driven workflow (recommended)

bd compact --analyze --json # Get candidates with full content bd compact --apply --id bd-42 --summary summary.txt bd compact --apply --id bd-42 --summary - < summary.txt

Legacy AI-powered workflow

bd compact --auto --dry-run # Preview candidates bd compact --auto --all # Compact all eligible issues bd compact --auto --id bd-42 # Compact specific issue

Statistics

bd compact --stats # Show statistics

bd admin compact [flags]

Flags:

      --actor string     Actor name for audit trail (default "agent")
      --all              Process all candidates
      --analyze          Analyze mode: export candidates for agent review
      --apply            Apply mode: accept agent-provided summary
      --auto             Auto mode: AI-powered compaction (legacy)
      --batch-size int   Issues per batch (default 10)
      --dolt             Dolt mode: run Dolt garbage collection on .beads/dolt
      --dry-run          Preview without compacting
      --force            Force compact (bypass checks, requires --id)
      --id string        Compact specific issue
      --json             Output JSON format
      --limit int        Limit number of candidates (0 = no limit)
      --stats            Show compaction statistics
      --summary string   Path to summary file (use '-' for stdin)
      --tier int         Compaction tier (only tier 1 is implemented) (default 1)
      --workers int      Parallel workers (default 5)

bd admin reset

Reset beads to an uninitialized state, removing all local data.

This command removes:

  • The .beads directory (database, JSONL, config)
  • Git hooks installed by bd
  • Sync branch worktrees

By default, shows what would be deleted (dry-run mode). Use --force to actually perform the reset.

Examples: bd reset # Show what would be deleted bd reset --force # Actually delete everything

bd admin reset [flags]

Flags:

      --force   Actually perform the reset (required)