mirror of
https://github.com/gastownhall/beads.git
synced 2026-09-14 20:17:24 +08:00
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.
159 lines
5.4 KiB
Markdown
159 lines
5.4 KiB
Markdown
---
|
|
title: "bd admin"
|
|
description: "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)
|
|
```
|