Chris Sells
d2f87d50de
* docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a regeneration from main's source onto the PR branch, so the squash landed a contradictory mix — the release-aligned hand-written docs plus a CLI reference re-documenting unreleased commands and flags, with docs.json referencing four pages (heartbeat, migrate-personal, reclaim, unclaim) whose files do not exist. That broken nav fails the docsync guard on main and on every branch cut from it. This restores the intended end state of #4874 and lands the pin that prevents the race from recurring. - Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's canonical pure-Go build), removing the unreleased commands/flags and fixing the dangling nav entries. - docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh builds and caches a canonical pure-Go bd from that tag, fetching the tag first in shallow CI checkouts. - generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh resolve bd through the pin and ignore a supplied binary while pinned (BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot now enforce docs-match-release instead of docs-match-main. - tools/docsmint detects the pre-overhaul Docusaurus staging layout that bd <= v1.1.0 emits and converts it to the generic form before its normal Mintlify transform (tested); removable once the pin reaches a release whose emitter writes build/cli-docs. - check-doc-flags.sh: run without timeout(1) on macOS instead of failing Check 4. - Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the beads-docs skill §8 updated to match. * lint: annotate gosec G705 false positive in the docsmint legacy bridge Same class as the existing nav-splice annotation: a developer tool writing repo Markdown, not a web-output sink.
5.4 KiB
title, description
| title | description |
|---|---|
| bd admin | Administrative commands for beads 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)