docs: go all-in on Mintlify — delete the Docusaurus site and its machinery

Per the decision record: no parallel run and no cutover PR. Removes
website/ (including the four versioned doc snapshots — current-only
versioning; snapshots remain in git history), deploy-docs.yml,
generate-llms-full.sh (Mintlify serves llms.txt natively), the ci-website
package gate (Makefile target, scripts/ci/website.sh, the package-website
jobs and their aggregate-gate entries in pr.yml/main.yml/release.yml, the
ci-measurements suite, detect-package-gates wiring), and the release-time
docs snapshot flow (snapshot-release-docs.sh, check-docs-version.sh, their
call sites in update-versions.sh/check-versions.sh, RELEASING.md section
rewritten for the Mintlify reality).

Drift machinery now covers exactly the Mintlify artifacts:
check-cli-docs-drift.sh pathspecs/fingerprint, docs-autofix-push.sh
allowlist, and check-doc-flags.sh scans drop the website/llms paths. The
beads-docs skill's generated-content and verification sections updated to
the bd-generic + docsmint pipeline.

NOTE for merge time: if branch protection requires the 'Package Gate
(website)' check by name (rather than the aggregate gate), drop it from
the required checks or PRs will wait forever.

Gates: docsync PASS, generate-cli-docs.sh --check PASS, freshness PASS.
This commit is contained in:
Chris Sells 2026-07-10 23:16:34 -07:00
commit 52aea3f7e3
810 changed files with 31 additions and 108635 deletions

View file

@ -172,14 +172,18 @@ text. Two non-negotiables:
Never hand-edit a generated file. The generated surfaces are:
- `docs/cli-reference/*.md` and the CLI Reference pages array inside
`docs/docs.json` — emitted by `bd help --docs-root` from the Cobra command
strings in `cmd/bd/*.go`.
- `docs/CLI_REFERENCE.md` (single-file reference for GitHub) and
`website/docs/cli-reference/` (Docusaurus, until cutover) — same emitter.
- `website/static/llms-full.txt` — `scripts/generate-llms-full.sh`.
`docs/docs.json` — bd emits vendor-neutral pages (`bd help --docs-root`,
from the Cobra command strings in `cmd/bd/*.go`) into an uncommitted
staging tree, and `tools/docsmint` post-processes them into the committed
Mintlify form. bd itself never emits Mintlify (or any site-generator)
specifics; that lives in docsmint.
- `docs/CLI_REFERENCE.md` — the single-file reference, emitted directly by
`bd help --docs-root`.
To change wording in any of them, edit the Go source (`Short:`, `Long:`,
`Example:` strings) and run `./scripts/generate-cli-docs.sh`. The drift gates
`Example:` strings) and run `./scripts/generate-cli-docs.sh` (which runs both
stages). To change the Mintlify page form itself (comment markers, link
style, nav), edit `tools/docsmint` and its tests. The drift gates
(`generate-cli-docs.sh --check`, `scripts/check-cli-docs-drift.sh` in PR CI,
and the docs-autofix bot) fail or auto-fix any hand edit.

View file

@ -11,8 +11,9 @@ Run these before considering docs work complete. Ordered cheapest-first.
go test ./test/docsync
# 2. Generated CLI docs freshness: regenerates from the live command tree
# and diffs docs/CLI_REFERENCE.md, docs/cli-reference/, the CLI pages
# array in docs/docs.json, website/docs/cli-reference/, and llms-full.
# and diffs docs/CLI_REFERENCE.md, docs/cli-reference/, and the CLI
# pages array in docs/docs.json (bd emits generic pages to staging;
# tools/docsmint produces the committed Mintlify form).
./scripts/generate-cli-docs.sh --check
# CI's blame-scoped variant (only fails PRs for drift they introduced):
./scripts/check-cli-docs-drift.sh
@ -31,9 +32,6 @@ make docs-dev # or: ./mint.sh dev -> http://localhost:3000
./mint.sh broken-links
```
Until cutover, the Docusaurus site keeps building from `website/` — if you
touched anything it consumes, `make ci-website` must stay green.
## Principles the gates don't fully cover
- **Every code fence must be real.** A `bash` fence should show a command the

View file

@ -33,7 +33,6 @@ on:
- nix
- mcp-package
- npm-package
- website
smoke_version:
description: "Optional previous release for cross-version-smoke"
required: false
@ -759,33 +758,3 @@ jobs:
retention-days: 7
if-no-files-found: ignore
website:
name: Measure website checks
if: ${{ inputs.suite == 'website' }}
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v6
- name: Set up Node.js
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
with:
node-version: '24'
cache: 'npm'
cache-dependency-path: website/package-lock.json
- name: Measure commands
run: |
set -euo pipefail
source scripts/ci/lib/timing.sh
ci_time "website package gate" -- make ci-website
- name: Upload measurement artifacts
if: always()
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
with:
name: ci-measure-website
path: website/build/
retention-days: 7
if-no-files-found: ignore

View file

@ -1,102 +0,0 @@
name: Deploy Documentation
on:
push:
branches:
- main
paths:
- 'website/**'
- 'docs/ANTIVIRUS.md'
- 'docs/COMMUNITY_TOOLS.md'
- 'docs/LABELS.md'
- 'docs/METADATA.md'
- 'docs/SYNC_CONCEPTS.md'
- 'docs/UNINSTALLING.md'
- 'scripts/sync-website-docs.sh'
- 'scripts/generate-llms-full.sh'
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment
concurrency:
group: "pages"
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v6
- name: Setup Node.js
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
with:
node-version: 24
cache: 'npm'
cache-dependency-path: website/package-lock.json
- name: Run website package gate
run: make ci-website
- name: Prepare link check (map baseUrl /beads/ to build output)
run: |
mkdir -p website/link-check-root
ln -s "$PWD/website/build" website/link-check-root/beads
- name: Check internal links
uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2
with:
args: |
--verbose
--no-progress
--offline
--include-fragments
--timeout 30
--root-dir website/link-check-root
--fallback-extensions html
--exclude-path 'website/build/search/**'
website/build
fail: true
- name: Check external links (non-blocking)
uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2
continue-on-error: true
with:
cache: true
args: |
--verbose
--no-progress
--timeout 30
--scheme https
--scheme http
--exclude 'localhost'
--exclude '127.0.0.1'
--exclude 'tree/main'
--exclude 'example.com'
--exclude 'mailto:'
--exclude-path 'website/build/search/**'
website/build
- name: Upload artifact
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
with:
path: website/build
deploy:
# Guard: deploy should only run in the canonical repository (not in forks)
if: ${{ github.repository == 'gastownhall/beads' }}
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5

View file

@ -214,7 +214,6 @@ jobs:
outputs:
mcp_package: ${{ steps.detect.outputs.mcp_package }}
npm_package: ${{ steps.detect.outputs.npm_package }}
website: ${{ steps.detect.outputs.website }}
reason: ${{ steps.detect.outputs.reason }}
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v6
@ -320,33 +319,6 @@ jobs:
BEADS_TEST_BD_BINARY: ${{ github.workspace }}/ci-build-artifacts/bd-linux-gms-pure
run: make ci-package-npm
package-website:
name: Package Gate (website)
runs-on: ubuntu-latest
needs: detect-package-gates
steps:
- name: Check applicability
id: applicability
run: |
echo "run=${{ needs.detect-package-gates.outputs.website }}" >> "$GITHUB_OUTPUT"
if [[ "${{ needs.detect-package-gates.outputs.website }}" != "true" ]]; then
echo "website package gate is not applicable: ${{ needs.detect-package-gates.outputs.reason }}"
fi
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v6
if: steps.applicability.outputs.run == 'true'
- name: Set up Node.js
if: steps.applicability.outputs.run == 'true'
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
with:
node-version: '24'
cache: 'npm'
cache-dependency-path: website/package-lock.json
- name: Run website package gate
if: steps.applicability.outputs.run == 'true'
run: make ci-website
pr-policy-wrapper:
name: PR Policy (wrapper timing)

View file

@ -216,7 +216,6 @@ jobs:
outputs:
mcp_package: ${{ steps.detect.outputs.mcp_package }}
npm_package: ${{ steps.detect.outputs.npm_package }}
website: ${{ steps.detect.outputs.website }}
reason: ${{ steps.detect.outputs.reason }}
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v6
@ -322,33 +321,6 @@ jobs:
BEADS_TEST_BD_BINARY: ${{ github.workspace }}/ci-build-artifacts/bd-linux-gms-pure
run: make ci-package-npm
package-website:
name: Package Gate (website)
runs-on: ubuntu-latest
needs: detect-package-gates
steps:
- name: Check applicability
id: applicability
run: |
echo "run=${{ needs.detect-package-gates.outputs.website }}" >> "$GITHUB_OUTPUT"
if [[ "${{ needs.detect-package-gates.outputs.website }}" != "true" ]]; then
echo "website package gate is not applicable: ${{ needs.detect-package-gates.outputs.reason }}"
fi
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v6
if: steps.applicability.outputs.run == 'true'
- name: Set up Node.js
if: steps.applicability.outputs.run == 'true'
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
with:
node-version: '24'
cache: 'npm'
cache-dependency-path: website/package-lock.json
- name: Run website package gate
if: steps.applicability.outputs.run == 'true'
run: make ci-website
pr-policy-wrapper:
name: PR Policy (wrapper timing)
@ -560,7 +532,6 @@ jobs:
- detect-package-gates
- package-mcp
- package-npm
- package-website
- pr-policy-wrapper
- pr-core-wrapper
- pr-lint-wrapper
@ -586,7 +557,6 @@ jobs:
DETECT_PACKAGE_GATES
PACKAGE_MCP
PACKAGE_NPM
PACKAGE_WEBSITE
PR_POLICY_WRAPPER
PR_CORE_WRAPPER
PR_LINT_WRAPPER
@ -604,7 +574,6 @@ jobs:
DETECT_PACKAGE_GATES: ${{ needs.detect-package-gates.result }}
PACKAGE_MCP: ${{ needs.package-mcp.result }}
PACKAGE_NPM: ${{ needs.package-npm.result }}
PACKAGE_WEBSITE: ${{ needs.package-website.result }}
PR_POLICY_WRAPPER: ${{ needs.pr-policy-wrapper.result }}
PR_CORE_WRAPPER: ${{ needs.pr-core-wrapper.result }}
PR_LINT_WRAPPER: ${{ needs.pr-lint-wrapper.result }}

View file

@ -110,24 +110,6 @@ jobs:
- name: Run npm package gate
run: make ci-package-npm
release-package-website:
name: Release Package Gate (website)
if: ${{ github.repository == 'gastownhall/beads' && startsWith(github.ref, 'refs/tags/v') }}
needs: verify-version-consistency
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v6
- name: Set up Node.js
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
with:
node-version: '24'
cache: 'npm'
cache-dependency-path: website/package-lock.json
- name: Run website package gate
run: make ci-website
goreleaser:
# Guard: only run goreleaser in the canonical repository (not in forks)
@ -135,7 +117,6 @@ jobs:
needs:
- release-package-mcp
- release-package-npm
- release-package-website
runs-on: ubuntu-latest
steps:
- name: Checkout

View file

@ -10,7 +10,7 @@ endif
endif
.PHONY: all build doctor-build test test-icu-path test-full-cgo test-regression test-upgrade test-cross-version test-migration corpus-regen bench bench-quick clean clean-test-tmp install install-force help check-up-to-date fmt fmt-check check-testing-short
.PHONY: ci-pr-core ci-pr-policy ci-pr-lint ci-package-mcp ci-package-npm ci-website
.PHONY: ci-pr-core ci-pr-policy ci-pr-lint ci-package-mcp ci-package-npm
# Default target
all: build
@ -132,9 +132,6 @@ ci-package-mcp:
ci-package-npm:
@./scripts/ci/package-npm.sh
ci-website:
@./scripts/ci/website.sh
# Run differential regression tests (baseline v0.49.6 vs current worktree).
# Downloads baseline binary on first run; cached in ~/Library/Caches/beads-regression/.
# Override baseline: BD_REGRESSION_BASELINE_BIN=/path/to/bd make test-regression
@ -290,7 +287,6 @@ help:
@echo " make ci-pr-lint - Run required PR formatting and lint wrapper"
@echo " make ci-package-mcp - Run MCP Python package gate"
@echo " make ci-package-npm - Run npm package gate"
@echo " make ci-website - Run website typecheck/build gate"
@echo " make test-regression - Run differential regression tests (baseline vs candidate)"
@echo " make test-upgrade - Run upgrade smoke tests (release stability gate)"
@echo " make test-cross-version - Run cross-version smoke tests (last 30 tags)"

View file

@ -175,7 +175,6 @@ The tag workflow re-runs release-critical package gates before publishing:
- `make ci-package-mcp` builds and validates the MCP package, then the PyPI job
publishes the validated `dist/*` artifact from that gate.
- `make ci-package-npm` validates the npm wrapper package before npm publish.
- `make ci-website` validates the release docs/website build before GoReleaser
publishes GitHub release assets.
The npm publish job also waits for the macOS release assets, because the npm
@ -366,24 +365,14 @@ git commit -m "chore: Update plugin marketplaces to v0.22.0"
**Note:** These files define how beads appears in Claude Code and Codex plugin marketplaces. Version should match the release version.
### Documentation Site (Docusaurus)
### Documentation Site (Mintlify)
The published docs at GitHub Pages are versioned. Unreleased edits live in
`website/docs/` (**Next**); each release should add a snapshot:
```bash
cd website
npm ci
npm run docusaurus docs:version X.Y.Z
```
Then set `lastVersion` in `website/docusaurus.config.ts` to `X.Y.Z` so
visitors default to the latest stable docs (not **Next**).
Commit `website/versioned_docs/`, `website/versioned_sidebars/`, and
`website/versions.json` with the release. The
`scripts/generate-llms-full.sh` script pulls from the latest entry in
`versions.json` so `llms-full.txt` stays aligned with that snapshot.
The published docs are the Mintlify site rooted at `docs/`, deployed from
main via the Mintlify GitHub integration — no release-time docs snapshot is
needed. The site documents the current release line only (see
engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md). The generated CLI
reference is kept fresh by `scripts/generate-cli-docs.sh` and its PR drift
gate, not by the release process.
## 6. npm Package Release
@ -543,7 +532,6 @@ identifier (e.g. `1.1.0-rc.1`); Python tooling normalizes this to PEP 440 form
# same as a stable release. Date the CHANGELOG section.
# 2. Bump versions. update-versions.sh accepts a prerelease identifier and,
# for prereleases, skips the Docusaurus docs snapshot automatically.
./scripts/update-versions.sh 1.1.0-rc.1
# Windows PE numeric fields (winres file_version/product_version and the
# manifest <assemblyIdentity> version) are set to the base version 1.1.0,

View file

@ -225,7 +225,6 @@ Use the package gate wrappers when touching package or docs surfaces:
```bash
make ci-package-mcp
make ci-package-npm
make ci-website
```
### Coverage Signal Policy

View file

@ -13,7 +13,6 @@ make ci-pr-policy
make ci-pr-lint
make ci-package-mcp
make ci-package-npm
make ci-website
```
Each wrapper auto-detects the repository root, sources `.buildflags` when it
@ -46,8 +45,6 @@ Package gate wrappers validate publishable/package-adjacent surfaces:
- `make ci-package-npm` builds or consumes the native binary expected by
`npm-package/bin/bd`, runs the npm package test suite, and checks
`npm pack --dry-run`.
- `make ci-website` runs website dependency install, typecheck,
`llms-full.txt` generation, and Docusaurus build.
Set `BEADS_TEST_BD_BINARY=/path/to/bd` for MCP and npm package gates to reuse a
prebuilt candidate binary instead of rebuilding it inside the wrapper.

View file

@ -73,8 +73,6 @@ GEN_PATHSPECS=(
"docs/CLI_REFERENCE.md"
"docs/cli-reference"
"docs/docs.json"
"website/docs/cli-reference"
"website/static/llms-full.txt"
)
print_fix_help() {
@ -82,7 +80,6 @@ print_fix_help() {
echo "To fix in any environment (build a canonical bd, then regenerate):"
echo " CGO_ENABLED=0 go build -tags gms_pure_go -o ./bd-docs ./cmd/bd/"
echo " ./scripts/generate-cli-docs.sh ./bd-docs"
echo " ./scripts/generate-llms-full.sh"
echo " rm ./bd-docs"
}
@ -95,9 +92,6 @@ regen_worktree() {
cd "$dir"
CGO_ENABLED=0 go build -tags gms_pure_go -o "$dir/.docs-bd" ./cmd/bd/
./scripts/generate-cli-docs.sh "$dir/.docs-bd" >/dev/null
if [ -x ./scripts/generate-llms-full.sh ]; then
./scripts/generate-llms-full.sh >/dev/null
fi
rm -f "$dir/.docs-bd"
)
}
@ -109,13 +103,13 @@ surface_fingerprint() {
(
cd "$dir"
local f d
for f in docs/CLI_REFERENCE.md docs/docs.json website/static/llms-full.txt; do
for f in docs/CLI_REFERENCE.md docs/docs.json; do
if [ -f "$f" ]; then
printf '== %s\n' "$f"
cat "$f"
fi
done
for d in website/docs/cli-reference docs/cli-reference; do
for d in docs/cli-reference; do
if [ -d "$d" ]; then
find "$d" -type f -name '*.md' | sort | while IFS= read -r f; do
printf '== %s\n' "$f"
@ -198,7 +192,7 @@ if [ -z "$PR_TOUCHED" ] && [ "$FP_HEAD" = "$FP_BASE" ]; then
echo "this change neither alters the regenerated CLI surface nor touches generated files."
git -C "$W_HEAD" diff --stat | sed 's/^/ /'
echo "Not failing this PR. The base branch needs a docs regeneration:"
echo " ./scripts/generate-cli-docs.sh && ./scripts/generate-llms-full.sh"
echo " ./scripts/generate-cli-docs.sh"
if [ -n "${GITHUB_ACTIONS:-}" ]; then
echo "::warning::Generated CLI docs are stale on the base branch (inherited drift, not introduced by this PR)."
fi

View file

@ -44,7 +44,6 @@ SYNC_REFS=$(grep -rn 'bd sync\b' \
"$PROJECT_ROOT"/README.md \
"$PROJECT_ROOT"/npm-package/*.md \
"$PROJECT_ROOT"/integrations/*/README.md \
"$PROJECT_ROOT"/website/docs/**/*.md \
"$PROJECT_ROOT"/plugins/beads/skills/beads/commands/*.md \
"$PROJECT_ROOT"/plugins/beads/skills/beads/resources/*.md \
2>/dev/null \
@ -74,7 +73,6 @@ BRANCH_REFS=$(grep -rn 'bd init.*--branch' \
"$PROJECT_ROOT"/AGENT_INSTRUCTIONS.md \
"$PROJECT_ROOT"/AGENTS.md \
"$PROJECT_ROOT"/README.md \
"$PROJECT_ROOT"/website/docs/**/*.md \
2>/dev/null \
| grep -v 'CHANGELOG\|removed\|was removed\|no longer\|deprecated' \
|| true)
@ -98,7 +96,6 @@ SQLITE_REFS=$(grep -rn 'beads\.db\|default\.db\|sqlite3.*\.beads\|\.beads/.*\.db
"$PROJECT_ROOT"/AGENT_INSTRUCTIONS.md \
"$PROJECT_ROOT"/AGENTS.md \
"$PROJECT_ROOT"/README.md \
"$PROJECT_ROOT"/website/docs/**/*.md \
2>/dev/null \
| grep -v 'CHANGELOG\|removed\|legacy\|migration\|migrate\|was removed\|pre-\|old\|deprecated' \
|| true)
@ -135,7 +132,7 @@ if [ -f "$CLI_REF" ]; then
echo "PASS: docs/CLI_REFERENCE.md covers all live top-level CLI commands"
fi
WEBSITE_DIRS=("$PROJECT_ROOT/website/docs/cli-reference" "$PROJECT_ROOT/docs/cli-reference")
WEBSITE_DIRS=("$PROJECT_ROOT/docs/cli-reference")
for dir in "${WEBSITE_DIRS[@]}"; do
if [ ! -d "$dir" ]; then
continue

View file

@ -1,122 +0,0 @@
#!/bin/bash
# Check that the released Docusaurus docs metadata is self-consistent.
#
# Between a version bump and the actual release, cmd/bd/version.go can be ahead
# of the latest released docs snapshot. In normal PR/main CI, keep validating
# the latest released docs without forcing it to match the unreleased binary
# version. Set BEADS_REQUIRE_RELEASE_DOCS=1, or run from a stable v* tag, to
# require the released docs snapshot to match the current binary version.
set -euo pipefail
RED='\033[0;31m'
GREEN='\033[0;32m'
NC='\033[0m'
if [ ! -f "cmd/bd/version.go" ] || [ ! -f "website/docusaurus.config.ts" ]; then
echo -e "${RED}Error: must run from repository root${NC}"
exit 1
fi
CANONICAL=$(grep 'Version = ' cmd/bd/version.go | sed 's/.*"\(.*\)".*/\1/')
if [ -z "$CANONICAL" ]; then
echo -e "${RED}Could not read version from cmd/bd/version.go${NC}"
exit 1
fi
MISMATCH=0
check_equal() {
local description=$1
local actual=$2
local expected=$3
if [ "$actual" != "$expected" ]; then
echo -e "${RED}❌ $description: $actual (expected $expected)${NC}"
MISMATCH=1
else
echo -e "${GREEN}✓ $description: $actual${NC}"
fi
}
check_exists() {
local description=$1
local path=$2
if [ ! -e "$path" ]; then
echo -e "${RED}❌ Missing $description: $path${NC}"
MISMATCH=1
else
echo -e "${GREEN}✓ $description: $path${NC}"
fi
}
echo "Canonical version (from version.go): $CANONICAL"
echo ""
LATEST_DOCS_VERSION=$(grep -oE '"[0-9]+\.[0-9]+\.[0-9]+"' website/versions.json | head -1 | tr -d '"' || true)
LAST_VERSION=$(grep -oE "lastVersion: '[0-9]+\.[0-9]+\.[0-9]+'" website/docusaurus.config.ts | head -1 | sed "s/.*'\([^']*\)'.*/\1/" || true)
LLMS_VERSION_LABEL=$(grep -oE 'version: [^)]+' website/static/llms-full.txt | head -1 | sed 's/version: //' || true)
CLI_REF_LABEL=""
if [ -n "$LATEST_DOCS_VERSION" ]; then
CLI_REF_LABEL=$(grep -oE 'Reference for bd v[0-9]+\.[0-9]+\.[0-9]+' "website/versioned_docs/version-$LATEST_DOCS_VERSION/cli-reference/index.md" 2>/dev/null | head -1 | sed 's/Reference for bd v//' || true)
fi
REQUIRE_RELEASE_DOCS="${BEADS_REQUIRE_RELEASE_DOCS:-}"
IS_PRERELEASE=0
if [[ "$CANONICAL" == *-* ]]; then
IS_PRERELEASE=1
fi
if [ -z "$REQUIRE_RELEASE_DOCS" ] && [ "$IS_PRERELEASE" -eq 0 ] && [[ "${GITHUB_REF:-}" == refs/tags/v* ]]; then
REQUIRE_RELEASE_DOCS=1
fi
if [ -z "$REQUIRE_RELEASE_DOCS" ] && [ "$IS_PRERELEASE" -eq 0 ] && [ "${GITHUB_REF_TYPE:-}" = "tag" ]; then
REQUIRE_RELEASE_DOCS=1
fi
check_equal "website/versions.json latest released docs version" "$LATEST_DOCS_VERSION" "$LAST_VERSION"
check_equal "website/docusaurus.config.ts lastVersion" "$LAST_VERSION" "$LATEST_DOCS_VERSION"
check_equal "website/static/llms-full.txt source version label" "$LLMS_VERSION_LABEL" "latest released"
check_equal "versioned CLI reference label" "$CLI_REF_LABEL" "$LATEST_DOCS_VERSION"
check_exists "versioned docs snapshot" "website/versioned_docs/version-$LATEST_DOCS_VERSION"
check_exists "versioned sidebar snapshot" "website/versioned_sidebars/version-$LATEST_DOCS_VERSION-sidebars.json"
case "$REQUIRE_RELEASE_DOCS" in
1|true|TRUE|yes|YES)
check_equal "release docs version" "$LATEST_DOCS_VERSION" "$CANONICAL"
;;
*)
if [ "$LATEST_DOCS_VERSION" != "$CANONICAL" ]; then
echo "Release docs strict mode is off; canonical version $CANONICAL may be ahead of latest released docs $LATEST_DOCS_VERSION."
fi
;;
esac
echo ""
if [ "$MISMATCH" -ne 0 ]; then
echo -e "${RED}Docs version policy mismatch detected.${NC}"
echo ""
case "$REQUIRE_RELEASE_DOCS" in
1|true|TRUE|yes|YES)
echo "To prepare release docs for $CANONICAL:"
echo " cd website"
echo " npm ci"
echo " npx docusaurus docs:version $CANONICAL"
echo " cd .."
echo " # Ensure website/docusaurus.config.ts lastVersion is '$CANONICAL'"
echo " ./scripts/generate-cli-docs.sh --versioned $CANONICAL ./bd"
echo " ./scripts/generate-llms-full.sh"
echo " BEADS_REQUIRE_RELEASE_DOCS=1 ./scripts/check-docs-version.sh"
;;
*)
echo "Latest released docs should remain internally consistent."
echo "For unreleased version bumps, leave website/versions.json and"
echo "website/docusaurus.config.ts lastVersion on the latest released snapshot."
;;
esac
exit 1
fi
echo -e "${GREEN}✓ Released docs version policy passed: $LATEST_DOCS_VERSION${NC}"

View file

@ -65,9 +65,6 @@ check_version "npm-package/package.json" \
echo ""
if ! ./scripts/check-docs-version.sh; then
MISMATCH=1
fi
echo ""

View file

@ -11,7 +11,6 @@ push_after_sha="${PUSH_AFTER_SHA:-${GITHUB_SHA:-HEAD}}"
mcp_package=false
npm_package=false
website=false
reason=""
changed_files=""
@ -20,7 +19,6 @@ write_outputs() {
{
echo "mcp_package=$mcp_package"
echo "npm_package=$npm_package"
echo "website=$website"
echo "reason=$reason"
} >>"$GITHUB_OUTPUT"
fi
@ -30,7 +28,6 @@ run_all() {
reason="$1"
mcp_package=true
npm_package=true
website=true
write_outputs
echo "$reason"
exit 0
@ -85,13 +82,14 @@ while IFS= read -r path; do
;;
esac
case "$path" in
website/*|scripts/generate-llms-full.sh|scripts/ci/website.sh|scripts/ci/detect-package-gates.sh|.github/workflows/pr.yml|.github/workflows/main.yml|.github/workflows/pr-risk.yml|.github/workflows/ci-measurements.yml|.github/workflows/deploy-docs.yml|Makefile)
website=true
scripts/ci/detect-package-gates.sh|.github/workflows/pr.yml|.github/workflows/main.yml|.github/workflows/pr-risk.yml|.github/workflows/ci-measurements.yml|Makefile)
mcp_package=true
npm_package=true
;;
esac
done <<<"$changed_files"
if [[ "$mcp_package" == "true" || "$npm_package" == "true" || "$website" == "true" ]]; then
if [[ "$mcp_package" == "true" || "$npm_package" == "true" ]]; then
reason="package paths changed"
else
reason="no package-gate paths changed"
@ -111,4 +109,3 @@ fi
echo "Package gates:"
echo " mcp_package=$mcp_package"
echo " npm_package=$npm_package"
echo " website=$website"

View file

@ -1,36 +0,0 @@
#!/usr/bin/env bash
# Website package gate.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
WEBSITE_DIR="$REPO_ROOT/website"
# shellcheck source=lib/timing.sh
source "$REPO_ROOT/scripts/ci/lib/timing.sh"
website_npm_ci() {
cd "$WEBSITE_DIR"
npm ci
}
website_typecheck() {
cd "$WEBSITE_DIR"
npm run typecheck
}
generate_llms_full() {
cd "$REPO_ROOT"
./scripts/generate-llms-full.sh
}
website_build() {
cd "$WEBSITE_DIR"
npm run build
}
ci_time "website npm ci" -- website_npm_ci
ci_time "website typecheck" -- website_typecheck
ci_time "generate llms-full" -- generate_llms_full
ci_time "website build" -- website_build

View file

@ -55,10 +55,7 @@ path_allowed() {
case "$1" in *..*) return 1 ;; esac
[[ "$1" == "docs/CLI_REFERENCE.md" ]] && return 0
[[ "$1" == "docs/docs.json" ]] && return 0
[[ "$1" == "website/static/llms-full.txt" ]] && return 0
[[ "$1" =~ ^docs/cli-reference/[A-Za-z0-9_.-]+\.md$ ]] && return 0
[[ "$1" =~ ^website/docs/cli-reference/[A-Za-z0-9_.-]+\.md$ ]] && return 0
[[ "$1" =~ ^website/versioned_docs/[A-Za-z0-9_.-]+/cli-reference/[A-Za-z0-9_.-]+\.md$ ]] && return 0
return 1
}
@ -159,7 +156,7 @@ git commit -m "docs: regenerate CLI reference"
git push
\`\`\`
Or regenerate from scratch: \`CGO_ENABLED=0 go build -tags gms_pure_go -o ./bd-docs ./cmd/bd/ && ./scripts/generate-cli-docs.sh ./bd-docs && ./scripts/generate-llms-full.sh && rm ./bd-docs\`
Or regenerate from scratch: \`CGO_ENABLED=0 go build -tags gms_pure_go -o ./bd-docs ./cmd/bd/ && ./scripts/generate-cli-docs.sh ./bd-docs && rm ./bd-docs\`
_Automated by the [docs-autofix workflow]($RUN_URL); this comment is updated in place on each failing run._
EOF

View file

@ -1,195 +0,0 @@
#!/bin/bash
# Generate llms-full.txt from website documentation
# This concatenates all docs into a single file for LLM consumption.
# Uses the latest *released* docs snapshot (versioned_docs) when present so
# llms-full matches the default site version, not unreleased "Next".
set -euo pipefail
export LC_ALL=C
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
SOURCE_ROOT="$PROJECT_ROOT"
OUTPUT_FILE="$PROJECT_ROOT/website/static/llms-full.txt"
CHECK_MODE=0
TMP_OUTPUT_FILE=""
usage() {
echo "Usage: $0 [--check] [--source-root DIR] [--output FILE]" >&2
}
while [ "$#" -gt 0 ]; do
case "$1" in
--check)
CHECK_MODE=1
shift
;;
--source-root)
if [ "$#" -lt 2 ]; then
usage
exit 1
fi
SOURCE_ROOT="$2"
shift 2
;;
--output)
if [ "$#" -lt 2 ]; then
usage
exit 1
fi
OUTPUT_FILE="$2"
shift 2
;;
-h|--help)
usage
exit 0
;;
*)
usage
exit 1
;;
esac
done
cleanup() {
if [ -n "$TMP_OUTPUT_FILE" ]; then
rm -f "$TMP_OUTPUT_FILE"
fi
}
trap cleanup EXIT
resolve_docs_dir() {
local vfile="$SOURCE_ROOT/website/versions.json"
if [ ! -f "$vfile" ]; then
echo "$SOURCE_ROOT/website/docs"
return
fi
# versions.json lists newest first; first semver-like string wins
local ver
ver=$(grep -oE '"[0-9][^"]*"' "$vfile" | head -1 | tr -d '"')
if [ -n "$ver" ] && [ -d "$SOURCE_ROOT/website/versioned_docs/version-$ver" ]; then
echo "$SOURCE_ROOT/website/versioned_docs/version-$ver"
else
echo "$SOURCE_ROOT/website/docs"
fi
}
DOCS_DIR="$(resolve_docs_dir)"
DOC_VERSION_LABEL="Latest"
if [[ "$DOCS_DIR" == *"/versioned_docs/version-"* ]]; then
DOC_VERSION_LABEL="latest released"
fi
if [ "$CHECK_MODE" -eq 1 ]; then
TMP_OUTPUT_FILE="$(mktemp)"
GENERATED_FILE="$TMP_OUTPUT_FILE"
else
mkdir -p "$(dirname "$OUTPUT_FILE")"
GENERATED_FILE="$OUTPUT_FILE"
fi
# Header
cat > "$GENERATED_FILE" << EOF
# Beads Documentation (Complete)
> This file contains the complete beads documentation for LLM consumption.
> Generated automatically from the documentation source files (version: ${DOC_VERSION_LABEL}).
> For the web version, visit: https://gastownhall.github.io/beads/
---
EOF
normalize_content() {
local relative_path="$1"
if [ "$relative_path" = "cli-reference/index.md" ]; then
sed -E 's/^Reference for bd v[0-9][A-Za-z0-9._-]*\. Generated/Reference for bd Latest. Generated/'
else
cat
fi
}
# Function to process a markdown file
process_file() {
local file="$1"
local relative_path="${file#$DOCS_DIR/}"
echo "<document path=\"docs/$relative_path\">" >> "$GENERATED_FILE"
echo "" >> "$GENERATED_FILE"
# Remove frontmatter and add content
sed '/^---$/,/^---$/d' "$file" | normalize_content "$relative_path" >> "$GENERATED_FILE"
echo "" >> "$GENERATED_FILE"
echo "</document>" >> "$GENERATED_FILE"
echo "" >> "$GENERATED_FILE"
}
# Process files in order (intro first, then by category)
if [ -f "$DOCS_DIR/intro.md" ]; then
process_file "$DOCS_DIR/intro.md"
fi
# Process directories in logical order
for dir in getting-started core-concepts architecture cli-reference workflows multi-agent integrations; do
if [ -d "$DOCS_DIR/$dir" ]; then
# Process index first if exists
if [ -f "$DOCS_DIR/$dir/index.md" ]; then
process_file "$DOCS_DIR/$dir/index.md"
fi
# Process other files
for file in "$DOCS_DIR/$dir"/*.md; do
if [ -f "$file" ] && [ "$(basename "$file")" != "index.md" ]; then
process_file "$file"
fi
done
fi
done
for doc in community-tools; do
if [ -f "$DOCS_DIR/$doc.md" ]; then
process_file "$DOCS_DIR/$doc.md"
fi
done
for dir in recovery reference; do
if [ -d "$DOCS_DIR/$dir" ]; then
# Process index first if exists
if [ -f "$DOCS_DIR/$dir/index.md" ]; then
process_file "$DOCS_DIR/$dir/index.md"
fi
# Process other files
for file in "$DOCS_DIR/$dir"/*.md; do
if [ -f "$file" ] && [ "$(basename "$file")" != "index.md" ]; then
process_file "$file"
fi
done
fi
done
# Add footer
cat >> "$GENERATED_FILE" << 'EOF'
---
# End of Documentation
For updates and contributions, visit: https://github.com/gastownhall/beads
EOF
if [ "$CHECK_MODE" -eq 1 ]; then
if ! diff -q "$OUTPUT_FILE" "$GENERATED_FILE" >/dev/null; then
echo "FAIL: website/static/llms-full.txt is out of sync with generated website docs."
echo "Run: ./scripts/generate-llms-full.sh"
diff -u "$OUTPUT_FILE" "$GENERATED_FILE" | sed -n '1,160p' || true
exit 1
fi
echo "PASS: website/static/llms-full.txt is fresh"
else
echo "Generated: $OUTPUT_FILE"
echo "Source docs: $DOCS_DIR"
echo "Size: $(wc -c < "$OUTPUT_FILE" | tr -d ' ') bytes"
echo "Lines: $(wc -l < "$OUTPUT_FILE" | tr -d ' ')"
fi

View file

@ -1,93 +0,0 @@
#!/bin/bash
# snapshot-release-docs.sh — Create/refresh the Docusaurus release snapshot for a
# given version so the published docs (version dropdown, default docs route, and
# the llms-full artifact) match the released bd version.
#
# This is the single source of truth for the docs side of a version bump. It is
# called by scripts/update-versions.sh and referenced by the beads-release
# formula, so version.go and the docs snapshot cannot drift apart (the failure
# mode that left main red after the 1.0.5 release).
#
# Usage: scripts/snapshot-release-docs.sh <version>
# e.g. scripts/snapshot-release-docs.sh 1.0.5
#
# Idempotent: re-running for an existing snapshot only regenerates artifacts and
# re-verifies; it does not duplicate the versioned_docs directory.
set -euo pipefail
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'
if [ $# -ne 1 ]; then
echo "Usage: $0 <version>" >&2
echo "Example: $0 1.0.5" >&2
exit 1
fi
VERSION="$1"
if ! [[ $VERSION =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo -e "${RED}Error: Invalid version format '$VERSION'${NC}" >&2
echo "Expected: MAJOR.MINOR.PATCH (e.g., 1.0.5)" >&2
exit 1
fi
if [ ! -f "cmd/bd/version.go" ] || [ ! -f "website/docusaurus.config.ts" ]; then
echo -e "${RED}Error: must run from repository root${NC}" >&2
exit 1
fi
if ! command -v npx >/dev/null 2>&1; then
echo -e "${RED}Error: npx (Node.js) is required to snapshot Docusaurus docs.${NC}" >&2
echo "Install Node.js, or re-run the version bump with --skip-docs and snapshot separately." >&2
exit 1
fi
echo -e "${YELLOW}Snapshotting release docs for $VERSION${NC}"
# 1. Install website dependencies if needed.
if [ ! -d "website/node_modules" ]; then
echo " • website: npm ci"
(cd website && npm ci)
fi
# 2. Create the versioned snapshot if it does not already exist.
if [ -d "website/versioned_docs/version-$VERSION" ]; then
echo " • snapshot website/versioned_docs/version-$VERSION already exists (skipping docs:version)"
else
echo " • docusaurus docs:version $VERSION"
(cd website && npx docusaurus docs:version "$VERSION")
fi
# 3. Point the site default at the new release snapshot.
echo " • docusaurus.config.ts lastVersion -> $VERSION"
if [[ "$OSTYPE" == "darwin"* ]]; then
sed -i '' "s/lastVersion: '[^']*'/lastVersion: '$VERSION'/" website/docusaurus.config.ts
else
sed -i "s/lastVersion: '[^']*'/lastVersion: '$VERSION'/" website/docusaurus.config.ts
fi
# 4. Regenerate docs artifacts from a freshly built bd so the versioned CLI
# reference carries the "Reference for bd v$VERSION" label and llms-full.txt
# reflects the release snapshot.
echo " • building bd for docs generation"
BD_DOCS="$(pwd)/bd-docs-snapshot"
trap 'rm -f "$BD_DOCS"' EXIT
CGO_ENABLED=0 go build -tags gms_pure_go -o "$BD_DOCS" ./cmd/bd/
echo " • generate-cli-docs.sh"
./scripts/generate-cli-docs.sh --versioned "$VERSION" "$BD_DOCS"
echo " • generate-llms-full.sh"
./scripts/generate-llms-full.sh
# 5. Verify consistency (fails non-zero if anything still drifts).
echo ""
./scripts/check-docs-version.sh
./scripts/check-doc-flags.sh "$BD_DOCS"
echo ""
echo -e "${GREEN}✓ Release docs snapshot ready for $VERSION${NC}"

View file

@ -23,11 +23,8 @@ usage() {
echo "Usage: $0 <version> [--skip-docs]"
echo ""
echo "Updates version numbers across all components (no git operations),"
echo "and snapshots the Docusaurus release docs so version.go and the docs"
echo "snapshot cannot drift apart for stable releases."
echo ""
echo " --skip-docs Skip the Docusaurus snapshot (e.g. on a host without"
echo " Node.js). You must then run scripts/snapshot-release-docs.sh"
echo " <version> elsewhere before tagging a stable release, or CI"
echo " will fail. Prereleases skip docs snapshots by default."
echo ""
@ -148,7 +145,6 @@ echo ""
echo -e "${GREEN}✓ Version constants updated to $NEW_VERSION${NC}"
echo ""
# Snapshot the Docusaurus release docs as part of the same bump so version.go
# and the published docs cannot diverge. This is the failure mode that left
# main red after the 1.0.5 release (version bumped, docs snapshot missing).
if [ "$SKIP_DOCS" -eq 1 ]; then
@ -156,7 +152,6 @@ if [ "$SKIP_DOCS" -eq 1 ]; then
if [ "$IS_PRERELEASE" -eq 1 ]; then
echo " Prerelease CI does not require a stable docs snapshot for $NEW_VERSION."
else
echo " Run scripts/snapshot-release-docs.sh $NEW_VERSION before tagging,"
echo " or CI (check-version-consistency) will fail."
fi
elif [ "$IS_PRERELEASE" -eq 1 ]; then
@ -164,8 +159,7 @@ elif [ "$IS_PRERELEASE" -eq 1 ]; then
echo " Stable docs stay on the latest stable release until $BASE_VERSION ships."
else
echo "Snapshotting release docs..."
./scripts/snapshot-release-docs.sh "$NEW_VERSION"
fi
fi
echo ""
echo "Changed files:"

20
website/.gitignore vendored
View file

@ -1,20 +0,0 @@
# Dependencies
/node_modules
# Production
/build
# Generated files
.docusaurus
.cache-loader
# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*

View file

@ -1,40 +0,0 @@
# Beads Documentation Site (Docusaurus)
This is the Docusaurus site behind https://gastownhall.github.io/beads/.
> **Status: parallel-run.** The docs are being migrated to a Mintlify site
> that lives in `docs/` (preview with `../mint.sh dev`). This Docusaurus site
> keeps building and deploying until the cutover, after which `website/` and
> `.github/workflows/deploy-docs.yml` retire. Author new content in `docs/`;
> only fix things here that break the still-live site.
## Local development
```bash
cd website
npm ci
npm start # dev server with hot reload at http://localhost:3000
```
## Build and verify
```bash
npm run typecheck # TS config sanity
npm run build # production build into website/build/
npm run serve # serve the production build locally
```
The CI package gate is `make ci-website` from the repo root (npm ci,
typecheck, `scripts/generate-llms-full.sh`, build). The Pages deploy runs
from `.github/workflows/deploy-docs.yml` on pushes to `main` that touch
`website/**`.
## Generated content
- `website/docs/cli-reference/` and the versioned CLI snapshots are emitted
by `bd help --docs-root` via `scripts/generate-cli-docs.sh` — never edit
them by hand.
- `website/static/llms-full.txt` and `llms.txt` come from
`scripts/generate-llms-full.sh`.
- Doc versions live in `website/versioned_docs/` (managed by
`npm run docusaurus docs:version <x.y.z>` at release time).

File diff suppressed because it is too large Load diff

View file

@ -1,213 +0,0 @@
---
sidebar_position: 1
title: Architecture Overview
description: Understanding Beads' three-layer data model
---
# Architecture Overview
This document explains how Beads' architecture works with Dolt as its storage backend.
## Architecture
Beads uses **Dolt** as its sole storage backend -- a version-controlled SQL database that provides git-like semantics (branch, merge, diff, push, pull) natively at the database level.
By default, Dolt runs in **embedded mode** (in-process, no separate server). For multi-writer
setups (multiple agents, orchestrator), switch to **server mode** which connects to a
running `dolt sql-server`. See the [Dolt Server Mode](#dolt-server-mode) section below for details.
```mermaid
flowchart TD
subgraph DOLT["🗄️ Dolt Database"]
D[(".beads/dolt/<br/><i>Version-Controlled SQL</i>")]
end
subgraph REMOTE["🌐 Dolt Remotes"]
R[("DoltHub / S3 / GCS<br/><i>Sync & Backup</i>")]
end
D <-->|"bd dolt push/pull"| R
U((User)) -->|"bd create<br/>bd update"| D
D -->|"bd list<br/>bd show"| U
style DOLT fill:#2d5a27,stroke:#4a9c3e,color:#fff
style REMOTE fill:#1a4a6e,stroke:#3a8ac4,color:#fff
```
:::info Source of Truth
**Dolt** is the source of truth. Every write auto-commits to Dolt history, providing full version control, branching, and merge capabilities at the database level.
Recovery is straightforward: pull from a Dolt remote with `bd dolt pull`, or restore from a Dolt-native backup with `bd backup restore`.
:::
### Why Dolt?
- **Version-controlled SQL**: Full SQL queries with native version control
- **Cell-level merge**: Concurrent changes merge automatically at the field level
- **Multi-writer**: Server mode supports concurrent agents
- **Native branching**: Dolt branches independent of git branches
- **Works offline**: All queries run against local database
- **Portable**: `bd export` produces JSONL for migration and interoperability
## Data Flow
### Write Path
```text
User runs bd create
→ Dolt database updated
→ Auto-committed to Dolt history
```
### Read Path
```text
User runs bd list
→ Dolt SQL query
→ Results returned immediately
```
### Sync Path
```text
User runs bd dolt push
→ Commits pushed to Dolt remote
User runs bd dolt pull
→ Remote commits fetched and merged
```
### Multi-Machine Sync Considerations
When working across multiple machines or clones:
1. **Always sync before switching machines**
```bash
bd dolt push # Push changes before leaving
```
2. **Pull before creating new issues**
```bash
bd dolt pull # Pull changes first on new machine
bd create "New issue"
```
3. **Avoid parallel edits** - If two machines create issues simultaneously without syncing, Dolt's cell-level merge handles most conflicts automatically
See [Sync Failures Recovery](/recovery/sync-failures) for data loss prevention in multi-machine workflows (Pattern A5/C3).
## Dolt Server Mode
The Dolt server handles background synchronization and database operations:
- Manages the Dolt database backend
- Handles auto-commit for change tracking
- Provides concurrent access for multiple agents
- Logs available at `.beads/dolt/sql-server.log`
:::tip
Start the Dolt server with `bd dolt start`. Check health with `bd doctor`.
:::
### Embedded Mode (No Server)
For CI/CD pipelines, containers, and single-use scenarios, no server is needed. Beads operates in embedded mode automatically when no Dolt server is running:
```bash
bd create "CI-generated issue"
bd dolt push
```
**When embedded mode is appropriate:**
- CI/CD pipelines (Jenkins, GitHub Actions)
- Docker containers
- Ephemeral environments
- Scripts that should not leave background processes
### Multi-Clone Scenarios
:::warning Race Conditions in Multi-Clone Workflows
When multiple git clones of the same repository run sync operations simultaneously, race conditions can occur during push/pull operations. This is particularly common in:
- Multi-agent AI workflows (multiple Claude/GPT instances)
- Developer workstations with multiple checkouts
- Worktree-based development workflows
**Prevention:**
1. Stop the Dolt server (`bd dolt stop`) before switching between clones
2. Dolt handles worktrees natively in server mode
3. Use embedded mode for automated workflows
:::
See [Sync Failures Recovery](/recovery/sync-failures) for sync race condition troubleshooting (Pattern B2).
## Recovery Model
Dolt's version control makes recovery straightforward:
1. **Lost database?** → Pull from Dolt remote: `bd dolt pull`
2. **Have a backup?** → Restore it: `bd backup restore [path] --force`
3. **Merge conflicts?** → Dolt handles cell-level merge natively
### Universal Recovery Sequence
The following sequence resolves the majority of reported issues. For detailed procedures, see [Recovery Runbooks](/recovery).
```bash
bd dolt stop # Stop Dolt server (prevents race conditions)
git worktree prune # Clean orphaned worktrees
bd dolt pull # Pull from Dolt remote
bd dolt start # Restart server
```
:::warning Use `bd doctor --fix` With Care
Always back up and preview before running `bd doctor --fix`:
1. **Back up first:** `cp -r .beads .beads.backup`
2. **Preview changes:** `bd doctor --dry-run` — shows what would be fixed without making changes
3. **Review diagnostics:** `bd doctor` (no flags) — diagnostic only, no changes made
4. **Then fix:** `bd doctor --fix` — or `bd doctor --fix -i` to confirm each fix individually
**Why caution?** The `--fix` flag may remove dependencies it flags as circular, including valid parent-child relationships. Use `--fix-child-parent` only if you're certain the flagged deps are invalid.
**Other diagnostic tools:**
- `bd blocked` — check which issues are blocked and why
- `bd show <issue-id>` — inspect a specific issue's state
:::
See [Recovery](/recovery) for specific procedures and [Database Corruption Recovery](/recovery/database-corruption) for Dolt recovery steps.
## Design Decisions
### Why Dolt?
Dolt is a version-controlled SQL database that provides git-like semantics natively. Unlike plain SQLite (binary merge conflicts) or JSONL (slow queries), Dolt gives you both fast SQL queries and proper merge semantics.
### Why not a cloud server?
Beads is designed for offline-first, local-first development. The Dolt server runs locally -- no cloud dependency, no downtime, no vendor lock-in, and full functionality on airplanes or in restricted networks.
### Trade-offs
| Benefit | Trade-off |
|---------|-----------|
| Works offline | No real-time collaboration |
| Version-controlled database | Requires Dolt server |
| Cell-level merge | Requires initial setup |
| Local-first speed | Manual sync to remotes |
| SQL queries | Dolt binary dependency |
### When NOT to use Beads
Beads is not suitable for:
- **Large teams (10+)** — Git-based sync doesn't scale well for high-frequency concurrent edits
- **Non-developers** — Requires Git and command-line familiarity
- **Real-time collaboration** — No live updates; requires explicit sync
- **Cross-repository tracking** — Issues are scoped to a single repository
- **Rich media attachments** — Designed for text-based issue tracking
For these use cases, consider GitHub Issues, Linear, or Jira.
## Related Documentation
- [Recovery Runbooks](/recovery) — Step-by-step procedures for common issues
- [CLI Reference](/cli-reference) — Complete command documentation
- [Getting Started](/) — Installation and first steps

View file

@ -1,161 +0,0 @@
---
id: admin
title: bd admin
slug: /cli-reference/admin
sidebar_position: 610
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc admin`
## bd 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 -&gt; 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 - &lt; 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)
```

View file

@ -1,118 +0,0 @@
---
id: ado
title: bd ado
slug: /cli-reference/ado
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc ado`
## bd ado
Commands for syncing issues between beads and Azure DevOps.
Configuration can be set via 'bd config' or environment variables:
ado.org / AZURE_DEVOPS_ORG - Organization name
ado.project / AZURE_DEVOPS_PROJECT - Project name (single)
ado.projects / AZURE_DEVOPS_PROJECTS - Project names (comma-separated)
ado.pat / AZURE_DEVOPS_PAT - Personal access token
ado.url / AZURE_DEVOPS_URL - Custom base URL (on-prem)
```
bd ado [flags]
```
### bd ado projects
List Azure DevOps projects that the configured token has access to.
```
bd ado projects [flags]
```
### bd ado pull
Pull one or more items from Azure DevOps.
Accepts bead IDs or external references as positional arguments.
Equivalent to: bd ado sync --pull-only --issues &lt;refs&gt;
```
bd ado pull [refs...] [flags]
```
**Flags:**
```
--dry-run Preview pull without making changes
```
### bd ado push
Push one or more beads issues to Azure DevOps.
Accepts bead IDs as positional arguments.
Equivalent to: bd ado sync --push-only --issues &lt;ids&gt;
```
bd ado push [bead-ids...] [flags]
```
**Flags:**
```
--dry-run Preview push without making changes
```
### bd ado status
Display current Azure DevOps configuration and sync status.
```
bd ado status [flags]
```
### bd ado sync
Synchronize issues between beads and Azure DevOps.
By default, performs bidirectional sync:
- Pulls new/updated work items from Azure DevOps to beads
- Pushes local beads issues to Azure DevOps
Use --pull-only or --push-only to limit direction.
Filters (--area-path, --iteration-path, --types, --states) restrict
which work items are synced. On pull, they limit the WIQL query. On push,
--types and --states filter local beads before pushing to ADO. Use
--no-create with push to skip creating new ADO work items (only update
existing linked items). Filters can also be persisted via config:
ado.filter.area_path, ado.filter.iteration_path,
ado.filter.types, ado.filter.states
CLI flags override config values when both are set.
```
bd ado sync [flags]
```
**Flags:**
```
--area-path string Filter to ADO area path (e.g., "Project\Team")
--bootstrap-match Enable heuristic matching for first sync
--dry-run Show what would be synced without making changes
--issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
--iteration-path string Filter to ADO iteration path (e.g., "Project\Sprint 1")
--no-create Never create new items in either direction (pull or push)
--parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues.
--prefer-ado On conflict, use Azure DevOps version
--prefer-local On conflict, keep local beads version
--prefer-newer On conflict, use most recent version (default)
--project strings Project name(s) to sync (overrides configured project/projects)
--pull-only Only pull issues from Azure DevOps
--push-only Only push issues to Azure DevOps
--reconcile Force reconciliation scan for deleted items
--states string Filter to ADO states, comma-separated (e.g., "New,Active,Resolved")
--types string Filter to work item types, comma-separated (e.g., "Bug,Task,User Story")
```

View file

@ -1,23 +0,0 @@
---
id: assign
title: bd assign
slug: /cli-reference/assign
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc assign`
## bd assign
Assign an issue to someone.
Shorthand for 'bd update &lt;id&gt; --assignee &lt;name&gt;'.
Examples:
bd assign bd-123 alice
bd assign bd-123 "" # unassign
```
bd assign <id> <name> [flags]
```

View file

@ -1,65 +0,0 @@
---
id: audit
title: bd audit
slug: /cli-reference/audit
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc audit`
## bd audit
Record explicit agent/tool interaction audit entries in .beads/interactions.jsonl.
This optional JSONL sidecar is disabled by default. Enable it with:
bd config set audit.enabled true
Issue history is always recorded in the database and is visible with
bd history &lt;id&gt; --events. The JSONL sidecar is for explicit interaction capture:
- auditing ("why did the agent do that?")
- dataset generation (SFT/RL fine-tuning)
Entries are append-only. Labeling creates a new "label" entry that references a parent entry.
```
bd audit [flags]
```
### bd audit label
Append a label entry referencing an existing interaction
```
bd audit label <entry-id> [flags]
```
**Flags:**
```
--label string Label value (e.g. "good" or "bad")
--reason string Reason for label
```
### bd audit record
Append an audit interaction entry
```
bd audit record [flags]
```
**Flags:**
```
--error string Error string (llm_call/tool_call)
--exit-code int Exit code (tool_call) (default -1)
--issue-id string Related issue id (bd-...)
--kind string Entry kind (e.g. llm_call, tool_call, label)
--model string Model name (llm_call)
--prompt string Prompt text (llm_call)
--response string Response text (llm_call)
--stdin Read a JSON object from stdin (must match audit.Entry schema)
--tool-name string Tool name (tool_call)
```

View file

@ -1,118 +0,0 @@
---
id: backup
title: bd backup
slug: /cli-reference/backup
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc backup`
## bd backup
Back up your beads database for off-machine recovery.
This is a Dolt-native database backup. It preserves the database state,
including tables, branches, commit history, and working-set data. This is
different from 'bd export', which writes issue records to JSONL for migration
and interoperability.
Commands:
bd backup init &lt;path&gt; Set up a backup destination (filesystem or DoltHub)
bd backup sync Push to configured backup destination
bd backup restore [path] Restore from a backup directory
bd backup remove Remove backup destination
bd backup status Show backup status
DoltHub is recommended for cloud backup:
bd backup init https://doltremoteapi.dolthub.com/&lt;user&gt;/&lt;repo&gt;
Set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD for authentication.
```
bd backup [flags]
```
### bd backup init
Configure a filesystem path or URL as a backup destination.
The path can be a local directory (external drive, NAS, Dropbox folder) or a
DoltHub remote URL. If the destination was previously configured, it is
updated to the new path.
Filesystem examples:
bd backup add /mnt/usb/beads-backup
bd backup add ~/Dropbox/beads-backup
DoltHub (recommended for cloud backup):
bd backup add https://doltremoteapi.dolthub.com/myuser/beads-backup
After adding, run 'bd backup sync' to push your data.
```
bd backup init <path> [flags]
```
**Aliases:** add
### bd backup remove
Remove the configured backup destination.
This unregisters the backup remote from Dolt and removes the local
backup configuration. The backup data at the destination is not deleted.
```
bd backup remove [flags]
```
**Aliases:** rm
### bd backup restore
Restore the beads database from a Dolt-native backup.
By default, reads from .beads/backup/ (or the configured backup directory).
Optionally specify a path to a directory containing a Dolt backup.
This restores a full database backup created by 'bd backup sync' or an
equivalent Dolt backup. JSONL files produced by 'bd export' are issue exports,
not restore targets for this command.
Use --force to overwrite an existing database with the backup contents.
The database must already be initialized (run 'bd init' first if needed).
To initialize and restore in one step, use: bd init &amp;&amp; bd backup restore
```
bd backup restore [path] [flags]
```
**Flags:**
```
--force Overwrite existing database with backup contents
```
### bd backup status
Show last backup status
```
bd backup status [flags]
```
### bd backup sync
Sync the current beads database to the configured Dolt backup destination.
This pushes the entire database state (all branches, full history) to the
backup location configured with 'bd backup init'.
The backup is atomic — if the sync fails, the previous backup state is preserved.
Run 'bd backup init &lt;path&gt;' first to configure a destination.
```
bd backup sync [flags]
```

View file

@ -1,65 +0,0 @@
---
id: batch
title: bd batch
slug: /cli-reference/batch
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc batch`
## bd batch
Run multiple write operations in a single database transaction.
Commands are read from stdin (one per line) or from a file via -f/--file.
All operations execute inside a single dolt transaction: on any error the
whole batch is rolled back, otherwise it is committed with one DOLT_COMMIT.
This is intended for shell scripts that currently invoke 'bd' many times in
a loop, which causes severe write amplification on a dolt sql-server backed
by btrfs+compression. Batching collapses N invocations into one transaction
and one dolt commit.
Grammar (one command per line):
close &lt;id&gt; [reason...]
update &lt;id&gt; &lt;key&gt;=&lt;value&gt; [&lt;key&gt;=&lt;value&gt; ...]
create &lt;type&gt; &lt;priority&gt; &lt;title...&gt;
dep add &lt;from-id&gt; &lt;to-id&gt; [type]
dep remove &lt;from-id&gt; &lt;to-id&gt;
#comment (blank lines and '# ...' comments are ignored)
Supported 'update' keys: status, priority, title, assignee
Supported dependency types: see 'bd dep add --help' (default: blocks)
Tokens are whitespace-separated. Double-quoted strings ("like this") may
contain spaces; use \" to embed a quote and \\ for a backslash.
Examples:
# From a pipe
bd list --status stale -q | awk '&#123;print "close",$1," stale"&#125;' | bd batch
# From a file
bd batch -f operations.txt
# Inline
printf 'close bd-1 done\nupdate bd-2 status=in_progress\n' | bd batch
On success, exits 0 and prints a summary (or JSON with --json). On any error,
rolls back the entire transaction and exits non-zero with the failing line.
NOTE: This is a narrow subset. Commands like 'show', 'list', 'ready', 'sync',
complex create flows, or any flag not listed above are NOT accepted. Use
normal 'bd' subcommands for interactive/read operations.
```
bd batch [flags]
```
**Flags:**
```
--dry-run Parse input and echo commands without executing
-f, --file string Read commands from file instead of stdin
-m, --message string DOLT_COMMIT message (default: 'bd: batch N ops by <actor>')
```

View file

@ -1,23 +0,0 @@
---
id: blocked
title: bd blocked
slug: /cli-reference/blocked
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc blocked`
## bd blocked
Show blocked issues
```
bd blocked [flags]
```
**Flags:**
```
--parent string Filter to descendants of this bead/epic
```

View file

@ -1,50 +0,0 @@
---
id: bootstrap
title: bd bootstrap
slug: /cli-reference/bootstrap
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc bootstrap`
## bd bootstrap
Bootstrap sets up the beads database without destroying existing data.
Unlike 'bd init --force', bootstrap will never delete existing issues.
Bootstrap auto-detects the right action:
• If sync.remote is configured: clones from the remote
• If git origin has Dolt data (refs/dolt/data): clones from git and wires origin for future push/pull
• If .beads/backup/*.jsonl exists: restores from backup
• If .beads/issues.jsonl exists: imports from git-tracked JSONL
• If no database exists: creates a fresh one
• If database already exists: validates and reports status
This is the recommended command for:
• Setting up beads on a fresh clone
• Recovering after moving to a new machine
• Repairing a broken database configuration
Non-interactive mode (--non-interactive, --yes/-y, or BD_NON_INTERACTIVE=1):
Skips the confirmation prompt before executing the bootstrap plan.
Also auto-detected when stdin is not a terminal or CI=true is set.
Examples:
bd bootstrap # Auto-detect and set up
bd bootstrap --dry-run # Show what would be done
bd bootstrap --json # Output plan as JSON
bd bootstrap --yes # Skip confirmation prompt
```
bd bootstrap [flags]
```
**Flags:**
```
--dry-run Show what would be done without doing it
--non-interactive Alias for --yes
-y, --yes Skip confirmation prompts (for CI/automation)
```

View file

@ -1,24 +0,0 @@
---
id: branch
title: bd branch
slug: /cli-reference/branch
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc branch`
## bd branch
List all branches or create a new branch.
This command requires the Dolt storage backend. Without arguments,
it lists all branches. With an argument, it creates a new branch.
Examples:
bd branch # List all branches
bd branch feature-xyz # Create a new branch named feature-xyz
```
bd branch [name] [flags]
```

View file

@ -1,32 +0,0 @@
---
id: children
title: bd children
slug: /cli-reference/children
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc children`
## bd children
List all beads that are children of the specified parent bead.
This is a convenience alias for 'bd list --parent &lt;id&gt; --status all'.
Unlike plain 'bd list', children includes closed issues by default,
since the primary use case is inspecting all work under a parent.
Examples:
bd children hq-abc123 # List all children of hq-abc123
bd children hq-abc123 --json # List children in JSON format
bd children hq-abc123 --pretty # Show children in tree format
```
bd children <parent-id> [flags]
```
**Flags:**
```
--pretty Show children in tree format
```

View file

@ -1,40 +0,0 @@
---
id: close
title: bd close
slug: /cli-reference/close
sidebar_position: 60
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc close`
## bd close
Close one or more issues.
If no issue ID is provided, closes the last touched issue (from most recent
create, update, show, or close operation).
When closing multiple issues, provide one --reason for all IDs or repeat
--reason once per ID. Reasons map positionally: the first --reason applies
to the first ID, the second --reason to the second ID, regardless of where
the flags appear in the command line.
```
bd close [id...] [flags]
```
**Aliases:** done
**Flags:**
```
--claim-next Automatically claim the next highest priority available issue
--continue Auto-advance to next step in molecule
-f, --force Force close pinned issues or unsatisfied gates
--no-auto With --continue, show next step but don't claim it
-r, --reason string Reason for closing
--reason-file string Read close reason from file (use - for stdin)
--session string Claude Code session ID (or set CLAUDE_SESSION_ID env var)
--suggest-next Show newly unblocked issues after closing
```

View file

@ -1,32 +0,0 @@
---
id: comment
title: bd comment
slug: /cli-reference/comment
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc comment`
## bd comment
Add a comment to an issue.
Shorthand for 'bd comments add &lt;id&gt; "text"'.
Examples:
bd comment bd-123 "Working on this now"
bd comment bd-123 Working on this now
echo "comment from pipe" | bd comment bd-123 --stdin
bd comment bd-123 --file notes.txt
```
bd comment <id> [text...] [flags]
```
**Flags:**
```
--file string Read comment text from file
--stdin Read comment text from stdin
```

View file

@ -1,66 +0,0 @@
---
id: comments
title: bd comments
slug: /cli-reference/comments
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc comments`
## bd comments
View or manage comments on an issue.
Examples:
# List all comments on an issue (issue id is required — there is no "comments list")
bd comments bd-123
# List comments in JSON format
bd comments bd-123 --json
# Add a comment
bd comments add bd-123 "This is a comment"
# Add a comment from a file
bd comments add bd-123 -f notes.txt
```
bd comments [issue-id] [flags]
```
**Flags:**
```
--local-time Show timestamps in local time instead of UTC
```
### bd comments add
Add a comment to an issue.
Examples:
# Add a comment
bd comments add bd-123 "Working on this now"
# Add a comment from a file
bd comments add bd-123 -f notes.txt
```
bd comments add [issue-id] [text] [flags]
```
**Flags:**
```
-a, --author string Add author to comment
-f, --file string Read comment text from file
```
### bd comments list
Invalid — use bd comments &lt;issue-id&gt; to list comments
```
bd comments list [flags]
```

View file

@ -1,45 +0,0 @@
---
id: compact
title: bd compact
slug: /cli-reference/compact
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc compact`
## bd compact
Squash Dolt commits older than N days into a single commit.
Recent commits (within the retention window) are preserved via cherry-pick.
This reduces Dolt storage overhead from auto-commit history while keeping
recent change tracking intact.
For semantic issue compaction (summarizing closed issues), use 'bd admin compact'.
For full history squash, use 'bd flatten'.
How it works:
1. Identifies commits older than --days threshold
2. Creates a squashed base commit from all old history
3. Cherry-picks recent commits on top
4. Swaps main branch to the compacted version
5. Runs Dolt GC to reclaim space
Examples:
bd compact --dry-run # Preview: show commit breakdown
bd compact --force # Squash commits older than 30 days
bd compact --days 7 --force # Keep only last 7 days of history
bd compact --days 90 --force # Conservative: squash 90+ day old commits
```
bd compact [flags]
```
**Flags:**
```
--days int Keep commits newer than N days (default 30)
--dry-run Preview without making changes
-f, --force Confirm commit squash
```

View file

@ -1,136 +0,0 @@
---
id: completion
title: bd completion
slug: /cli-reference/completion
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc completion`
## bd completion
Generate the autocompletion script for bd for the specified shell.
See each sub-command's help for details on how to use the generated script.
```
bd completion [flags]
```
### bd completion bash
Generate the autocompletion script for the bash shell.
This script depends on the 'bash-completion' package.
If it is not installed already, you can install it via your OS's package manager.
To load completions in your current shell session:
source &lt;(bd completion bash)
To load completions for every new session, execute once:
#### Linux:
bd completion bash &gt; /etc/bash_completion.d/bd
#### macOS:
bd completion bash &gt; $(brew --prefix)/etc/bash_completion.d/bd
You will need to start a new shell for this setup to take effect.
```
bd completion bash
```
**Flags:**
```
--no-descriptions disable completion descriptions
```
### bd completion fish
Generate the autocompletion script for the fish shell.
To load completions in your current shell session:
bd completion fish | source
To load completions for every new session, execute once:
bd completion fish &gt; ~/.config/fish/completions/bd.fish
You will need to start a new shell for this setup to take effect.
```
bd completion fish [flags]
```
**Flags:**
```
--no-descriptions disable completion descriptions
```
### bd completion powershell
Generate the autocompletion script for powershell.
To load completions in your current shell session:
bd completion powershell | Out-String | Invoke-Expression
To load completions for every new session, add the output of the above command
to your powershell profile.
```
bd completion powershell [flags]
```
**Flags:**
```
--no-descriptions disable completion descriptions
```
### bd completion zsh
Generate the autocompletion script for the zsh shell.
If shell completion is not already enabled in your environment you will need
to enable it. You can execute the following once:
echo "autoload -U compinit; compinit" &gt;&gt; ~/.zshrc
To load completions in your current shell session:
source &lt;(bd completion zsh)
To load completions for every new session, execute once:
#### Linux:
bd completion zsh &gt; "$&#123;fpath[1]&#125;/_bd"
#### macOS:
bd completion zsh &gt; $(brew --prefix)/share/zsh/site-functions/_bd
You will need to start a new shell for this setup to take effect.
```
bd completion zsh [flags]
```
**Flags:**
```
--no-descriptions disable completion descriptions
```

View file

@ -1,246 +0,0 @@
---
id: config
title: bd config
slug: /cli-reference/config
sidebar_position: 420
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc config`
## bd config
Manage configuration settings for external integrations and preferences.
Configuration is stored per-project in the beads database and is version-control-friendly.
Common namespaces:
- export.* Auto-export settings (stored in config.yaml)
- import.* JSONL import settings (stored in config.yaml)
- jira.* Jira integration settings
- linear.* Linear integration settings
- github.* GitHub integration settings
- gitlab.* GitLab integration settings
- ado.* Azure DevOps integration settings
- notion.* Notion integration settings
- custom.* Custom integration settings
- status.* Issue status configuration
- doctor.suppress.* Suppress specific bd doctor warnings (GH#1095)
Auto-Export (config.yaml):
Optional JSONL export to .beads/issues.jsonl after write commands (throttled).
Useful for viewers (bv), interchange, and issue-level migration; not a backup.
It is not cross-machine sync; use bd dolt push/pull with a Dolt remote.
Disabled by default. Enable only for integrations that need fresh JSONL.
Auto-staging is separate and disabled by default.
Keys:
export.auto Enable/disable auto-export (default: false)
export.path Output filename relative to .beads/ (default: issues.jsonl)
export.interval Minimum time between exports (default: 60s)
export.git-add Auto-stage the export file (default: false)
Auto-Import (config.yaml):
Reads .beads/issues.jsonl by default when a JSONL import path is implied.
Use a relative filename/path so the import stays within the project .beads/
directory and remains portable across machines.
Keys:
import.path Input filename relative to .beads/ (default: issues.jsonl)
Custom Status States:
You can define custom status states for multi-step pipelines using the
status.custom config key. Statuses should be comma-separated.
Example:
bd config set status.custom "awaiting_review,awaiting_testing,awaiting_docs"
This enables issues to use statuses like 'awaiting_review' in addition to
the built-in statuses (open, in_progress, blocked, deferred, closed).
Suppressing Doctor Warnings:
Suppress specific bd doctor warnings by check name slug:
bd config set doctor.suppress.pending-migrations true
bd config set doctor.suppress.git-hooks true
Check names are converted to slugs: "Git Hooks" → "git-hooks".
Only warnings are suppressed (errors and passing checks always show).
To unsuppress: bd config unset doctor.suppress.&lt;slug&gt;
Examples:
bd config set export.auto true # Enable auto-export for viewer integrations
bd config set export.path "beads.jsonl" # Custom export filename
bd config set import.path "beads.jsonl" # Custom import filename
bd config set export.git-add true # Also stage the export file
bd config set jira.url "https://company.atlassian.net"
bd config set jira.project "PROJ"
bd config set status.custom "awaiting_review,awaiting_testing"
bd config set doctor.suppress.pending-migrations true
bd config set dolt.debug true # Enable Dolt sql-server debug mode (loglevel=debug, --prof cpu)
bd config set dolt.local-only true # Skip wiring a Dolt sync remote during bd init
bd config get export.auto
bd config list
bd config unset jira.url
```
bd config [flags]
```
### bd config apply
Reconcile actual system state to match declared configuration.
Runs drift detection and then fixes any mismatches it finds:
- hooks Reinstall git hooks if missing or outdated
- remote Add/update Dolt origin remote to match federation.remote
- server Start Dolt server if dolt.shared-server is enabled
This command is idempotent — safe to run multiple times. Use --dry-run
to preview what would change without making modifications.
Examples:
bd config apply
bd config apply --dry-run
bd config apply --json
```
bd config apply [flags]
```
**Flags:**
```
--dry-run Show what would change without making modifications
```
### bd config drift
Detect drift between declared configuration and actual system state.
This is a read-only diagnostic that answers "is my environment consistent
with my config?" — no mutations are performed.
Checks:
- hooks Git hooks installed and up-to-date
- remote Dolt remote matches federation.remote config
- server Server state matches dolt.shared-server config
Exit codes:
0 No drift detected (all checks ok/info/skipped)
1 Drift detected (at least one check has status "drift")
Examples:
bd config drift
bd config drift --json
```
bd config drift [flags]
```
### bd config get
Get a configuration value
```
bd config get <key> [flags]
```
### bd config list
List all configuration
```
bd config list [flags]
```
### bd config set
Set a configuration value
```
bd config set <key> <value> [flags]
```
**Flags:**
```
--force-git-tracked Allow writing secret keys to git-tracked config files (use with caution)
```
### bd config set-many
Set multiple configuration values at once with a single auto-commit and auto-push.
Each argument must be in key=value format. All values are validated before
any writes occur. This is faster and less noisy than separate 'bd config set'
calls, especially in CI.
Examples:
bd config set-many ado.state_map.open=New ado.state_map.closed=Closed
bd config set-many jira.url=https://example.atlassian.net jira.project=PROJ
```
bd config set-many <key=value>... [flags]
```
**Flags:**
```
--force-git-tracked Allow writing secret keys to git-tracked config files (use with caution)
```
### bd config show
Display a unified view of all effective configuration across all sources
with annotations showing where each value comes from.
Sources (by precedence for Viper-managed keys):
- env Environment variable (BD_* or BEADS_*)
- config.yaml Project config file (.beads/config.yaml)
- default Built-in default value
Additional sources:
- metadata Connection settings from .beads/metadata.json
- database Integration config stored in the Dolt database
- git Git config (e.g., beads.role)
Examples:
bd config show
bd config show --json
bd config show --source config.yaml
```
bd config show [flags]
```
**Flags:**
```
--source string Filter by source (e.g., config.yaml, env, default, metadata, database, git)
```
### bd config unset
Delete a configuration value
```
bd config unset <key> [flags]
```
### bd config validate
Validate sync-related configuration settings.
Checks:
- federation.sovereignty is valid (T1, T2, T3, T4, or empty)
- federation.remote is set for Dolt sync
- Remote URL format is valid (dolthub://, gs://, s3://, az://, file://)
- routing.mode is valid (auto, maintainer, contributor, explicit)
Examples:
bd config validate
bd config validate --json
```
bd config validate [flags]
```

View file

@ -1,26 +0,0 @@
---
id: context
title: bd context
slug: /cli-reference/context
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc context`
## bd context
Show the effective backend identity information including repository paths,
backend configuration, and sync settings.
This command reads directly from config files and does not require the
database to be open, making it useful for diagnostics in degraded states.
Examples:
bd context # Show context information
bd context --json # Output in JSON format
```
bd context [flags]
```

View file

@ -1,75 +0,0 @@
---
id: cook
title: bd cook
slug: /cli-reference/cook
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc cook`
## bd cook
Cook transforms a .formula.json file into a proto.
By default, cook outputs the resolved formula as JSON to stdout for
ephemeral use. The output can be inspected, piped, or saved to a file.
Two cooking modes are available:
COMPILE-TIME (default, --mode=compile):
Produces a proto with &#123;&#123;variable&#125;&#125; placeholders intact.
Use for: modeling, estimation, contractor handoff, planning.
Variables are NOT substituted - the output shows the template structure.
RUNTIME (--mode=runtime or when --var flags provided):
Produces a fully-resolved proto with variables substituted.
Use for: final validation before pour, seeing exact output.
Requires all variables to have values (via --var or defaults).
Formulas are high-level workflow templates that support:
- Variable definitions with defaults and validation
- Step definitions that become issue hierarchies
- Composition rules for bonding formulas together
- Inheritance via extends
The --persist flag enables the legacy behavior of writing the proto
to the database. This is useful when you want to reuse the same
proto multiple times without re-cooking.
For most workflows, prefer ephemeral protos: pour and wisp commands
accept formula names directly and cook inline.
Examples:
bd cook mol-feature.formula.json # Compile-time: keep &#123;&#123;vars&#125;&#125;
bd cook mol-feature --var name=auth # Runtime: substitute vars
bd cook mol-feature --mode=runtime --var name=auth # Explicit runtime mode
bd cook mol-feature --dry-run # Preview steps
bd cook mol-release.formula.json --persist # Write to database
bd cook mol-release.formula.json --persist --force # Replace existing
Output (default):
JSON representation of the resolved formula with all steps.
Output (--persist):
Creates a proto bead in the database with:
- ID matching the formula name (e.g., mol-feature)
- The "template" label for proto identification
- Child issues for each step
- Dependencies matching depends_on relationships
```
bd cook <formula-file> [flags]
```
**Flags:**
```
--dry-run Preview what would be created
--force Replace existing proto if it exists (requires --persist)
--mode string Cooking mode: compile (keep placeholders) or runtime (substitute vars)
--persist Persist proto to database (legacy behavior)
--prefix string Prefix to prepend to proto ID (e.g., 'gt-' creates 'gt-mol-feature')
--search-path strings Additional paths to search for formula inheritance
--var stringArray Variable substitution (key=value), enables runtime mode
```

View file

@ -1,65 +0,0 @@
---
id: count
title: bd count
slug: /cli-reference/count
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc count`
## bd count
Count issues matching the specified filters.
By default, returns the total count of issues matching the filters.
Use --by-* flags to group counts by different attributes.
Examples:
bd count # Count all issues
bd count --status open # Count open issues
bd count --by-status # Group count by status
bd count --by-priority # Group count by priority
bd count --by-type # Group count by issue type
bd count --by-assignee # Group count by assignee
bd count --by-label # Group count by label
bd count --assignee alice --by-status # Count alice's issues by status
bd count --include-infra # Count issues + wisps tier (matches 'bd list --include-infra --all' cardinality)
```
bd count [flags]
```
**Flags:**
```
-a, --assignee string Filter by assignee
--by-assignee Group count by assignee
--by-label Group count by label
--by-priority Group count by priority
--by-status Group count by status
--by-type Group count by issue type
--closed-after string Filter issues closed after date (YYYY-MM-DD or RFC3339)
--closed-before string Filter issues closed before date (YYYY-MM-DD or RFC3339)
--created-after string Filter issues created after date (YYYY-MM-DD or RFC3339)
--created-before string Filter issues created before date (YYYY-MM-DD or RFC3339)
--desc-contains string Filter by description substring
--empty-description Filter issues with empty description
--id string Filter by specific issue IDs (comma-separated)
--include-infra Include infrastructure beads and the wisps tier (matches 'bd list --include-infra --all' cardinality)
-l, --label strings Filter by labels (AND: must have ALL)
--label-any strings Filter by labels (OR: must have AT LEAST ONE)
--no-assignee Filter issues with no assignee
--no-labels Filter issues with no labels
--notes-contains string Filter by notes substring
-p, --priority int Filter by priority (0-4: 0=critical, 1=high, 2=medium, 3=low, 4=backlog)
--priority-max int Filter by maximum priority (inclusive)
--priority-min int Filter by minimum priority (inclusive)
-s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Note: dependency-blocked issues use 'bd blocked'
--title string Filter by title text (case-insensitive substring match)
--title-contains string Filter by title substring
-t, --type string Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate)
--updated-after string Filter issues updated after date (YYYY-MM-DD or RFC3339)
--updated-before string Filter issues updated before date (YYYY-MM-DD or RFC3339)
```

View file

@ -1,35 +0,0 @@
---
id: create-form
title: bd create-form
slug: /cli-reference/create-form
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc create-form`
## bd create-form
Create a new issue using an interactive terminal form.
This command provides a user-friendly form interface for creating issues,
with fields for title, description, type, priority, labels, and more.
Use --parent to create a sub-issue under an existing parent issue.
The child will get an auto-generated hierarchical ID (e.g., parent-id.1).
The form uses keyboard navigation:
- Tab/Shift+Tab: Move between fields
- Enter: Submit the form (on the last field or submit button)
- Ctrl+C: Cancel and exit
- Arrow keys: Navigate within select fields
```
bd create-form [flags]
```
**Flags:**
```
--parent string Parent issue ID for creating a hierarchical child (e.g., 'bd-a3f8e9')
```

View file

@ -1,67 +0,0 @@
---
id: create
title: bd create
slug: /cli-reference/create
sidebar_position: 10
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc create`
## bd create
Create a new issue (or batch from markdown/graph JSON)
```
bd create [title] [flags]
```
**Aliases:** new
**Flags:**
```
--acceptance string Acceptance criteria
--append-notes string Append to existing notes (with newline separator)
-a, --assignee string Assignee
--body-file string Read description from file (use - for stdin)
--context string Additional context for the issue
--defer string Defer until date (issue hidden from bd ready until then). Same formats as --due
--deps strings Dependencies in format 'type:id' or 'id' (e.g., 'discovered-from:bd-20,blocks:bd-15' or 'bd-20')
-d, --description string Issue description
--design string Design notes
--design-file string Read design from file (use - for stdin)
--dry-run Preview what would be created without actually creating
--due string Due date/time. Formats: +6h, +1d, +2w, tomorrow, next monday, 2025-01-15
--ephemeral Create as ephemeral (short-lived, subject to TTL compaction)
-e, --estimate int Time estimate in minutes (e.g., 60 for 1 hour)
--event-actor string Entity URI who caused this event (requires --type=event)
--event-category string Event category (e.g., patrol.muted, agent.started) (requires --type=event)
--event-payload string Event-specific JSON data (requires --type=event)
--event-target string Entity URI or bead ID affected (requires --type=event)
--external-ref string External reference (e.g., 'gh-9', 'jira-ABC', Linear URL)
-f, --file string Create multiple issues from markdown file
--force Force creation even if prefix doesn't match database prefix
--graph string Create a graph of issues with dependencies from JSON plan file
--id string Explicit issue ID (e.g., 'bd-42' for partitioning)
-l, --labels strings Labels (comma-separated)
--metadata string Set custom metadata (JSON string or @file.json to read from file)
--mol-type string Molecule type: swarm (multi-agent), patrol (recurring ops), work (default)
--no-history Skip Dolt commit history without making GC-eligible (for permanent agent beads)
--no-inherit-labels Don't inherit labels from parent issue
--notes string Additional notes
--parent string Parent issue ID for hierarchical child (e.g., 'bd-a3f8e9')
-p, --priority string Priority (0-4 or P0-P4, 0=highest) (default "2")
--repo string Target repository for issue (overrides auto-routing)
--silent Output only the issue ID (for scripting)
--skills string Required skills for this issue
--spec-id string Link to specification document
-s, --status string Initial status
--stdin Read description from stdin (alias for --body-file -)
--title string Issue title (alternative to positional argument)
-t, --type string Issue type (bug|feature|task|epic|chore|decision|spike|story|milestone); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision (default "task")
--validate Validate description contains required sections for issue type
--waits-for string Spawner issue ID to wait for (creates waits-for dependency for fanout gate)
--waits-for-gate string Gate type: all-children (wait for all) or any-children (wait for first) (default "all-children")
--wisp-type string Wisp type for TTL-based compaction: heartbeat, ping, patrol, gc_report, recovery, error, escalation
```

View file

@ -1,37 +0,0 @@
---
id: defer
title: bd defer
slug: /cli-reference/defer
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc defer`
## bd defer
Defer issues to put them on ice for later.
Deferred issues are deliberately set aside - not blocked by anything specific,
just postponed for future consideration. Unlike blocked issues, there's no
dependency keeping them from being worked. Unlike closed issues, they will
be revisited.
Deferred issues don't show in 'bd ready' but remain visible in 'bd list'.
Examples:
bd defer bd-abc # Defer a single issue (status-based)
bd defer bd-abc --until=tomorrow # Defer until specific time
bd defer bd-abc --reason="waiting on API access"
bd defer bd-abc bd-def # Defer multiple issues
```
bd defer [id...] [flags]
```
**Flags:**
```
--reason string Record why this issue is being deferred (appended to notes)
--until string Defer until specific time (e.g., +1h, tomorrow, next monday)
```

View file

@ -1,52 +0,0 @@
---
id: delete
title: bd delete
slug: /cli-reference/delete
sidebar_position: 70
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc delete`
## bd delete
Delete one or more issues and clean up all references to them.
This command will:
1. Remove all dependency links (any type, both directions) involving the issues
2. Update text references to "[deleted:ID]" in directly connected issues
3. Permanently delete the issues from the database
This is a destructive operation that cannot be undone. Use with caution.
BATCH DELETION:
Delete multiple issues at once:
bd delete bd-1 bd-2 bd-3 --force
Delete from file (one ID per line):
bd delete --from-file deletions.txt --force
Preview before deleting:
bd delete --from-file deletions.txt --dry-run
DEPENDENCY HANDLING:
Default: Fails if any issue has dependents not in deletion set
bd delete bd-1 bd-2
Cascade: Recursively delete all dependents
bd delete bd-1 --cascade --force
Force: Delete and orphan dependents
bd delete bd-1 --force
```
bd delete <issue-id> [issue-id...] [flags]
```
**Flags:**
```
--cascade Recursively delete all dependent issues
--dry-run Preview what would be deleted without making changes
-f, --force Actually delete (without this flag, shows preview)
--from-file string Read issue IDs from file (one per line)
```

View file

@ -1,186 +0,0 @@
---
id: dep
title: bd dep
slug: /cli-reference/dep
sidebar_position: 100
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc dep`
## bd dep
Manage dependencies between issues.
When called with an issue ID and --blocks flag, creates a blocking dependency:
bd dep &lt;blocker-id&gt; --blocks &lt;blocked-id&gt;
This is equivalent to:
bd dep add &lt;blocked-id&gt; &lt;blocker-id&gt;
Examples:
bd dep bd-xyz --blocks bd-abc # bd-xyz blocks bd-abc
bd dep add bd-abc bd-xyz # Same as above (bd-abc depends on bd-xyz)
```
bd dep [issue-id] [flags]
```
**Flags:**
```
-b, --blocks string Issue ID that this issue blocks (shorthand for: bd dep add <blocked> <blocker>)
--no-cycle-check Skip per-edge cycle checks for speed (bulk wiring); bulk --file adds still run one final whole-graph check before commit
```
### bd dep add
Add a dependency between two issues.
The depends-on-id can be provided as:
- A positional argument: bd dep add issue-123 issue-456
- A flag: bd dep add issue-123 --blocked-by issue-456
- A flag: bd dep add issue-123 --depends-on issue-456
The --blocked-by and --depends-on flags are aliases and both mean "issue-123
depends on (is blocked by) the specified issue."
The depends-on-id can be:
- A local issue ID (e.g., bd-xyz)
- An external reference: external:&lt;project&gt;:&lt;capability&gt;
For bulk wiring, pass newline-delimited JSON with --file. Each line must be an
object with "from" and "to" fields, and may include "type". The aliases
"issue_id" and "depends_on_id" are also accepted. Use --file - to read stdin.
External references are stored as-is and resolved at query time using
the external_projects config. They block the issue until the capability
is "shipped" in the target project.
Examples:
bd dep add bd-42 bd-41 # Positional args
bd dep add bd-42 --blocked-by bd-41 # Flag syntax (same effect)
bd dep add bd-42 --depends-on bd-41 # Alias (same effect)
bd dep add gt-xyz external:beads:mol-run-assignee # Cross-project dependency
bd dep add bd-42 bd-41 --no-cycle-check # Skip cycle check (bulk wiring)
bd dep add --file deps.jsonl # Bulk JSONL: &#123;"from":"bd-42","to":"bd-41"&#125;
```
bd dep add [issue-id] [depends-on-id] [flags]
```
**Flags:**
```
--blocked-by string Issue ID that blocks the first issue (alternative to positional arg)
--depends-on string Issue ID that the first issue depends on (alias for --blocked-by)
--file string Read dependency edges from JSONL file, or '-' for stdin
--no-cycle-check Skip per-edge cycle checks for speed (bulk wiring); bulk --file adds still run one final whole-graph check before commit
-t, --type string Dependency type (blocks|tracks|related|parent-child|discovered-from|until|caused-by|validates|relates-to|supersedes) (default "blocks")
```
### bd dep cycles
Detect dependency cycles
```
bd dep cycles [flags]
```
### bd dep list
List dependencies or dependents of one or more issues with optional type filtering.
By default shows dependencies (what issues depend on). Use --direction to control:
- down: Show dependencies (what this issue depends on) - default
- up: Show dependents (what depends on this issue)
Multiple IDs can be provided for batch dep listing. With --json, the output
is a flat array of dependency records across all requested issues.
Use --type to filter by dependency type (e.g., tracks, blocks, parent-child).
Examples:
bd dep list gt-abc # Show what gt-abc depends on
bd dep list gt-abc gt-def # Batch: deps for both issues
bd dep list gt-abc --direction=up # Show what depends on gt-abc
bd dep list gt-abc --direction=up -t tracks # Show what tracks gt-abc (convoy tracking)
```
bd dep list [issue-id...] [flags]
```
**Flags:**
```
--direction string Direction: 'down' (dependencies), 'up' (dependents) (default "down")
-t, --type string Filter by dependency type (e.g., tracks, blocks, parent-child)
```
### bd dep relate
Create a loose 'see also' relationship between two issues.
The relates_to link is bidirectional - both issues will reference each other.
This enables knowledge graph connections without blocking or hierarchy.
Examples:
bd relate bd-abc bd-xyz # Link two related issues
bd relate bd-123 bd-456 # Create see-also connection
```
bd dep relate <id1> <id2> [flags]
```
### bd dep remove
Remove a dependency
```
bd dep remove [issue-id] [depends-on-id] [flags]
```
**Aliases:** rm
### bd dep tree
Show dependency tree rooted at the given issue.
By default, shows dependencies (what blocks this issue). Use --direction to control:
- down: Show dependencies (what blocks this issue) - default
- up: Show dependents (what this issue blocks)
- both: Show full graph in both directions
Examples:
bd dep tree gt-0iqq # Show what blocks gt-0iqq
bd dep tree gt-0iqq --direction=up # Show what gt-0iqq blocks
bd dep tree gt-0iqq --status=open # Only show open issues
bd dep tree gt-0iqq --depth=3 # Limit to 3 levels deep
```
bd dep tree [issue-id] [flags]
```
**Flags:**
```
--direction string Tree direction: 'down' (dependencies), 'up' (dependents), or 'both'
--format string Output format: 'mermaid' for Mermaid.js flowchart
-d, --max-depth int Maximum tree depth to display (safety limit) (default 50)
--reverse Show dependent tree (deprecated: use --direction=up)
--show-all-paths Show all paths to nodes (no deduplication for diamond dependencies)
--status string Filter to only show issues with this status (open, in_progress, blocked, deferred, closed)
```
### bd dep unrelate
Remove a relates_to relationship between two issues.
Removes the link in both directions.
Example:
bd unrelate bd-abc bd-xyz
```
bd dep unrelate <id1> <id2> [flags]
```

View file

@ -1,27 +0,0 @@
---
id: diff
title: bd diff
slug: /cli-reference/diff
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc diff`
## bd diff
Show the differences in issues between two commits or branches.
The refs can be:
- Commit hashes (e.g., abc123def)
- Branch names (e.g., main, feature-branch)
- Special refs like HEAD, HEAD~1
Examples:
bd diff main feature-branch # Compare main to feature branch
bd diff HEAD~5 HEAD # Show changes in last 5 commits
bd diff abc123 def456 # Compare two specific commits
```
bd diff <from-ref> <to-ref> [flags]
```

View file

@ -1,153 +0,0 @@
---
id: doctor
title: bd doctor
slug: /cli-reference/doctor
sidebar_position: 600
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc doctor`
## bd doctor
Sanity check the beads installation for the current directory or specified path.
This command checks:
- If .beads/ directory exists
- Database version and migration status
- Schema compatibility (all required tables and columns present)
- Whether using hash-based vs sequential IDs
- If CLI version is current (checks GitHub releases)
- If Claude plugin is current (when running in Claude Code)
- File permissions
- Circular dependencies
- Git hooks (pre-commit, post-merge, pre-push)
- .beads/.gitignore up to date
- Metadata.json version tracking (LastBdVersion field)
Performance Mode (--perf):
Run performance diagnostics on your database:
- Times key operations (bd ready, bd list, bd show, etc.)
- Collects system info (OS, arch, SQLite version, database stats)
- Generates CPU profile for analysis
- Outputs shareable report for bug reports
Export Mode (--output):
Save diagnostics to a JSON file for historical analysis and bug reporting.
Includes timestamp and platform info for tracking intermittent issues.
Specific Check Mode (--check):
Run a specific check in detail. Available checks:
- artifacts: Detect and optionally clean beads classic artifacts
(stale JSONL, SQLite files, cruft .beads dirs). Use with --clean.
- conventions: Check for convention drift (lint warnings, stale
issues, orphaned issues). Advisory only - warns, never blocks.
- pollution: Detect and optionally clean test issues from database
- validate: Run focused data-integrity checks (duplicates, orphaned
deps, test pollution, git conflicts). Use with --fix to auto-repair.
Deep Validation Mode (--deep):
Validate full graph integrity. May be slow on large databases.
Additional checks:
- Parent consistency: All parent-child deps point to existing issues
- Dependency integrity: All deps reference valid issues
- Epic completeness: Find epics ready to close (all children closed)
- Agent bead integrity: Agent beads have valid state values
- Mail thread integrity: Thread IDs reference existing issues
- Molecule integrity: Molecules have valid parent-child structures
Server Mode (--server):
Run health checks for Dolt server mode connections (bd-dolt.2.3):
- Server reachable: Can connect to configured host:port?
- Dolt version: Is it a Dolt server (not vanilla MySQL)?
- Database exists: Does the 'beads' database exist?
- Schema compatible: Can query beads tables?
- Connection pool: Pool health metrics
Migration Validation Mode (--migration):
Run Dolt migration validation checks with machine-parseable output.
Use --migration=pre before migration to verify readiness:
- JSONL file exists and is valid (parseable, no corruption)
- All JSONL issues are present in SQLite (or explains discrepancies)
- No blocking issues prevent migration
Use --migration=post after migration to verify completion:
- Dolt database exists and is healthy
- All issues from JSONL are present in Dolt
- No data was lost during migration
- Dolt database has no locks or uncommitted changes
Combine with --json for machine-parseable output for automation.
Agent Mode (--agent):
Output diagnostics designed for AI agent consumption. Instead of terse
pass/fail messages, each issue includes:
- Observed state: what the system actually looks like
- Expected state: what it should look like
- Explanation: full prose context about the issue and why it matters
- Commands: exact remediation commands to run
- Source files: where in the codebase to investigate further
- Severity: blocking (prevents operation), degraded (partial function),
or advisory (informational only)
ZFC-compliant: Go observes and reports, the agent decides and acts.
Combine with --json for structured agent-facing output.
Suppressing Warnings:
Suppress specific warnings by setting doctor.suppress.&lt;check-slug&gt; config:
bd config set doctor.suppress.pending-migrations true
bd config set doctor.suppress.git-hooks true
Check names are converted to slugs: "Git Hooks" → "git-hooks".
Only warnings are suppressed; errors and passing checks always show.
To unsuppress: bd config unset doctor.suppress.&lt;slug&gt;
Examples:
bd doctor # Check current directory
bd doctor /path/to/repo # Check specific repository
bd doctor --json # Machine-readable output
bd doctor --agent # Agent-facing diagnostic output
bd doctor --agent --json # Structured agent diagnostics (JSON)
bd doctor --fix # Automatically fix issues (with confirmation)
bd doctor --fix --yes # Automatically fix issues (no confirmation)
bd doctor --fix -i # Confirm each fix individually
bd doctor --fix --fix-child-parent # Also fix child→parent deps (opt-in)
bd doctor --fix --force # Force repair even when database can't be opened
bd doctor --fix --source=jsonl # Rebuild database from a JSONL export
bd doctor --dry-run # Preview what --fix would do without making changes
bd doctor --perf # Performance diagnostics
bd doctor --output diagnostics.json # Export diagnostics to file
bd doctor --check=artifacts # Show classic artifacts (JSONL, SQLite, cruft dirs)
bd doctor --check=artifacts --clean # Delete safe-to-delete artifacts (with confirmation)
bd doctor --check=conventions # Convention drift check (lint, stale, orphans)
bd doctor --check=pollution # Show potential test issues
bd doctor --check=pollution --clean # Delete test issues (with confirmation)
bd doctor --check=validate # Data-integrity checks only
bd doctor --check=validate --fix # Auto-fix data-integrity issues
bd doctor --deep # Full graph integrity validation
bd doctor --server # Dolt server mode health checks
bd doctor --migration=pre # Validate readiness for Dolt migration
bd doctor --migration=post # Validate Dolt migration completed
bd doctor --migration=pre --json # Machine-parseable migration validation
```
bd doctor [path] [flags]
```
**Flags:**
```
--agent Agent-facing diagnostic mode: rich context for AI agents (ZFC-compliant)
--check string Run specific check in detail (e.g., 'pollution')
--check-health Quick health check for git hooks (silent on success)
--clean For pollution check: delete detected test issues
--deep Validate full graph integrity
--dry-run Preview fixes without making changes
--fix Automatically fix issues where possible
--fix-child-parent Remove child→parent dependencies (opt-in)
-i, --interactive Confirm each fix individually
--migration string Run Dolt migration validation: 'pre' (before migration) or 'post' (after migration)
--orchestrator Running in orchestrator multi-workspace mode (routes.jsonl is expected, higher duplicate tolerance)
--orchestrator-duplicates-threshold int Duplicate tolerance threshold for orchestrator mode (wisps are ephemeral) (default 1000)
-o, --output string Export diagnostics to JSON file
--perf Run performance diagnostics and generate CPU profile
--server Run Dolt server mode health checks (connectivity, version, schema)
-v, --verbose Show all checks (default shows only warnings/errors)
-y, --yes Skip confirmation prompt (for non-interactive use)
```

View file

@ -1,304 +0,0 @@
---
id: dolt
title: bd dolt
slug: /cli-reference/dolt
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc dolt`
## bd dolt
Configure and manage Dolt database settings and server lifecycle.
Beads uses a dolt sql-server for all database operations. The server is
auto-started transparently when needed. Use these commands for explicit
control or diagnostics.
Server lifecycle:
bd dolt start Start the Dolt server for this project
bd dolt stop Stop the Dolt server for this project
bd dolt status Show Dolt server status
Configuration:
bd dolt show Show current Dolt configuration with connection test
bd dolt set &lt;k&gt; &lt;v&gt; Set a configuration value
bd dolt test Test server connection
Version control:
bd dolt commit Commit pending changes
bd dolt push Push commits to Dolt remote
bd dolt pull Pull commits from Dolt remote
Remote management:
bd dolt remote add &lt;name&gt; &lt;url&gt; Add a Dolt remote
bd dolt remote list List configured remotes
bd dolt remote remove &lt;name&gt; Remove a Dolt remote
Configuration keys for 'bd dolt set':
database Database name (default: issue prefix or "beads")
host Server host (default: 127.0.0.1)
port Server port (auto-detected; override with bd dolt set port &lt;N&gt;)
user MySQL user (default: root)
data-dir Custom dolt data directory (absolute path; default: .beads/dolt)
Flags for 'bd dolt set':
--update-config Also write to config.yaml for team-wide defaults
Examples:
bd dolt set database myproject
bd dolt set host 192.168.1.100 --update-config
bd dolt set data-dir /home/user/.beads-dolt/myproject
bd dolt test
```
bd dolt [flags]
```
### bd dolt clean-databases
Identify and drop leftover test and agent databases that accumulate
on the shared Dolt server from interrupted test runs and terminated agents.
Stale database prefixes: testdb_*, beads_test*, beads_pt*, beads_vr*, doctest_*, doctortest_*, benchdb_*
These waste server memory and can degrade performance under concurrent load.
Use --dry-run to see what would be dropped without actually dropping.
```
bd dolt clean-databases [flags]
```
**Flags:**
```
--dry-run Show what would be dropped without dropping
```
### bd dolt commit
Create a Dolt commit from any uncommitted changes in the working set.
This is the primary commit point for batch mode. When auto-commit is set to
"batch", changes accumulate in the working set across multiple bd commands and
are committed together here with a descriptive summary message.
Also useful before push operations that require a clean working set, or when
auto-commit was off or changes were made externally.
For more options (--stdin, custom messages), see: bd vc commit
```
bd dolt commit [flags]
```
**Flags:**
```
-m, --message string Commit message (default: auto-generated)
```
### bd dolt killall
Find and kill orphan dolt sql-server processes not tracked by the
canonical PID file for the current repo's Dolt data directory.
Under an orchestrator, the canonical server lives at $GT_ROOT/.beads/. Any other
dolt sql-server processes using that shared data directory are considered
orphans and will be killed.
In standalone mode, only dolt sql-server processes using the current
project's Dolt data directory are eligible for cleanup. Other projects'
servers are preserved.
```
bd dolt killall [flags]
```
### bd dolt pull
Pull commits from the configured Dolt remote into the local database.
Requires a Dolt remote to be configured in the database directory.
For Hosted Dolt, set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD environment
variables for authentication.
Use --remote to pull from a specific named remote instead of the default.
The remote must already exist (see 'bd dolt remote add').
```
bd dolt pull [flags]
```
**Flags:**
```
--remote string Pull from a specific named remote instead of the default
```
### bd dolt push
Push local Dolt commits to the configured remote.
Requires a Dolt remote to be configured in the database directory.
For Hosted Dolt, set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD environment
variables for authentication.
Use --force to overwrite remote changes (e.g., when the remote has
uncommitted changes in its working set).
Use --remote to push to a specific named remote instead of the default.
The remote must already exist (see 'bd dolt remote add').
```
bd dolt push [flags]
```
**Flags:**
```
--force Force push (overwrite remote changes)
--remote string Push to a specific named remote instead of the default
```
### bd dolt remote
Manage Dolt remotes for push/pull replication.
Subcommands:
add &lt;name&gt; &lt;url&gt; Add a new remote
list List all configured remotes
remove &lt;name&gt; Remove a remote
```
bd dolt remote [flags]
```
#### bd dolt remote add
Add a Dolt remote
```
bd dolt remote add <name> <url> [flags]
```
**Flags:**
```
--allow-git-origin Allow adding a Dolt remote whose URL matches the git origin (proceed with a warning instead of aborting)
```
#### bd dolt remote list
List configured Dolt remotes
```
bd dolt remote list [flags]
```
#### bd dolt remote remove
Remove a Dolt remote
```
bd dolt remote remove <name> [flags]
```
### bd dolt set
Set a Dolt configuration value in metadata.json.
Keys:
database Database name (default: issue prefix or "beads")
host Server host (default: 127.0.0.1)
port Server port (auto-detected; override with bd dolt set port &lt;N&gt;)
user MySQL user (default: root)
data-dir Custom dolt data directory (absolute path; default: .beads/dolt)
Use --update-config to also write to config.yaml for team-wide defaults.
Examples:
bd dolt set database myproject
bd dolt set host 192.168.1.100
bd dolt set port 3307 --update-config
bd dolt set data-dir /home/user/.beads-dolt/myproject
```
bd dolt set <key> <value> [flags]
```
**Flags:**
```
--update-config Also write to config.yaml for team-wide defaults
```
### bd dolt show
Show current Dolt configuration with connection status
```
bd dolt show [flags]
```
### bd dolt start
Start a dolt sql-server for the current beads project.
The server runs in the background on a per-project port derived from the
project path. PID and logs are stored in .beads/.
The server auto-starts transparently when needed, so manual start is rarely
required. Use this command for explicit control or diagnostics.
```
bd dolt start [flags]
```
### bd dolt status
Show the status of the Dolt engine for the current project.
In embedded mode, reports that the Dolt engine runs in-process and shows
the on-disk data directory. For beads-managed (local) servers, displays
PID, port, and data directory from the local PID file. For externally-
managed servers — a shared server (dolt.shared-server: true), a remote
dolt_server_host, or a local server managed outside bd (dolt.auto-start:
false, e.g. an orchestrator-shared sql-server) — pings the configured
endpoint via SQL and reports reachability, server version, and database.
```
bd dolt status [flags]
```
### bd dolt stop
Stop the dolt sql-server managed by beads for the current project.
This sends a graceful shutdown signal. The server will restart automatically
on the next bd command unless auto-start is disabled.
```
bd dolt stop [flags]
```
**Flags:**
```
--force Force stop the server
```
### bd dolt test
Test the connection to the configured Dolt server.
This verifies that:
1. The server is reachable at the configured host:port
2. The connection can be established
Use this before switching to server mode to ensure the server is running.
```
bd dolt test [flags]
```

View file

@ -1,29 +0,0 @@
---
id: duplicate
title: bd duplicate
slug: /cli-reference/duplicate
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc duplicate`
## bd duplicate
Mark an issue as a duplicate of a canonical issue.
The duplicate issue is automatically closed with a reference to the canonical.
This is essential for large issue databases with many similar reports.
Examples:
bd duplicate bd-abc --of bd-xyz # Mark bd-abc as duplicate of bd-xyz
```
bd duplicate <id> --of <canonical> [flags]
```
**Flags:**
```
--of string Canonical issue ID (required)
```

View file

@ -1,33 +0,0 @@
---
id: duplicates
title: bd duplicates
slug: /cli-reference/duplicates
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc duplicates`
## bd duplicates
Find issues with identical content (title, description, design, acceptance criteria).
Groups issues by content hash and reports duplicates with suggested merge targets.
The merge target is chosen by:
1. Reference count (most referenced issue wins)
2. Lexicographically smallest ID if reference counts are equal
Only groups issues with matching status (open with open, closed with closed).
Example:
bd duplicates # Show all duplicate groups
bd duplicates --auto-merge # Automatically merge all duplicates
bd duplicates --dry-run # Show what would be merged
```
bd duplicates [flags]
```
**Flags:**
```
--auto-merge Automatically merge all duplicates
--dry-run Show what would be merged without making changes
```

View file

@ -1,36 +0,0 @@
---
id: edit
title: bd edit
slug: /cli-reference/edit
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc edit`
## bd edit
Edit an issue field using your configured $EDITOR.
By default, edits the description. Use flags to edit other fields.
Examples:
bd edit bd-42 # Edit description
bd edit bd-42 --title # Edit title
bd edit bd-42 --design # Edit design notes
bd edit bd-42 --notes # Edit notes
bd edit bd-42 --acceptance # Edit acceptance criteria
```
bd edit [id] [flags]
```
**Flags:**
```
--acceptance Edit the acceptance criteria
--description Edit the description (default)
--design Edit the design notes
--notes Edit the notes
--title Edit the title
```

View file

@ -1,45 +0,0 @@
---
id: epic
title: bd epic
slug: /cli-reference/epic
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc epic`
## bd epic
Epic management commands
```
bd epic [flags]
```
### bd epic close-eligible
Close epics where all children are complete
```
bd epic close-eligible [flags]
```
**Flags:**
```
--dry-run Preview what would be closed without making changes
```
### bd epic status
Show epic completion status
```
bd epic status [flags]
```
**Flags:**
```
--eligible-only Show only epics eligible for closure
```

View file

@ -1,52 +0,0 @@
---
id: export
title: bd export
slug: /cli-reference/export
sidebar_position: 220
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc export`
## bd export
Export all issues to JSONL (newline-delimited JSON) format.
Each line is a complete JSON object representing one issue, including its
labels, dependencies, and comments.
This command is for issue export, migration, and interoperability. It exports
records from the issues table; it is not a full database backup and does not
capture Dolt branches, commit history, working-set state, or non-issue tables.
For supported full backup/restore flows, use 'bd backup init', 'bd backup sync',
and 'bd backup restore'.
By default, exports only regular issues (excluding infrastructure beads
like agents, roles, and messages). Use --all to include everything.
Memories (from 'bd remember') are excluded by default because they may
contain sensitive agent context. Use --include-memories or --all to
include them.
EXAMPLES:
bd export # Export issues to stdout
bd export -o issues.jsonl # Export issues to file
bd export --include-memories # Export issues + memories
bd export --all -o full.jsonl # Include infra + templates + gates + memories
bd export --scrub -o clean.jsonl # Exclude test/pollution records
```
bd export [flags]
```
**Flags:**
```
--all Include all records (infra, templates, gates, memories)
--exclude-owner stringArray Exclude issues created by this identity (repeatable; also reads export.exclude_owners config)
--include-infra Include infrastructure beads (agents, roles, messages)
--include-memories Include persistent memories (from 'bd remember') in the export
-o, --output string Output file path (default: stdout)
--scrub Exclude test/pollution records
--verbose Print filtered issue count when owners are excluded
```

View file

@ -1,24 +0,0 @@
---
id: federation
title: bd federation
slug: /cli-reference/federation
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc federation`
## bd federation
Federation commands require CGO and the Dolt storage backend.
This binary was built without CGO support. To use federation features:
1. Use pre-built binaries from GitHub releases, or
2. Build from source with CGO enabled
Federation enables synchronized issue tracking across multiple workspaces,
each maintaining their own Dolt database while sharing updates via remotes.
```
bd federation [flags]
```

View file

@ -1,53 +0,0 @@
---
id: find-duplicates
title: bd find-duplicates
slug: /cli-reference/find-duplicates
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc find-duplicates`
## bd find-duplicates
Find issues that are semantically similar but not exact duplicates.
Unlike 'bd duplicates' which finds exact content matches, find-duplicates
uses text similarity or AI to find issues that discuss the same topic
with different wording.
Approaches:
mechanical Token-based text similarity (default, no API key needed)
ai LLM-based semantic comparison (requires ANTHROPIC_API_KEY or ai.api_key)
The mechanical approach tokenizes titles and descriptions, then computes
Jaccard similarity between all issue pairs. It's fast and free but may
miss semantically similar issues with very different wording.
The AI approach sends candidate pairs to Claude for semantic comparison.
It first uses mechanical pre-filtering to reduce the number of API calls,
then asks the LLM to judge whether the remaining pairs are true duplicates.
Examples:
bd find-duplicates # Mechanical similarity (default)
bd find-duplicates --threshold 0.4 # Lower threshold = more results
bd find-duplicates --method ai # Use AI for semantic comparison
bd find-duplicates --status open # Only check open issues
bd find-duplicates --limit 20 # Show top 20 pairs
bd find-duplicates --json # JSON output
```
bd find-duplicates [flags]
```
**Aliases:** find-dups
**Flags:**
```
-n, --limit int Maximum number of pairs to show (default 50)
--method string Detection method: mechanical, ai (default "mechanical")
--model string AI model to use (only with --method ai; default from config ai.model)
-s, --status string Filter by status (default: non-closed)
--threshold float Similarity threshold (0.0-1.0, lower = more results) (default 0.5)
```

View file

@ -1,44 +0,0 @@
---
id: flatten
title: bd flatten
slug: /cli-reference/flatten
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc flatten`
## bd flatten
Nuclear option: squash ALL Dolt commit history into a single commit.
This uses the Tim Sehn recipe:
1. Create a new branch from the current state
2. Soft-reset to the initial commit (preserving all data)
3. Commit everything as a single snapshot
4. Swap main branch to the new flattened branch
5. Run Dolt GC to reclaim space from old history
This is irreversible — all commit history is lost. The resulting database
has exactly one commit containing all current data.
Use this when:
- Your .beads/dolt directory has grown very large
- You don't need commit-level history (time travel)
- You want to start fresh with minimal storage
Examples:
bd flatten --dry-run # Preview: show commit count and disk usage
bd flatten --force # Actually squash all history
bd flatten --force --json # JSON output
```
bd flatten [flags]
```
**Flags:**
```
--dry-run Preview without making changes
-f, --force Confirm irreversible history squash
```

View file

@ -1,23 +0,0 @@
---
id: forget
title: bd forget
slug: /cli-reference/forget
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc forget`
## bd forget
Remove a memory by its key.
Use 'bd memories' to see available keys.
Examples:
bd forget dolt-phantoms
bd forget auth-jwt
```
bd forget <key> [flags]
```

View file

@ -1,147 +0,0 @@
---
id: formula
title: bd formula
slug: /cli-reference/formula
sidebar_position: 310
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc formula`
## bd formula
Manage workflow formulas - the source layer for molecule templates.
Formulas are TOML/JSON files that define workflows with composition rules.
Define formulas, cook them into protos, then pour or wisp them into work.
Search paths (in order):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Commands:
list List available formulas from all search paths
show Show formula details, steps, and composition rules
schema Show the formula schema index (alias: primitives)
Discovering primitives:
bd formula schema # list every declared formula struct
bd formula schema loop # show LoopSpec fields, types, and tags
bd formula primitives gate # alias; same handler as 'schema'
examples/formulas/primitives/ # curated, smoke-tested wired fixtures
website/docs/workflows/formulas.md # narrative reference
```
bd formula [flags]
```
### bd formula convert
Convert formula files from JSON to TOML format.
TOML format provides better ergonomics:
- Multi-line strings without \n escaping
- Human-readable diffs
- Comments allowed
The convert command reads a .formula.json file and outputs .formula.toml.
The original JSON file is preserved (use --delete to remove it).
Examples:
bd formula convert shiny # Convert shiny.formula.json to .toml
bd formula convert ./my.formula.json # Convert specific file
bd formula convert --all # Convert all JSON formulas
bd formula convert shiny --delete # Convert and remove JSON file
bd formula convert shiny --stdout # Print TOML to stdout
```
bd formula convert <formula-name|path> [--all] [flags]
```
**Flags:**
```
--all Convert all JSON formulas
--delete Delete JSON file after conversion
--stdout Print TOML to stdout instead of file
```
### bd formula list
List all formulas from search paths.
Search paths (in order of priority):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project - highest priority)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Formulas in earlier paths shadow those with the same name in later paths.
To list the declared formula schema structs an agent can write inside a .formula.toml,
use 'bd formula schema' (alias: 'bd formula primitives').
Examples:
bd formula list
bd formula list --json
bd formula list --type workflow
bd formula list --type convoy
```
bd formula list [flags]
```
**Flags:**
```
--type string Filter by type (workflow, expansion, aspect, convoy)
```
### bd formula schema
Show the formula schema index: every exported struct declared
in a .formula.toml/.formula.json, with field names, types, and tags.
The index is generated from internal/formula/types.go via go:generate; the
struct definitions are the source of truth, so this list cannot drift. It is
structural reference, not proof that every declared runtime behavior is wired.
Examples:
bd formula schema # list every declared schema struct
bd formula schema loop # show LoopSpec fields
bd formula primitives gate # alias; shows Gate fields
bd formula schema --json # machine-readable index
Curated smoke-tested fixtures for wired primitives live in
examples/formulas/primitives/ (with a smoke harness that proves they work).
```
bd formula schema [primitive] [flags]
```
**Aliases:** primitives
### bd formula show
Show detailed information about a formula.
Displays:
- Formula metadata (name, type, description)
- Variables with defaults and constraints
- Steps with dependencies
- Composition rules (extends, aspects, expansions)
- Bond points for external composition
To inspect the structure of an individual primitive (e.g. LoopSpec, Gate)
rather than a user-authored formula, use 'bd formula schema &lt;primitive&gt;'.
Examples:
bd formula show shiny
bd formula show rule-of-five
bd formula show security-audit --json
```
bd formula show <formula-name> [flags]
```

View file

@ -1,207 +0,0 @@
---
id: gate
title: bd gate
slug: /cli-reference/gate
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc gate`
## bd gate
Gates are async wait conditions that block workflow steps.
Gates are created automatically when a formula step has a gate field.
They must be closed (manually or via watchers) for the blocked step to proceed.
Gate types:
human - Requires manual bd close (Phase 1)
timer - Expires after timeout (Phase 2)
gh:run - Waits for GitHub workflow (Phase 3)
gh:pr - Waits for PR merge (Phase 3)
bead - Waits for cross-rig bead to close (Phase 4)
For bead gates, await_id format is &lt;rig&gt;:&lt;bead-id&gt; (e.g., "other-project:op-abc123").
Examples:
bd gate list # Show all open gates
bd gate list --all # Show all gates including closed
bd gate check # Evaluate all open gates
bd gate check --type=bead # Evaluate only bead gates
bd gate resolve &lt;id&gt; # Close a gate manually
```
bd gate [flags]
```
### bd gate add-waiter
Register an agent as a waiter on a gate bead.
When the gate closes, the waiter will receive a wake notification via 'bd gate wake'.
The waiter is typically the worker's address (e.g., "my-project/workers/agent-1").
This is used by 'bd done --phase-complete' to register for gate wake notifications.
```
bd gate add-waiter <gate-id> <waiter> [flags]
```
### bd gate check
Evaluate gate conditions and automatically close resolved gates.
By default, checks all open gates. Use --type to filter by gate type.
Gate types:
gh - Check all GitHub gates (gh:run and gh:pr)
gh:run - Check GitHub Actions workflow runs
gh:pr - Check pull request merge status
timer - Check timer gates (auto-expire based on timeout)
bead - Check cross-rig bead gates
all - Check all gate types
GitHub gates use the 'gh' CLI to query status:
- gh:run checks 'gh run view &lt;id&gt; --json status,conclusion'
- gh:pr checks 'gh pr view &lt;id&gt; --json state,title'
A gate is resolved when:
- gh:run: status=completed AND conclusion=success
- gh:pr: state=MERGED
- timer: current time &gt; created_at + timeout
- bead: target bead status=closed
A gate is escalated when:
- gh:run: status=completed AND conclusion in (failure, canceled)
- gh:pr: state=CLOSED
Examples:
bd gate check # Check all gates
bd gate check --type=gh # Check only GitHub gates
bd gate check --type=gh:run # Check only workflow run gates
bd gate check --type=timer # Check only timer gates
bd gate check --type=bead # Check only cross-rig bead gates
bd gate check --dry-run # Show what would happen without changes
bd gate check --escalate # Escalate expired/failed gates
```
bd gate check [flags]
```
**Flags:**
```
--dry-run Show what would happen without making changes
-e, --escalate Escalate failed/expired gates
-l, --limit int Limit results (default 100) (default 100)
-t, --type string Gate type to check (gh, gh:run, gh:pr, timer, bead, all)
```
### bd gate create
Create an ad-hoc gate issue that blocks another issue until resolved.
The blocked issue will not appear in 'bd ready' until the gate is resolved
via 'bd gate resolve'.
Gate types:
human - Requires manual 'bd gate resolve' (default)
timer - Auto-resolves after --timeout duration
gh:run - Waits for GitHub Actions workflow
gh:pr - Waits for PR merge
Examples:
bd gate create --blocks bd-abc
bd gate create --type=human --blocks bd-abc --reason="Need design review"
bd gate create --type=timer --blocks bd-abc --timeout=2h
bd gate create --type=gh:pr --blocks bd-abc --await-id=42
```
bd gate create [flags]
```
**Flags:**
```
--await-id string Condition identifier (run ID, PR number, etc.)
--blocks string Issue ID to block (required)
-r, --reason string Reason for the gate
--timeout string Timeout duration (e.g., 2h, 30m)
-t, --type string Gate type (human, timer, gh:run, gh:pr) (default "human")
```
### bd gate discover
Discovers GitHub workflow run IDs for gates awaiting CI/CD completion.
This command finds open gates with await_type="gh:run" that don't have an await_id,
queries recent GitHub workflow runs, and matches them using heuristics:
- Branch name matching
- Commit SHA matching
- Time proximity (runs within 5 minutes of gate creation)
Once matched, the gate's await_id is updated with the GitHub run ID, enabling
subsequent polling to check the run's status.
Examples:
bd gate discover # Auto-discover run IDs for all matching gates
bd gate discover --dry-run # Preview what would be matched (no updates)
bd gate discover --branch main --limit 10 # Only match runs on 'main' branch
```
bd gate discover [flags]
```
**Flags:**
```
-b, --branch string Filter runs by branch (default: current branch)
-n, --dry-run Preview mode: show matches without updating
-l, --limit int Max runs to query from GitHub (default 10)
-a, --max-age duration Max age for gate/run matching (default 30m0s)
```
### bd gate list
List all gate issues in the current beads database.
By default, shows only open gates. Use --all to include closed gates.
```
bd gate list [flags]
```
**Flags:**
```
-a, --all Show all gates including closed
-n, --limit int Limit results (default 50) (default 50)
```
### bd gate resolve
Close a gate issue to unblock the step waiting on it.
This is equivalent to 'bd close &lt;gate-id&gt;' but with a more explicit name.
Use --reason to provide context for why the gate was resolved.
```
bd gate resolve <gate-id> [flags]
```
**Flags:**
```
-r, --reason string Reason for resolving the gate
```
### bd gate show
Display details of a gate issue including its waiters.
This is similar to 'bd show' but validates that the issue is a gate.
```
bd gate show <gate-id> [flags]
```

View file

@ -1,43 +0,0 @@
---
id: gc
title: bd gc
slug: /cli-reference/gc
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc gc`
## bd gc
Full lifecycle garbage collection for standalone Beads databases.
Runs three phases in sequence:
1. DECAY — Delete closed issues older than N days (default 90)
2. COMPACT — Squash old Dolt commits into fewer commits (bd compact)
3. GC — Run Dolt garbage collection to reclaim disk space
Each phase can be skipped individually. Use --dry-run to preview all phases
without making changes.
Examples:
bd gc # Full GC with defaults (90 day decay)
bd gc --dry-run # Preview what would happen
bd gc --older-than 30 # Decay issues closed 30+ days ago
bd gc --skip-decay # Skip issue deletion, just compact+GC
bd gc --skip-dolt # Skip Dolt GC, just decay+compact
bd gc --force # Skip confirmation prompt
```
bd gc [flags]
```
**Flags:**
```
--dry-run Preview without making changes
-f, --force Skip confirmation prompts
--older-than int Delete closed issues older than N days (default 90)
--skip-decay Skip issue deletion phase
--skip-dolt Skip Dolt garbage collection phase
```

View file

@ -1,101 +0,0 @@
---
id: github
title: bd github
slug: /cli-reference/github
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc github`
## bd github
Commands for syncing issues between beads and GitHub.
Configuration can be set via 'bd config' or environment variables:
github.token / GITHUB_TOKEN - Personal access token
github.owner / GITHUB_OWNER - Repository owner
github.repo / GITHUB_REPO - Repository name
github.repository / GITHUB_REPOSITORY - Combined "owner/repo" format
github.url / GITHUB_API_URL - Custom API URL (GitHub Enterprise)
```
bd github [flags]
```
### bd github pull
Pull one or more items from GitHub.
Accepts bead IDs or external references as positional arguments.
Equivalent to: bd github sync --pull-only --issues &lt;refs&gt;
```
bd github pull [refs...] [flags]
```
**Flags:**
```
--dry-run Preview pull without making changes
```
### bd github push
Push one or more beads issues to GitHub.
Accepts bead IDs as positional arguments.
Equivalent to: bd github sync --push-only --issues &lt;ids&gt;
```
bd github push [bead-ids...] [flags]
```
**Flags:**
```
--dry-run Preview push without making changes
```
### bd github repos
List GitHub repositories that the configured token has access to.
```
bd github repos [flags]
```
### bd github status
Display current GitHub configuration and sync status.
```
bd github status [flags]
```
### bd github sync
Synchronize issues between beads and GitHub.
By default, performs bidirectional sync:
- Pulls new/updated issues from GitHub to beads
- Pushes local beads issues to GitHub
Use --pull-only or --push-only to limit direction.
```
bd github sync [flags]
```
**Flags:**
```
--dry-run Show what would be synced without making changes
--issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
--parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues.
--prefer-github On conflict, use GitHub version
--prefer-local On conflict, keep local beads version
--prefer-newer On conflict, use most recent version (default)
--pull-only Only pull issues from GitHub
--push-only Only push issues to GitHub
```

View file

@ -1,108 +0,0 @@
---
id: gitlab
title: bd gitlab
slug: /cli-reference/gitlab
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc gitlab`
## bd gitlab
Commands for syncing issues between beads and GitLab.
Configuration can be set via 'bd config' or environment variables:
gitlab.url / GITLAB_URL - GitLab instance URL
gitlab.token / GITLAB_TOKEN - Personal access token
gitlab.project_id / GITLAB_PROJECT_ID - Project ID or path
gitlab.group_id / GITLAB_GROUP_ID - Group ID for group-level sync
gitlab.default_project_id / GITLAB_DEFAULT_PROJECT_ID - Project for creating issues in group mode
```
bd gitlab [flags]
```
### bd gitlab projects
List GitLab projects that the configured token has access to.
```
bd gitlab projects [flags]
```
### bd gitlab pull
Pull one or more items from GitLab.
Accepts bead IDs or external references as positional arguments.
Equivalent to: bd gitlab sync --pull-only --issues &lt;refs&gt;
```
bd gitlab pull [refs...] [flags]
```
**Flags:**
```
--dry-run Preview pull without making changes
```
### bd gitlab push
Push one or more beads issues to GitLab.
Accepts bead IDs as positional arguments.
Equivalent to: bd gitlab sync --push-only --issues &lt;ids&gt;
```
bd gitlab push [bead-ids...] [flags]
```
**Flags:**
```
--dry-run Preview push without making changes
```
### bd gitlab status
Display current GitLab configuration and sync status.
```
bd gitlab status [flags]
```
### bd gitlab sync
Synchronize issues between beads and GitLab.
By default, performs bidirectional sync:
- Pulls new/updated issues from GitLab to beads
- Pushes local beads issues to GitLab
Use --pull-only or --push-only to limit direction.
```
bd gitlab sync [flags]
```
**Flags:**
```
--assignee string Filter by assignee username
--dry-run Show what would be synced without making changes
--exclude-type string Exclude these issue types from sync (comma-separated)
--issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
--label string Filter by labels (comma-separated, AND logic)
--milestone string Filter by milestone title
--no-ephemeral Exclude ephemeral/wisp issues from push (default: true) (default true)
--parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues.
--prefer-gitlab On conflict, use GitLab version
--prefer-local On conflict, keep local beads version
--prefer-newer On conflict, use most recent version (default)
--project string Filter to issues from this project ID (group mode)
--pull-only Only pull issues from GitLab
--push-only Only push issues to GitLab
--type string Only sync these issue types (comma-separated, e.g. 'epic,feature,task')
```

View file

@ -1,64 +0,0 @@
---
id: graph
title: bd graph
slug: /cli-reference/graph
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc graph`
## bd graph
Display a visualization of an issue's dependency graph.
For epics, shows all children and their dependencies.
For regular issues, shows the issue and its direct dependencies.
With --all, shows all open issues grouped by connected component.
Display formats:
(default) DAG with columns and box-drawing edges (terminal-native)
--box ASCII boxes showing layers, more detailed
--compact Tree format, one line per issue, more scannable
--dot Graphviz DOT format (pipe to dot -Tsvg &gt; graph.svg)
--html Self-contained interactive HTML with D3.js visualization
The graph shows execution order:
- Layer 0 / leftmost = no dependencies (can start immediately)
- Higher layers depend on lower layers
- Nodes in the same layer can run in parallel
Status icons: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred
Examples:
bd graph issue-id # Terminal DAG visualization (default)
bd graph --box issue-id # ASCII boxes with layer grouping
bd graph --dot issue-id | dot -Tsvg &gt; graph.svg # SVG via Graphviz
bd graph --dot issue-id | dot -Tpng &gt; graph.png # PNG via Graphviz
bd graph --html issue-id &gt; graph.html # Interactive browser view
bd graph --all --html &gt; all.html # All issues, interactive
```
bd graph [issue-id] [flags]
```
**Flags:**
```
--all Show graph for all open issues
--box ASCII boxes showing layers
--compact Tree format, one line per issue, more scannable
--dot Output Graphviz DOT format (pipe to: dot -Tsvg > graph.svg)
--html Output self-contained interactive HTML (redirect to file)
```
### bd graph check
Check the dependency graph for cycles, orphans, and other integrity issues.
Returns exit code 0 if the graph is clean, 1 if issues are found.
```
bd graph check [flags]
```

View file

@ -1,34 +0,0 @@
---
id: heartbeat
title: bd heartbeat
slug: /cli-reference/heartbeat
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc heartbeat`
## bd heartbeat
Refresh the lease on an issue you currently hold in_progress.
A claim carries a lease that expires after a TTL. A worker keeps its claim alive
by heartbeating faster than the TTL; once it stops (because it died), the lease
goes stale and 'bd reclaim' reverts the issue to ready so another worker can pick
it up. Heartbeat pushes lease_expires_at forward and stamps heartbeat_at = now.
Only the current owner may heartbeat. If the lease has already been reclaimed or
the issue closed, heartbeat fails so the worker learns to stop.
Heartbeat writes a Dolt commit, so heartbeat well below the TTL but not so fast
it bloats history — cadence should be a small fraction of the TTL, not per-op.
Examples:
bd heartbeat bd-123
bd hb bd-123
```
bd heartbeat <id> [flags]
```
**Aliases:** hb

View file

@ -1,30 +0,0 @@
---
id: history
title: bd history
slug: /cli-reference/history
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc history`
## bd history
Show the complete version history of an issue, including all commits
where the issue was modified.
Examples:
bd history bd-123 # Show all history for issue bd-123
bd history bd-123 --limit 5 # Show last 5 changes
bd history bd-123 --events # Show database audit events
```
bd history <id> [flags]
```
**Flags:**
```
--events Show database audit events instead of commit snapshots
--limit int Limit number of history entries (0 = all)
```

View file

@ -1,91 +0,0 @@
---
id: hooks
title: bd hooks
slug: /cli-reference/hooks
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc hooks`
## bd hooks
Install, uninstall, or list git hooks for beads integration.
The hooks provide:
- pre-commit: Run chained hooks before commit
- post-merge: Run chained hooks after pull/merge
- pre-push: Run chained hooks before push
- post-checkout: Run chained hooks after branch checkout
- prepare-commit-msg: Add agent identity trailers for forensics
```
bd hooks [flags]
```
### bd hooks install
Install git hooks for beads integration.
By default, hooks are installed to .git/hooks/ in the current repository.
Use --beads to install to .beads/hooks/ (recommended for Dolt backend).
Use --shared to install to a versioned directory (.beads-hooks/) that can be
committed to git and shared with team members.
Hooks use section markers to coexist with existing hooks — any user content
outside the markers is preserved across installs and upgrades.
Installed hooks:
- pre-commit: Run chained hooks before commit
- post-merge: Run chained hooks after pull/merge
- pre-push: Run chained hooks before push
- post-checkout: Run chained hooks after branch checkout
- prepare-commit-msg: Add agent identity trailers (for orchestrator agents)
```
bd hooks install [flags]
```
**Flags:**
```
--beads Install hooks to .beads/hooks/ (recommended for Dolt backend)
--chain Chain with existing hooks (run them before bd hooks)
--force Overwrite existing hooks without backup
--shared Install hooks to .beads-hooks/ (versioned) instead of .git/hooks/
```
### bd hooks list
Show the status of bd git hooks (installed, outdated, missing).
```
bd hooks list [flags]
```
### bd hooks run
Execute the logic for a git hook. This command is typically called by
thin shim scripts installed in .git/hooks/.
Supported hooks:
- pre-commit: Run chained hooks before commit
- post-merge: Run chained hooks after pull/merge
- pre-push: Run chained hooks before push
- post-checkout: Run chained hooks after branch checkout
- prepare-commit-msg: Add agent identity trailers for forensics
The thin shim pattern ensures hook logic is always in sync with the
installed bd version - upgrading bd automatically updates hook behavior.
```
bd hooks run <hook-name> [args...] [flags]
```
### bd hooks uninstall
Remove bd git hooks from .git/hooks/ directory.
```
bd hooks uninstall [flags]
```

View file

@ -1,103 +0,0 @@
---
id: human
title: bd human
slug: /cli-reference/human
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc human`
## bd human
Display a focused help menu showing only the most common commands.
bd has 70+ commands - many for AI agents, integrations, and advanced workflows.
This command shows the ~15 essential commands that human users need most often.
For the full command list, run: bd --help
SUBCOMMANDS:
human list List all human-needed beads (issues with 'human' label)
human respond &lt;id&gt; Respond to a human-needed bead (adds comment and closes)
human dismiss &lt;id&gt; Dismiss a human-needed bead permanently
human stats Show summary statistics for human-needed beads
```
bd human [flags]
```
### bd human dismiss
Dismiss a human-needed bead permanently without responding.
The issue is closed with a "Dismissed" reason and optional note.
Examples:
bd human dismiss bd-123
bd human dismiss bd-123 --reason "No longer applicable"
```
bd human dismiss <issue-id> [flags]
```
**Flags:**
```
--reason string Reason for dismissal (optional)
```
### bd human list
List all issues labeled with 'human' tag.
These are issues that require human intervention or input.
Examples:
bd human list
bd human list --status=open
bd human list --json
```
bd human list [flags]
```
**Flags:**
```
-s, --status string Filter by status (open, closed, etc.)
```
### bd human respond
Respond to a human-needed bead by adding a comment and closing it.
The response is added as a comment and the issue is closed with reason "Responded".
Examples:
bd human respond bd-123 --response "Use OAuth2 for authentication"
bd human respond bd-123 -r "Approved, proceed with implementation"
```
bd human respond <issue-id> [flags]
```
**Flags:**
```
-r, --response string Response text (required)
```
### bd human stats
Display summary statistics for human-needed beads.
Shows counts for total, pending (open), responded (closed without dismiss),
and dismissed beads.
Example:
bd human stats
```
bd human stats [flags]
```

View file

@ -1,87 +0,0 @@
---
id: import
title: bd import
slug: /cli-reference/import
sidebar_position: 210
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc import`
## bd import
Import issues from a JSONL file (newline-delimited JSON) into the database.
If no file is specified, imports from the configured import.path under .beads/
(default: issues.jsonl). Use "-" to read from stdin. This is the incremental counterpart to
'bd export': new issues are created and existing issues are updated (upsert
semantics).
Memory records (lines with "_type":"memory") are automatically detected and
imported as persistent memories (equivalent to 'bd remember'). This makes
'bd export | bd import' a full round-trip for both issues and memories.
Each JSONL line should map to an issue. The importer accepts every field
'bd export' emits — see 'bd export' output for the canonical schema. Only
"title" is required; everything else is optional.
Common fields:
title Required. Short summary.
description Long-form body.
design, notes, Additional content sections.
acceptance_criteria
issue_type bug | feature | task | epic | chore | ...
priority 0-4 (0 = critical). 0 is preserved (no omitempty).
status open | in_progress | blocked | closed | ...
(rows with status "tombstone" are skipped)
assignee, owner, Ownership metadata.
created_by
labels Array of strings.
dependencies Array of &#123;issue_id, depends_on_id, type, ...&#125;.
comments Array of comment objects.
external_ref, Cross-system identifiers (e.g. "gh-9").
source_system
due_at, defer_until RFC3339 timestamps for scheduling.
metadata Arbitrary JSON object preserved verbatim.
Timestamps (created_at, updated_at, started_at, closed_at) are preserved
when present in the JSONL and otherwise filled in by the importer. The
legacy "wisp" boolean is accepted as an alias for "ephemeral".
By default a row only rewrites an existing local issue when its
updated_at is strictly newer. Older rows are skipped (reported as
stale_skipped_ids) and rows with the same updated_at keep every local
column — updated_at has second granularity, so a timestamp tie can be
two distinct same-second updates, and the local row wins the tie
(reported as tie_kept_local_ids; the row's labels/comments/dependencies
still merge). The guard is also enforced inside the upsert itself, so a
local update that lands while the import is running is preserved rather
than overwritten. Existing issues that the import did rewrite are listed
with a field-level summary (updated_issues), so local state changed by
an import is visible. To deliberately restore an older snapshot, pass
--allow-stale, which imports every row even when it overwrites newer
local state.
EXAMPLES:
bd import # Import from configured import.path
bd import backup.jsonl # Import from a specific file
bd import -i backup.jsonl # Legacy alias for a specific file
bd import - # Read JSONL from stdin
cat issues.jsonl | bd import - # Pipe JSONL from another tool
bd import --dry-run # Show what would be imported
bd import --dedup # Skip issues with duplicate titles
bd import --allow-stale old.jsonl # Restore an older snapshot (overwrites newer local rows)
bd import --json # Structured output with created and skipped IDs
```
bd import [file|-] [flags]
```
**Flags:**
```
--allow-stale Import rows even when older than the local issue (required to restore an older snapshot)
--dedup Skip lines whose title matches an existing open issue
--dry-run Show what would be imported without importing
-i, --input string Read JSONL from a specific file
```

View file

@ -1,131 +0,0 @@
---
id: index
title: CLI Reference
sidebar_position: 0
---
# CLI Reference
<!-- AUTO-GENERATED: do not edit manually -->
Reference for bd Latest. Generated from `bd help --docs-root`.
This reference covers all 112 live top-level `bd` commands. Regenerate it with:
```bash
./scripts/generate-cli-docs.sh
```
## Commands
- [`bd admin`](./admin.md)
- [`bd ado`](./ado.md)
- [`bd assign`](./assign.md)
- [`bd audit`](./audit.md)
- [`bd backup`](./backup.md)
- [`bd batch`](./batch.md)
- [`bd blocked`](./blocked.md)
- [`bd bootstrap`](./bootstrap.md)
- [`bd branch`](./branch.md)
- [`bd children`](./children.md)
- [`bd close`](./close.md)
- [`bd comment`](./comment.md)
- [`bd comments`](./comments.md)
- [`bd compact`](./compact.md)
- [`bd completion`](./completion.md)
- [`bd config`](./config.md)
- [`bd context`](./context.md)
- [`bd cook`](./cook.md)
- [`bd count`](./count.md)
- [`bd create`](./create.md)
- [`bd create-form`](./create-form.md)
- [`bd defer`](./defer.md)
- [`bd delete`](./delete.md)
- [`bd dep`](./dep.md)
- [`bd diff`](./diff.md)
- [`bd doctor`](./doctor.md)
- [`bd dolt`](./dolt.md)
- [`bd duplicate`](./duplicate.md)
- [`bd duplicates`](./duplicates.md)
- [`bd edit`](./edit.md)
- [`bd epic`](./epic.md)
- [`bd export`](./export.md)
- [`bd federation`](./federation.md)
- [`bd find-duplicates`](./find-duplicates.md)
- [`bd flatten`](./flatten.md)
- [`bd forget`](./forget.md)
- [`bd formula`](./formula.md)
- [`bd gate`](./gate.md)
- [`bd gc`](./gc.md)
- [`bd github`](./github.md)
- [`bd gitlab`](./gitlab.md)
- [`bd graph`](./graph.md)
- [`bd heartbeat`](./heartbeat.md)
- [`bd history`](./history.md)
- [`bd hooks`](./hooks.md)
- [`bd human`](./human.md)
- [`bd import`](./import.md)
- [`bd info`](./info.md)
- [`bd init`](./init.md)
- [`bd init-safety`](./init-safety.md)
- [`bd jira`](./jira.md)
- [`bd kv`](./kv.md)
- [`bd label`](./label.md)
- [`bd linear`](./linear.md)
- [`bd link`](./link.md)
- [`bd lint`](./lint.md)
- [`bd list`](./list.md)
- [`bd mail`](./mail.md)
- [`bd memories`](./memories.md)
- [`bd merge-slot`](./merge-slot.md)
- [`bd metrics`](./metrics.md)
- [`bd migrate`](./migrate.md)
- [`bd migrate-personal`](./migrate-personal.md)
- [`bd mol`](./mol.md)
- [`bd note`](./note.md)
- [`bd notion`](./notion.md)
- [`bd onboard`](./onboard.md)
- [`bd orphans`](./orphans.md)
- [`bd ping`](./ping.md)
- [`bd preflight`](./preflight.md)
- [`bd prime`](./prime.md)
- [`bd priority`](./priority.md)
- [`bd promote`](./promote.md)
- [`bd prune`](./prune.md)
- [`bd purge`](./purge.md)
- [`bd q`](./q.md)
- [`bd query`](./query.md)
- [`bd quickstart`](./quickstart.md)
- [`bd ready`](./ready.md)
- [`bd recall`](./recall.md)
- [`bd reclaim`](./reclaim.md)
- [`bd recompute-blocked`](./recompute-blocked.md)
- [`bd remember`](./remember.md)
- [`bd rename`](./rename.md)
- [`bd rename-prefix`](./rename-prefix.md)
- [`bd reopen`](./reopen.md)
- [`bd repo`](./repo.md)
- [`bd restore`](./restore.md)
- [`bd rules`](./rules.md)
- [`bd search`](./search.md)
- [`bd set-state`](./set-state.md)
- [`bd setup`](./setup.md)
- [`bd ship`](./ship.md)
- [`bd show`](./show.md)
- [`bd sql`](./sql.md)
- [`bd stale`](./stale.md)
- [`bd state`](./state.md)
- [`bd status`](./status.md)
- [`bd statuses`](./statuses.md)
- [`bd supersede`](./supersede.md)
- [`bd swarm`](./swarm.md)
- [`bd tag`](./tag.md)
- [`bd todo`](./todo.md)
- [`bd types`](./types.md)
- [`bd unclaim`](./unclaim.md)
- [`bd undefer`](./undefer.md)
- [`bd update`](./update.md)
- [`bd upgrade`](./upgrade.md)
- [`bd vc`](./vc.md)
- [`bd version`](./version.md)
- [`bd where`](./where.md)
- [`bd worktree`](./worktree.md)

View file

@ -1,40 +0,0 @@
---
id: info
title: bd info
slug: /cli-reference/info
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc info`
## bd info
Display information about the current database.
This command helps debug issues where bd is using an unexpected database. It shows:
- The absolute path to the database file
- Database statistics (issue count)
- Schema information (with --schema flag)
- What's new in recent versions (with --whats-new flag)
Examples:
bd info
bd info --json
bd info --schema --json
bd info --whats-new
bd info --whats-new --json
bd info --thanks
```
bd info [flags]
```
**Flags:**
```
--json Output in JSON format
--schema Include schema information in output
--thanks Show thank you page for contributors
--whats-new Show agent-relevant changes from recent versions
```

View file

@ -1,83 +0,0 @@
---
id: init-safety
title: bd init-safety
slug: /cli-reference/init-safety
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc init-safety`
## bd init-safety
bd init flag safety contract.
Every bd init invocation resolves project_id from exactly one explicitly
named source (local reinit, remote adoption, or a fresh mint). When the
source is ambiguous, bd init refuses.
FLAG SURFACE
bd init Mint a new identity. Bootstraps from
origin if it has refs/dolt/data.
bd init --reinit-local Re-initialize local .beads/ over existing
local data. Does NOT authorize discarding
remote history. If origin has Dolt data
this will refuse — pair with
--discard-remote to override.
bd init --reinit-local \ Discard the remote's Dolt history and
--discard-remote replace it with the local reinit. First
bd dolt push after this will be a
history-replacing force-push.
bd init --force Deprecated alias for --reinit-local.
Kept working for ≥2 releases.
bd init --from-jsonl Import from configured import.path. If
origin has Dolt data, this refuses unless
--discard-remote authorizes replacing that
remote history.
ADOPTING A REMOTE
If you want to use the remote's existing history, use:
bd bootstrap
bd init will automatically suggest this when a remote is detected.
DESTROY-TOKEN (non-interactive only)
When running with no TTY (CI, agents, piped input), --discard-remote
requires an explicit --destroy-token value. The token format is:
DESTROY-&lt;issue-prefix&gt;
For example, if your issue prefix is "bd", the token is "DESTROY-bd":
bd init --reinit-local --discard-remote --destroy-token=DESTROY-bd
In interactive (TTY) mode you confirm via a typed prompt instead. The
token is not echoed by bd's runtime error messages — this is a
deliberate guard against pattern-matched one-liners (see
docs/adr/0002-init-safety-invariants.md).
EXIT CODES
10 refused: remote has Dolt history and you selected local history
without --discard-remote
11 refused: existing local data and you declined the destroy confirm
12 refused: --discard-remote passed without a valid --destroy-token
(non-interactive mode)
RECOVERY
If you hit a refusal, see docs/RECOVERY.md for step-by-step recovery
playbooks for each exit code.
```
bd init-safety [flags]
```

View file

@ -1,104 +0,0 @@
---
id: init
title: bd init
slug: /cli-reference/init
sidebar_position: 400
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc init`
## bd init
Initialize bd in the current directory by creating a .beads/ directory
and its storage (a Dolt database by default). Optionally specify a custom issue prefix.
Dolt is the default backend and the only one with version control (history,
branching, sync). Select an alternative with --backend=&lt;postgres|mysql|sqlite&gt;;
see docs/STORAGE-BACKENDS.md for the trade-offs and setup.
Use --database to specify an existing server database name, overriding the
default prefix-based naming. This is useful when an external tool (e.g. an orchestrator)
has already created the database.
With --stealth: configures per-repository git settings for invisible beads usage:
• .git/info/exclude to prevent beads files from being committed
Perfect for personal use without affecting repo collaborators.
To set up a specific AI tool, run: bd setup &lt;claude|cursor|aider|...&gt; --stealth
By default, beads uses an embedded Dolt engine (no external server needed).
Pass --server to use an external dolt sql-server instead. In server mode,
set connection details with --server-host, --server-port, and --server-user.
Password should be set via BEADS_DOLT_PASSWORD environment variable.
Auto-export is optional. When enabled, bd exports issues to
.beads/issues.jsonl after write commands (throttled to once per 60s). This is
for viewers (bv), interchange, and issue-level migration; not backup.
Cross-machine sync and backups use Dolt remotes/backups, not JSONL import/export.
To enable: bd config set export.auto true
Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
Skips all interactive prompts, using sensible defaults:
• Role defaults to "maintainer" (override with --role)
• Fork exclude auto-configured when fork detected
• Auto-export left at default (disabled)
• --contributor and --team flags are rejected (wizards require interaction)
Also auto-detected when stdin is not a terminal or CI=true is set.
```
bd init [flags]
```
**Flags:**
```
--agents-file string Custom filename for agent instructions (default: AGENTS.md)
--agents-profile string AGENTS.md profile: 'minimal' (default, pointer to bd prime) or 'full' (complete command reference)
--agents-template string Path to custom AGENTS.md template (overrides embedded default)
--backend string Storage backend: dolt (default), postgres, mysql, or sqlite. See docs/STORAGE-BACKENDS.md.
--contributor Run OSS contributor setup wizard
--database string Use existing server database name (overrides prefix-based naming)
--debug Run the managed Dolt sql-server with --loglevel=debug and CPU profiling (--prof cpu). Persisted to config.yaml as dolt.debug. No effect on externally-managed servers.
--destroy-token string Explicit confirmation token for destructive re-init in non-interactive mode (format: 'DESTROY-<prefix>')
--discard-remote Authorize discarding the configured remote's Dolt history when re-initializing. Requires --destroy-token in non-interactive mode; see 'bd help init-safety'.
--external Server is externally managed (skip server startup); use with --shared-server or --server
--force Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence (see 'bd help init-safety').
--from-jsonl Import issues from configured import.path; refuses remote history unless --discard-remote authorizes replacement
--init-if-missing If the workspace is already initialized, skip init and exit 0 instead of failing (idempotent init for scaffolds)
--mysql-database string MySQL database for this workspace (with --backend=mysql; MySQL's isolation unit)
--mysql-url string MySQL server DSN (with --backend=mysql), e.g. user:pass@tcp(host:3306)/ . A password may be included for init but is never persisted; set BEADS_MYSQL_PASSWORD for later commands. Falls back to BEADS_MYSQL_URL.
--non-interactive Skip all interactive prompts (auto-detected in CI or non-TTY environments)
--pg-schema string Postgres schema for this workspace's tables (with --backend=postgres; provides search_path isolation)
--pg-url string Postgres connection URL (with --backend=postgres). A password may be included for init but is never persisted; set BEADS_PG_PASSWORD for later commands. Falls back to BEADS_POSTGRES_URL.
-p, --prefix string Issue prefix (default: current directory name)
--proxied-server [EXPERIMENTAL] Use a per-workspace proxied dolt sql-server (proxy + child dolt) rooted at .beads/proxieddb
--proxied-server-config-path string [EXPERIMENTAL] Absolute path to an existing dolt sql-server YAML config (proxied-server mode only). When set, bd uses this file instead of auto-generating one. Relative paths are rejected.
--proxied-server-external-host string [EXPERIMENTAL] Hostname or IP of an externally-managed dolt sql-server the proxy should front (proxied-server mode only). Mutually exclusive with --proxied-server-external-socket-path.
--proxied-server-external-keep-alive duration [EXPERIMENTAL] TCP keepalive period for the proxy→external connection. Zero uses the package default (30s).
--proxied-server-external-port int [EXPERIMENTAL] TCP port of the externally-managed dolt sql-server (proxied-server mode only). Required when --proxied-server-external-host is set.
--proxied-server-external-socket-path string [EXPERIMENTAL] Absolute unix socket path of the externally-managed dolt sql-server (proxied-server mode only). Mutually exclusive with --proxied-server-external-host. Relative paths are rejected.
--proxied-server-external-tls [EXPERIMENTAL] Require TLS when connecting to the externally-managed dolt sql-server (proxied-server mode only).
--proxied-server-external-tls-cert-path string [EXPERIMENTAL] Absolute path to a client TLS certificate (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-key-path. Relative paths are rejected.
--proxied-server-external-tls-key-path string [EXPERIMENTAL] Absolute path to the client TLS private key (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-cert-path. Relative paths are rejected.
--proxied-server-external-user string [EXPERIMENTAL] MySQL user for the externally-managed dolt sql-server (proxied-server mode only). Defaults to "root" when empty. Password is read at runtime from $BEADS_PROXIED_SERVER_EXTERNAL_PASSWORD and is never persisted to disk.
--proxied-server-idle-timeout duration [EXPERIMENTAL] Idle duration after which the proxy shuts down its loopback listener and backend (proxied-server mode only). Omit for the built-in default (30s); 0 keeps the proxy and backend alive indefinitely; a positive value sets the window.
--proxied-server-log-path string [EXPERIMENTAL] Absolute path to the proxied dolt sql-server log file (proxied-server mode only). Default: <beadsDir>/proxieddb/server.log. Relative paths are rejected.
--proxied-server-port int [EXPERIMENTAL] Fixed TCP port for the proxy's loopback listener (proxied-server mode only). Default 0 = an OS-assigned free port. Startup fails if the port is already in use.
--proxied-server-root-path string [EXPERIMENTAL] Absolute directory holding the proxied dolt sql-server's lockfiles, pidfiles, and child .dolt repository (proxied-server mode only). Default: <beadsDir>/proxieddb. May not exist yet — bd will create it. Relative paths are rejected.
-q, --quiet Suppress output (quiet mode)
--reinit-local Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence; see --discard-remote.
--remote string Dolt remote URL to clone from and persist as sync.remote
--role string Set beads role without prompting: "maintainer" or "contributor"
--server Use external dolt sql-server instead of embedded engine
--server-host string Dolt server host (default: 127.0.0.1)
--server-port int Dolt server port (default: 3307)
--server-socket string Unix domain socket path (overrides host/port)
--server-user string Dolt server MySQL user (default: root)
--setup-exclude Configure .git/info/exclude to keep beads files local (for forks)
--shared-server Enable shared Dolt server mode (all projects share one server at ~/.beads/shared-server/)
--skip-agents Skip AGENTS.md and Claude/Codex/Cursor setup generation
--skip-hooks Skip git hooks installation
--sqlite-path string SQLite database file (with --backend=sqlite; relative to the beads dir, default beads.db)
--stealth Enable stealth mode: global gitattributes and gitignore, no local repo tracking
--team Run team workflow setup wizard
```

View file

@ -1,123 +0,0 @@
---
id: jira
title: bd jira
slug: /cli-reference/jira
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc jira`
## bd jira
Synchronize issues between beads and Jira.
Configuration:
bd config set jira.url "https://company.atlassian.net"
bd config set jira.project "PROJ"
bd config set jira.projects "PROJ1,PROJ2" # Multiple projects
bd config set jira.api_token "YOUR_TOKEN"
bd config set jira.username "your_email@company.com" # For Jira Cloud
bd config set jira.push_prefix "hippo" # Only push hippo-* issues to Jira
bd config set jira.push_prefix "proj1,proj2" # Multiple prefixes (comma-separated)
Environment variables (alternative to config):
JIRA_API_TOKEN - Jira API token
JIRA_USERNAME - Jira username/email
JIRA_PROJECTS - Comma-separated project keys
Examples:
bd jira sync --pull # Import issues from Jira
bd jira sync --push # Export issues to Jira
bd jira sync # Bidirectional sync (pull then push)
bd jira sync --dry-run # Preview sync without changes
bd jira status # Show sync status
```
bd jira [flags]
```
### bd jira pull
Pull one or more items from Jira.
Accepts bead IDs or external references as positional arguments.
Equivalent to: bd jira sync --pull --issues &lt;refs&gt;
```
bd jira pull [refs...] [flags]
```
**Flags:**
```
--dry-run Preview pull without making changes
```
### bd jira push
Push one or more beads issues to Jira.
Accepts bead IDs as positional arguments.
Equivalent to: bd jira sync --push --issues &lt;ids&gt;
```
bd jira push [bead-ids...] [flags]
```
**Flags:**
```
--dry-run Preview push without making changes
```
### bd jira status
Show the current Jira sync status, including:
- Last sync timestamp
- Configuration status
- Number of issues with Jira links
- Issues pending push (no external_ref)
```
bd jira status [flags]
```
### bd jira sync
Synchronize issues between beads and Jira.
Modes:
--pull Import issues from Jira into beads
--push Export issues from beads to Jira
(no flags) Bidirectional sync: pull then push, with conflict resolution
Conflict Resolution:
By default, newer timestamp wins. Override with:
--prefer-local Always prefer local beads version
--prefer-jira Always prefer Jira version
Examples:
bd jira sync --pull # Import from Jira
bd jira sync --push --create-only # Push new issues only
bd jira sync --dry-run # Preview without changes
bd jira sync --prefer-local # Bidirectional, local wins
```
bd jira sync [flags]
```
**Flags:**
```
--create-only Only create new issues, don't update existing
--dry-run Preview sync without making changes
--issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
--parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues.
--prefer-jira Prefer Jira version on conflicts
--prefer-local Prefer local version on conflicts
--project strings Project key(s) to sync (overrides configured project/projects)
--pull Pull issues from Jira
--push Push issues to Jira
--state string Issue state to sync: open, closed, all (default "all")
```

View file

@ -1,78 +0,0 @@
---
id: kv
title: bd kv
slug: /cli-reference/kv
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc kv`
## bd kv
Commands for working with the beads key-value store.
The key-value store is useful for storing flags, environment variables,
or other user-defined data that persists across sessions.
Examples:
bd kv set mykey myvalue # Set a value
bd kv get mykey # Get a value
bd kv clear mykey # Delete a key
bd kv list # List all key-value pairs
```
bd kv [flags]
```
### bd kv clear
Delete a key from the beads key-value store.
Examples:
bd kv clear feature_flag
bd kv clear api_endpoint
```
bd kv clear <key> [flags]
```
### bd kv get
Get a value from the beads key-value store.
Examples:
bd kv get feature_flag
bd kv get api_endpoint
```
bd kv get <key> [flags]
```
### bd kv list
List all key-value pairs in the beads key-value store.
Examples:
bd kv list
bd kv list --json
```
bd kv list [flags]
```
### bd kv set
Set a key-value pair in the beads key-value store.
This is useful for storing flags, environment variables, or other
user-defined data that persists across sessions.
Examples:
bd kv set feature_flag true
bd kv set api_endpoint https://api.example.com
bd kv set max_retries 3
```
bd kv set <key> <value> [flags]
```

View file

@ -1,57 +0,0 @@
---
id: label
title: bd label
slug: /cli-reference/label
sidebar_position: 110
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc label`
## bd label
Manage issue labels
```
bd label [flags]
```
### bd label add
Add labels to issues. Issue IDs come first; the final argument is the label. Pass multiple labels comma-separated: bd label add bd-123 label1,label2
```
bd label add [issue-id...] [label[,label...]] [flags]
```
### bd label list
List labels for an issue
```
bd label list [issue-id] [flags]
```
### bd label list-all
List all unique labels in the database
```
bd label list-all [flags]
```
### bd label propagate
Push a label from a parent down to all direct children that don't already have it. Useful for applying branch: labels across an epic's subtasks.
```
bd label propagate [parent-id] [label] [flags]
```
### bd label remove
Remove labels from issues. Issue IDs come first; the final argument is the label. Pass multiple labels comma-separated: bd label remove bd-123 label1,label2
```
bd label remove [issue-id...] [label[,label...]] [flags]
```

View file

@ -1,226 +0,0 @@
---
id: linear
title: bd linear
slug: /cli-reference/linear
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc linear`
## bd linear
Synchronize issues between beads and Linear.
Configuration:
bd config set linear.api_key "YOUR_API_KEY"
bd config set linear.team_id "TEAM_ID"
bd config set linear.team_ids "TEAM_ID1,TEAM_ID2" # Multiple teams (comma-separated)
bd config set linear.project_id "PROJECT_ID" # Optional: sync only this project
Environment variables (alternative to config):
LINEAR_API_KEY - Linear API key (for individual developers)
LINEAR_TEAM_ID - Linear team ID (UUID, singular)
LINEAR_TEAM_IDS - Linear team IDs (comma-separated UUIDs)
OAuth (for CI workers / automated sync):
LINEAR_OAUTH_CLIENT_ID - OAuth app client ID
LINEAR_OAUTH_CLIENT_SECRET - OAuth app client secret
When both OAuth env vars are set, OAuth client_credentials flow is used
instead of the API key. This allows CI workers to authenticate as an
application (actor=application) rather than impersonating a user.
Precedence: OAuth &gt; LINEAR_API_KEY &gt; config file.
Data Mapping (optional, sensible defaults provided):
Priority mapping (Linear 0-4 to Beads 0-4):
bd config set linear.priority_map.0 4 # No priority -&gt; Backlog
bd config set linear.priority_map.1 0 # Urgent -&gt; Critical
bd config set linear.priority_map.2 1 # High -&gt; High
bd config set linear.priority_map.3 2 # Medium -&gt; Medium
bd config set linear.priority_map.4 3 # Low -&gt; Low
State mapping (Linear state type to Beads status):
bd config set linear.state_map.backlog open
bd config set linear.state_map.unstarted open
bd config set linear.state_map.started in_progress
bd config set linear.state_map.completed closed
bd config set linear.state_map.canceled closed
bd config set linear.state_map.my_custom_state in_progress # Custom state names
Label to issue type mapping:
bd config set linear.label_type_map.bug bug
bd config set linear.label_type_map.feature feature
bd config set linear.label_type_map.epic epic
Relation type mapping (Linear relations to Beads dependencies):
bd config set linear.relation_map.blocks blocks
bd config set linear.relation_map.blockedBy blocks
bd config set linear.relation_map.duplicate duplicates
bd config set linear.relation_map.related related
ID generation (optional, hash IDs to match bd/Jira hash mode):
bd config set linear.id_mode "hash" # hash (default)
bd config set linear.hash_length "6" # hash length 3-8 (default: 6)
Examples:
bd linear sync --pull # Import issues from Linear
bd linear sync --push # Export issues to Linear
bd linear sync # Bidirectional sync (pull then push)
bd linear sync --dry-run # Preview sync without changes
bd create "Fix login" --external-ref https://linear.app/team/issue/TEAM-123
# Link a local issue to an existing Linear issue
bd linear status # Show sync status
```
bd linear [flags]
```
### bd linear pull
Pull one or more items from Linear.
Accepts bead IDs or external references as positional arguments.
Equivalent to: bd linear sync --pull --issues &lt;refs&gt;
```
bd linear pull [refs...] [flags]
```
**Flags:**
```
--dry-run Preview pull without making changes
--relations Import Linear relations as bd dependencies when pulling
```
### bd linear push
Push one or more beads issues to Linear.
Accepts bead IDs as positional arguments.
Equivalent to: bd linear sync --push --issues &lt;ids&gt;
```
bd linear push [bead-ids...] [flags]
```
**Flags:**
```
--dry-run Preview push without making changes
```
### bd linear status
Show the current Linear sync status, including:
- Last sync timestamp
- Configuration status
- Number of issues with Linear links
- Issues pending push (no external_ref)
```
bd linear status [flags]
```
### bd linear sync
Synchronize issues between beads and Linear.
Modes:
--pull Import issues from Linear into beads
--push Export issues from beads to Linear
--pull-if-stale Pull only if data is stale (skip if fresh)
(no flags) Bidirectional sync: pull then push, with conflict resolution
Staleness (--pull-if-stale):
--threshold 20m How old data must be before pulling (default 20m)
A 5-minute debounce prevents agent loops: if a pull completed within 5 minutes,
data is always treated as fresh regardless of the threshold.
Team Selection:
--team ID1,ID2 Override configured team IDs for this sync
Multiple teams can be configured via linear.team_ids (comma-separated).
Falls back to linear.team_id for backward compatibility.
Push requires explicit --team when multiple teams are configured.
Pull Options:
--milestones Reconstruct Linear project milestones as local epic parents
Type Filtering (--push only):
--type task,feature Only sync issues of these types
--exclude-type wisp Exclude issues of these types
--include-ephemeral Include ephemeral issues (wisps, etc.); default is to exclude
--parent TICKET Only push this ticket and its descendants
--relations Import Linear relations as bd dependencies on pull
Persistent push-direction ID filters (workflow artifacts, sandbox beads, etc.):
bd config set linear.exclude_id_prefix "hw-mol-"
bd config set linear.exclude_id_patterns "-wisp-,sandbox-,scratch-"
exclude_id_prefix is a single case-sensitive prefix on the bead ID.
exclude_id_patterns is a comma-separated list of case-sensitive substrings
(matched anywhere in the ID). Both are combined as a union: a bead
matching either rule is skipped from push (no create, no update). Beads
with an existing external_ref that NOW match are silently skipped on
future syncs; the Linear-side issue persists — archive/delete it manually
if desired.
Conflict Resolution:
By default, newer timestamp wins. Override with:
--prefer-local Always prefer local beads version
--prefer-linear Always prefer Linear version
Examples:
bd linear sync --pull # Import from Linear
bd linear sync --pull-if-stale # Pull only if data is stale
bd linear sync --pull-if-stale --threshold 5m # Pull if older than 5 minutes
bd linear sync --pull --relations # Import Linear blocking relations as bd deps
bd linear sync --push --create-only # Push new issues only
bd linear sync --push --type=task,feature # Push only tasks and features
bd linear sync --push --exclude-type=wisp # Push all except wisps
bd linear sync --push --parent=bd-abc123 # Push one ticket tree
bd linear sync --dry-run # Preview without changes
bd linear sync --prefer-local # Bidirectional, local wins
```
bd linear sync [flags]
```
**Flags:**
```
--create-only Only create new issues, don't update existing
--dry-run Preview sync without making changes
--exclude-type strings Exclude issues of these types (can be repeated)
--include-ephemeral Include ephemeral issues (wisps, etc.) when pushing to Linear
--issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
--milestones Reconstruct Linear project milestones as local epic parents when pulling
--no-wait Fail immediately if another sync is running instead of waiting
--parent string Limit push to this beads ticket and its descendants
--prefer-linear Prefer Linear version on conflicts
--prefer-local Prefer local version on conflicts
--pull Pull issues from Linear
--pull-if-stale Pull only if Linear data is stale (skip if fresh)
--push Push issues to Linear
--relations Import Linear relations as bd dependencies when pulling
--state string Issue state to sync: open, closed, all (default "all")
--team strings Team ID(s) to sync (overrides configured team_id/team_ids)
--threshold duration Staleness threshold for --pull-if-stale (default 20m) (default 20m0s)
--type strings Only sync issues of these types (can be repeated)
--update-refs Update external_ref after creating Linear issues (default true)
```
### bd linear teams
List all teams accessible with your Linear API key.
Use this to find the team ID (UUID) needed for configuration.
Example:
bd linear teams
bd config set linear.team_id "12345678-1234-1234-1234-123456789abc"
```
bd linear teams [flags]
```

View file

@ -1,31 +0,0 @@
---
id: link
title: bd link
slug: /cli-reference/link
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc link`
## bd link
Link two issues with a dependency.
Shorthand for 'bd dep add &lt;id1&gt; &lt;id2&gt;'. By default creates a "blocks"
dependency (id2 blocks id1). Use --type to specify a different relationship.
Examples:
bd link bd-123 bd-456 # bd-456 blocks bd-123
bd link bd-123 bd-456 --type related # bd-123 related to bd-456
bd link bd-123 bd-456 --type parent-child
```
bd link <id1> <id2> [flags]
```
**Flags:**
```
-t, --type string Dependency type (blocks|tracks|related|parent-child|discovered-from) (default "blocks")
```

View file

@ -1,41 +0,0 @@
---
id: lint
title: bd lint
slug: /cli-reference/lint
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc lint`
## bd lint
Check issues for missing recommended sections based on issue type.
By default, lints all open issues. Specify issue IDs to lint specific issues.
Section requirements by type:
bug: Steps to Reproduce, Acceptance Criteria
task: Acceptance Criteria
feature: Acceptance Criteria
epic: Success Criteria
chore: (none)
Examples:
bd lint # Lint all open issues
bd lint bd-abc # Lint specific issue
bd lint bd-abc bd-def # Lint multiple issues
bd lint --type bug # Lint only bugs
bd lint --status all # Lint all issues (including closed)
```
bd lint [issue-id...] [flags]
```
**Flags:**
```
-s, --status string Filter by status (default: open, use 'all' for all)
-t, --type string Filter by issue type (bug, task, feature, epic, decision, spike, story, chore, milestone)
```

View file

@ -1,80 +0,0 @@
---
id: list
title: bd list
slug: /cli-reference/list
sidebar_position: 20
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc list`
## bd list
List issues
```
bd list [flags]
```
**Flags:**
```
--all Show all issues including closed (overrides default filter)
-a, --assignee string Filter by assignee
--closed-after string Filter issues closed after date (YYYY-MM-DD or RFC3339)
--closed-before string Filter issues closed before date (YYYY-MM-DD or RFC3339)
--created-after string Filter issues created after date (YYYY-MM-DD or RFC3339)
--created-before string Filter issues created before date (YYYY-MM-DD or RFC3339)
--defer-after string Filter issues deferred after date (supports relative: +6h, tomorrow)
--defer-before string Filter issues deferred before date (supports relative: +6h, tomorrow)
--deferred Show only issues with defer_until set
--desc-contains string Filter by description substring (case-insensitive)
--due-after string Filter issues due after date (supports relative: +6h, tomorrow)
--due-before string Filter issues due before date (supports relative: +6h, tomorrow)
--empty-description Filter issues with empty or missing description
--exclude-label strings Exclude issues that have ANY of these labels
--exclude-type strings Exclude issue types from results (comma-separated or repeatable, e.g., --exclude-type=convoy,epic)
--flat Disable tree format and use legacy flat list output
--format string Output format: 'digraph' (for golang.org/x/tools/cmd/digraph), 'dot' (Graphviz), or Go template
--has-metadata-key string Filter issues that have this metadata key set
--id string Filter by specific issue IDs (comma-separated, e.g., bd-1,bd-5,bd-10)
--include-gates Include gate issues in output (normally hidden)
--include-infra Include infrastructure beads (agent/role/message) in output
--include-templates Include template molecules in output
-l, --label strings Filter by labels (AND: must have ALL). Can combine with --label-any
--label-any strings Filter by labels (OR: must have AT LEAST ONE). Can combine with --label
--label-pattern string Filter by label glob pattern (e.g., 'tech-*' matches tech-debt, tech-legacy)
--label-regex string Filter by label regex pattern (e.g., 'tech-(debt|legacy)')
-n, --limit int Limit results (default 50, use 0 for unlimited) (default 50)
--long Show detailed multi-line output for each issue
--metadata-field stringArray Filter by metadata field (key=value, repeatable)
--mol-type string Filter by molecule type: swarm, patrol, or work
--no-assignee Filter issues with no assignee
--no-labels Filter issues with no labels
--no-pager Disable pager output
--no-parent Exclude child issues (show only top-level issues)
--no-pinned Exclude pinned issues
--notes-contains string Filter by notes substring (case-insensitive)
--offset int Skip the first N matching results (0-based). Only supported under --proxied-server.
--overdue Show only issues with due_at in the past (not closed)
--parent string Filter by parent issue ID (shows children of specified issue)
--pinned Show only pinned issues
--pretty Display issues in a tree format with status/priority symbols
-p, --priority string Priority (0-4 or P0-P4, 0=highest)
--priority-max string Filter by maximum priority (inclusive, 0-4 or P0-P4)
--priority-min string Filter by minimum priority (inclusive, 0-4 or P0-P4)
--ready Show only ready issues (no active blockers, same semantics as bd ready)
-r, --reverse Reverse sort order
--skip-labels Skip label hydration. The labels field in output will be empty regardless of actual labels. Use only when the caller does not depend on label data. Cannot combine with --label, --label-any, --label-pattern, --label-regex, --exclude-label, or --no-labels.
--sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee
--spec string Filter by spec_id prefix
-s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress. Note: repeating -s/--status silently overwrites the previous value — always use the comma-separated form for multi-status filters.
--title string Filter by title text (case-insensitive substring match)
--title-contains string Filter by title substring (case-insensitive)
--tree Hierarchical tree format (default: true; use --flat to disable) (default true)
-t, --type string Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate, convoy). Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision
--updated-after string Filter issues updated after date (YYYY-MM-DD or RFC3339)
--updated-before string Filter issues updated before date (YYYY-MM-DD or RFC3339)
-w, --watch Watch for changes and auto-update display (implies --pretty)
--wisp-type string Filter by wisp type: heartbeat, ping, patrol, gc_report, recovery, error, escalation
```

View file

@ -1,36 +0,0 @@
---
id: mail
title: bd mail
slug: /cli-reference/mail
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc mail`
## bd mail
Delegates mail operations to an external mail provider.
Agents often type 'bd mail' when working with beads, but mail functionality
is typically provided by the orchestrator. This command bridges that gap
by delegating to the configured mail provider.
Configuration (checked in order):
1. BEADS_MAIL_DELEGATE or BD_MAIL_DELEGATE environment variable
2. 'mail.delegate' config setting (bd config set mail.delegate "gt mail")
Examples:
# Configure delegation (one-time setup)
export BEADS_MAIL_DELEGATE="gt mail"
# or
bd config set mail.delegate "gt mail"
# Then use bd mail as if it were gt mail
bd mail inbox # Lists inbox
bd mail send mayor/ -s "Hi" # Sends mail
bd mail read msg-123 # Reads a message
```
bd mail [subcommand] [args...] [flags]
```

View file

@ -1,22 +0,0 @@
---
id: memories
title: bd memories
slug: /cli-reference/memories
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc memories`
## bd memories
List all memories, or search by keyword.
Examples:
bd memories # list all memories
bd memories dolt # search for memories about dolt
bd memories "race flag" # search for a phrase
```
bd memories [search] [flags]
```

View file

@ -1,99 +0,0 @@
---
id: merge-slot
title: bd merge-slot
slug: /cli-reference/merge-slot
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc merge-slot`
## bd merge-slot
Merge-slot gates serialize conflict resolution in the merge queue.
A merge slot is an exclusive access primitive: only one agent can hold it at a time.
This prevents "monkey knife fights" where multiple polecats race to resolve conflicts
and create cascading conflicts.
Each rig has one merge slot bead: &lt;prefix&gt;-merge-slot (labeled gt:slot).
The slot uses:
- status=open: slot is available
- status=in_progress: slot is held
- metadata.holder: who currently holds the slot
- metadata.waiters: priority-ordered queue of waiters
Examples:
bd merge-slot create # Create merge slot for current rig
bd merge-slot check # Check if slot is available
bd merge-slot acquire # Try to acquire the slot
bd merge-slot release # Release the slot
```
bd merge-slot [flags]
```
### bd merge-slot acquire
Attempt to acquire the merge slot for exclusive access.
If the slot is available (status=open), it will be acquired:
- status set to in_progress
- holder set to the requester
If the slot is held (status=in_progress), the command fails unless
--wait is passed, which adds the requester to the waiters queue.
Use --holder to specify who is acquiring (default: BEADS_ACTOR env var).
```
bd merge-slot acquire [flags]
```
**Flags:**
```
--holder string Who is acquiring the slot (default: BEADS_ACTOR)
--wait Add to waiters list if slot is held
```
### bd merge-slot check
Check if the merge slot is available or held.
Returns:
- available: slot can be acquired
- held by &lt;holder&gt;: slot is currently held
- not found: no merge slot exists for this rig
```
bd merge-slot check [flags]
```
### bd merge-slot create
Create a merge slot bead for serialized conflict resolution.
The slot ID is automatically generated based on the beads prefix (e.g., gt-merge-slot).
The slot is created with status=open (available).
```
bd merge-slot create [flags]
```
### bd merge-slot release
Release the merge slot after conflict resolution is complete.
Sets status back to open and clears the holder field.
If there are waiters, the highest-priority waiter should then acquire.
```
bd merge-slot release [flags]
```
**Flags:**
```
--holder string Who is releasing the slot (for verification)
```

View file

@ -1,52 +0,0 @@
---
id: metrics
title: bd metrics
slug: /cli-reference/metrics
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc metrics`
## bd metrics
Show whether anonymous usage metrics are on, see exactly what is sent, and
turn them on or off.
bd shares anonymous usage metrics to learn how people actually use it — just
which commands get run, plus the bd version and OS platform. That's how we decide
what to polish next. We never collect your issues, paths, remotes, identity, or
any user-supplied text.
bd metrics show the current status and what is collected
bd metrics on turn metrics on
bd metrics off turn metrics off
bd metrics example show real examples of the events bd sends
```
bd metrics [flags]
```
### bd metrics example
Show real examples of the anonymous metrics bd sends
```
bd metrics example [flags]
```
### bd metrics off
Turn anonymous usage metrics off
```
bd metrics off [flags]
```
### bd metrics on
Turn anonymous usage metrics on
```
bd metrics on [flags]
```

View file

@ -1,36 +0,0 @@
---
id: migrate-personal
title: bd migrate-personal
slug: /cli-reference/migrate-personal
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc migrate-personal`
## bd migrate-personal
Identify issues you created in the project database and move them to your
personal planning repository (~/.beads-planning by default).
This is a one-time migration for contributors who created personal planning
issues before contributor routing was configured.
The command:
1. Finds all issues in the project database created by your git identity
2. Shows you the list and asks for confirmation
3. Moves them to the planning repo configured in routing.contributor
EXAMPLES:
bd migrate-personal # Interactive: show list and prompt
bd migrate-personal -y # Non-interactive: skip confirmation
```
bd migrate-personal [flags]
```
**Flags:**
```
-y, --yes Skip confirmation prompt
```

View file

@ -1,159 +0,0 @@
---
id: migrate
title: bd migrate
slug: /cli-reference/migrate
sidebar_position: 620
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc migrate`
## bd migrate
Database migration and data transformation commands.
Without subcommand, checks and updates database metadata to current version.
Subcommands:
hooks Plan git hook migration to marker-managed format
issues Move issues between repositories
schema Apply pending schema migrations (idempotent)
sync Set up sync.branch workflow for multi-clone setups
On a remote-backed database with pending schema migrations bd refuses to
migrate in place (#4259): migrating two clones independently forks the schema
so bd dolt pull can no longer merge — the break is silent and unrecoverable.
Use --force to confirm you are the single designated migrator, after which you
should publish the migrated schema with 'bd dolt push'. The env-var equivalent
BD_ALLOW_REMOTE_MIGRATE=1 remains supported for scripted/CI use.
```
bd migrate [flags]
```
**Flags:**
```
--dry-run Show what would be done without making changes
--force Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1)
--inspect Show migration plan and database state for AI agent analysis
--json Output migration statistics in JSON format
--update-repo-id Update repository ID (use after changing git remote)
--yes Auto-confirm prompts
```
### bd migrate hooks
Analyze git hook files and sidecar artifacts for migration to marker-managed format.
Modes:
--dry-run Preview migration operations without changing files
--apply Apply migration operations
Examples:
bd migrate hooks --dry-run
bd migrate hooks --apply
bd migrate hooks --apply --yes
bd migrate hooks --dry-run --json
```
bd migrate hooks [path] [flags]
```
**Flags:**
```
--apply Apply planned hook migration changes
--dry-run Show what would be done without making changes
--json Output in JSON format
--yes Skip confirmation prompt for --apply
```
### bd migrate issues
Move issues from one source repository to another with filtering and dependency preservation.
This command updates the source_repo field for selected issues, allowing you to:
- Move contributor planning issues to upstream repository
- Reorganize issues across multi-phase repositories
- Consolidate issues from multiple repos
Examples:
# Preview migration from planning repo to current repo
bd migrate-issues --from ~/.beads-planning --to . --dry-run
# Move all open P1 bugs
bd migrate-issues --from ~/repo1 --to ~/repo2 --priority 1 --type bug --status open
# Move specific issues with their dependencies
bd migrate-issues --from . --to ~/archive --id bd-abc --id bd-xyz --include closure
# Move issues with label filter
bd migrate-issues --from . --to ~/feature-work --label frontend --label urgent
```
bd migrate issues [flags]
```
**Flags:**
```
--dry-run Show plan without making changes
--from string Source repository (required)
--id strings Specific issue IDs to migrate (can specify multiple)
--ids-file string File containing issue IDs (one per line)
--include string Include dependencies: none/upstream/downstream/closure (default "none")
--label strings Filter by labels (can specify multiple)
--priority int Filter by priority (0-4) (default -1)
--status string Filter by status (open/closed/all)
--strict Fail on orphaned dependencies or missing repos
--to string Destination repository (required)
--type string Filter by issue type (bug/feature/task/epic/chore/decision)
--within-from-only Only include dependencies from source repo (default true)
--yes Skip confirmation prompt
```
### bd migrate schema
Apply pending schema migrations idempotently.
Schema migrations also run automatically on store open, so this subcommand
is typically a no-op. It exists to make migration explicit and observable
in CI, release gates, and recovery scenarios.
Example:
bd migrate schema
bd migrate schema --json
```
bd migrate schema [flags]
```
**Flags:**
```
--force Bypass the remote-migrate gate as the single designated migrator (equivalent to BD_ALLOW_REMOTE_MIGRATE=1)
--json Output in JSON format
```
### bd migrate sync
Configure separate branch workflow for multi-clone setups.
This sets the sync.branch config value so that issue data is committed
to a dedicated branch, keeping your main branch clean.
Example:
bd migrate sync beads-sync
```
bd migrate sync <branch> [flags]
```
**Flags:**
```
--dry-run Show what would be done without making changes
--json Output in JSON format
```

View file

@ -1,619 +0,0 @@
---
id: mol
title: bd mol
slug: /cli-reference/mol
sidebar_position: 300
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc mol`
## bd mol
Manage molecules - work templates for agent workflows.
Protos are template epics with the "template" label. They define a DAG of work
that can be spawned to create real issues (molecules).
The molecule metaphor:
- A proto is an uninstantiated template (reusable work pattern)
- Spawning creates a molecule (real issues) from the proto
- Variables (&#123;&#123;key&#125;&#125;) are substituted during spawning
- Bonding combines protos or molecules into compounds
- Distilling extracts a proto from an ad-hoc epic
Commands:
show Show proto/molecule structure and variables
pour Instantiate proto as persistent mol (liquid phase)
wisp Instantiate proto as ephemeral wisp (vapor phase)
bond Polymorphic combine: proto+proto, proto+mol, mol+mol
squash Condense molecule to digest
burn Discard wisp
distill Extract proto from ad-hoc epic
Use "bd formula list" to list available formulas.
```
bd mol [flags]
```
**Aliases:** protomolecule
### bd mol bond
Bond two protos or molecules to create a compound.
The bond command is polymorphic - it handles different operand types:
formula + formula → cook both, compound proto
formula + proto → cook formula, compound proto
formula + mol → cook formula, spawn and attach
proto + proto → compound proto (reusable template)
proto + mol → spawn proto, attach to molecule
mol + proto → spawn proto, attach to molecule
mol + mol → join into compound molecule
Formula names (e.g., mol-polecat-arm) are cooked inline as ephemeral protos.
This avoids needing pre-cooked proto beads in the database.
Bond types:
sequential (default) - B runs after A completes
parallel - B runs alongside A
conditional - B runs only if A fails
Phase control:
By default, spawned protos follow the target's phase:
- Attaching to mol (Ephemeral=false) → spawns as persistent (Ephemeral=false)
- Attaching to ephemeral issue (Ephemeral=true) → spawns as ephemeral (Ephemeral=true)
Override with:
--pour Force spawn as liquid (persistent, Ephemeral=false)
--ephemeral Force spawn as vapor (ephemeral, Ephemeral=true, excluded from Dolt sync via dolt_ignore)
Dynamic bonding (Christmas Ornament pattern):
Use --ref to specify a custom child reference with variable substitution.
This creates IDs like "parent.child-ref" instead of random hashes.
Example:
bd mol bond mol-worker-arm bd-patrol --ref arm-&#123;&#123;worker_name&#125;&#125; --var worker_name=ace
# Creates: bd-patrol.arm-ace (and children like bd-patrol.arm-ace.capture)
Use cases:
- Found important bug during patrol? Use --pour to persist it
- Need ephemeral diagnostic on persistent feature? Use --ephemeral
- Spawning per-worker arms on a patrol? Use --ref for readable IDs
Examples:
bd mol bond mol-feature mol-deploy # Compound proto
bd mol bond mol-feature mol-deploy --type parallel # Run in parallel
bd mol bond mol-feature bd-abc123 # Attach proto to molecule
bd mol bond bd-abc123 bd-def456 # Join two molecules
bd mol bond mol-critical-bug wisp-patrol --pour # Persist found bug
bd mol bond mol-temp-check bd-feature --ephemeral # Ephemeral diagnostic
bd mol bond mol-arm bd-patrol --ref arm-&#123;&#123;name&#125;&#125; --var name=ace # Dynamic child ID
```
bd mol bond <A> <B> [flags]
```
**Aliases:** fart
**Flags:**
```
--as string Custom title for compound proto (proto+proto only)
--dry-run Preview what would be created
--ephemeral Force spawn as vapor (ephemeral, Ephemeral=true)
--pour Force spawn as liquid (persistent, Ephemeral=false)
--ref string Custom child reference with {{var}} substitution (e.g., arm-{{polecat_name}})
--type string Bond type: sequential, parallel, or conditional (default "sequential")
--var stringArray Variable substitution for spawned protos (key=value)
```
### bd mol burn
Burn a molecule, deleting it without creating a digest.
Unlike squash (which creates a permanent digest before deletion), burn
completely removes the molecule with no trace. Use this for:
- Abandoned patrol cycles
- Crashed or failed workflows
- Test/debug molecules you don't want to preserve
The burn operation differs based on molecule phase:
- Wisp (ephemeral): Direct delete
- Mol (persistent): Cascade delete (syncs to remotes)
CAUTION: This is a destructive operation. The molecule's data will be
permanently lost. If you want to preserve a summary, use 'bd mol squash'.
Example:
bd mol burn bd-abc123 # Delete molecule with no trace
bd mol burn bd-abc123 --dry-run # Preview what would be deleted
bd mol burn bd-abc123 --force # Skip confirmation
bd mol burn bd-a1 bd-b2 bd-c3 # Batch delete multiple wisps
```
bd mol burn <molecule-id> [molecule-id...] [flags]
```
**Flags:**
```
--dry-run Preview what would be deleted
--force Skip confirmation prompt
```
### bd mol current
Show where you are in a molecule workflow.
If molecule-id is given, show status for that molecule.
If not given, infer from in_progress issues assigned to current agent.
The output shows all steps with status indicators:
[done] - Step is complete (closed)
[current] - Step is in_progress (you are here)
[ready] - Step is ready to start (unblocked)
[blocked] - Step is blocked by dependencies
[pending] - Step is waiting
For large molecules (&gt;100 steps), a summary is shown instead.
Use --limit or --range to view specific steps:
bd mol current &lt;id&gt; --limit 50 # Show first 50 steps
bd mol current &lt;id&gt; --range 100-150 # Show steps 100-150
```
bd mol current [molecule-id] [flags]
```
**Flags:**
```
--for string Show molecules for a specific agent/assignee
--limit int Maximum number of steps to display (0 = auto, use 'all' threshold)
--range string Display specific step range (e.g., '1-50', '100-150')
```
### bd mol distill
Distill a molecule by extracting a reusable formula from an existing epic.
This is the reverse of pour: instead of formula → molecule, it's molecule → formula.
The distill command:
1. Loads the existing epic and all its children
2. Converts the structure to a .formula.json file
3. Replaces concrete values with &#123;&#123;variable&#125;&#125; placeholders (via --var flags)
Use cases:
- Team develops good workflow organically, wants to reuse it
- Capture tribal knowledge as executable templates
- Create starting point for similar future work
Variable syntax (both work - we detect which side is the concrete value):
--var branch=feature-auth Spawn-style: variable=value (recommended)
--var feature-auth=branch Substitution-style: value=variable
Output locations (first writable wins):
1. &lt;resolved-beads-dir&gt;/formulas/ (project-level, default)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user-level, if project not writable)
Examples:
bd mol distill bd-o5xe my-workflow
bd mol distill bd-abc release-workflow --var feature_name=auth-refactor
```
bd mol distill <epic-id> [formula-name] [flags]
```
**Flags:**
```
--dry-run Preview what would be created
--output string Output directory for formula file
--var stringArray Replace value with {{variable}} placeholder (variable=value)
```
### bd mol last-activity
Show the most recent activity timestamp for a molecule.
Returns the timestamp of the most recent change to any step in the molecule,
making it easy to detect stale or stuck molecules.
Activity sources:
step_closed - A step was closed
step_updated - A step was updated (claimed, edited, etc.)
molecule_updated - The molecule root itself was updated
Examples:
bd mol last-activity hq-wisp-0laki
bd mol last-activity hq-wisp-0laki --json
```
bd mol last-activity <molecule-id> [flags]
```
### bd mol pour
Pour a proto into a persistent mol - like pouring molten metal into a mold.
This is the chemistry-inspired command for creating PERSISTENT work from templates.
The resulting mol lives in .beads/ (permanent storage) and is synced with git.
Phase transition: Proto (solid) -&gt; pour -&gt; Mol (liquid)
WHEN TO USE POUR vs WISP:
pour (liquid): Persistent work that needs audit trail
- Feature implementations spanning multiple sessions
- Work you may need to reference later
- Anything worth preserving in git history
wisp (vapor): Ephemeral work that auto-cleans up
- Release workflows (one-time execution)
- Operational loops and recurring cycles
- Health checks and diagnostics
- Any operational workflow without audit value
TIP: Formulas can specify phase:"vapor" to recommend wisp usage.
If you pour a vapor-phase formula, you'll get a warning.
Examples:
bd mol pour mol-feature --var name=auth # Persistent feature work
bd mol pour mol-review --var pr=123 # Persistent code review
```
bd mol pour <proto-id> [flags]
```
**Flags:**
```
--assignee string Assign the root issue to this agent/user
--attach strings Proto to attach after spawning (repeatable)
--attach-type string Bond type for attachments: sequential, parallel, or conditional (default "sequential")
--dry-run Preview what would be created
--var stringArray Variable substitution (key=value)
```
### bd mol progress
Show efficient progress summary for a molecule.
This command uses indexed queries to count progress without loading all steps,
making it suitable for very large molecules (millions of steps).
If no molecule-id is given, shows progress for any molecule you're working on.
Output includes:
- Progress: completed / total (percentage)
- Current step: the in-progress step (if any)
- Rate: steps/hour based on closure times
- ETA: estimated time to completion
Example:
bd mol progress bd-hanoi-xyz
```
bd mol progress [molecule-id] [flags]
```
### bd mol ready
Find molecules where a gate has closed and the workflow is ready to resume.
This command discovers molecules waiting at a gate step where:
1. The molecule has a gate bead that blocks a step
2. The gate bead is now closed (condition satisfied)
3. The blocked step is now ready to proceed
4. No agent currently has this molecule hooked
This enables discovery-based resume without explicit waiter tracking.
The patrol system uses this to find and dispatch gate-ready molecules.
Examples:
bd mol ready --gated # Find all gate-ready molecules
bd mol ready --gated --json # JSON output for automation
```
bd mol ready --gated [flags]
```
**Flags:**
```
--gated Find molecules ready for gate-resume dispatch (always on for this subcommand)
```
### bd mol seed
Verify that a formula is accessible and can be cooked.
The seed command checks formula search paths to ensure a formula exists
and can be loaded. This is useful for verifying system health before
attempting to spawn work from a formula.
Formula search paths (checked in order):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user level)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Examples:
bd mol seed mol-feature # Verify specific formula
bd mol seed mol-review --var name=test # Verify with variable substitution
```
bd mol seed <formula-name> [flags]
```
**Flags:**
```
--var stringArray Variable substitution for condition filtering (key=value)
```
### bd mol show
Show molecule structure and details.
The --parallel flag highlights parallelizable steps:
- Steps with no blocking dependencies can run in parallel
- Shows which steps are ready to start now
- Identifies parallel groups (steps that can run concurrently)
Example:
bd mol show bd-patrol --parallel
```
bd mol show <molecule-id> [flags]
```
**Flags:**
```
-p, --parallel Show parallel step analysis
```
### bd mol squash
Squash a molecule's ephemeral children into a single digest issue.
This command collects all ephemeral child issues of a molecule (Ephemeral=true),
generates a summary digest, and promotes the wisps to persistent by
clearing their Wisp flag (or optionally deletes them).
The squash operation:
1. Loads the molecule and all its children
2. Filters to only wisps (ephemeral issues with Ephemeral=true)
3. Generates a digest (summary of work done)
4. Creates a permanent digest issue (Ephemeral=false)
5. Clears Wisp flag on children (promotes to persistent)
OR keeps them with --keep-children (default: delete)
AGENT INTEGRATION:
Use --summary to provide an AI-generated summary. This keeps bd as a pure
tool - the calling agent (orchestrator worker, Claude Code, etc.) is responsible
for generating intelligent summaries. Without --summary, a basic concatenation
of child issue content is used.
This is part of the wisp workflow: spawn creates wisps,
execution happens, squash compresses the trace into an outcome (digest).
Example:
bd mol squash bd-abc123 # Squash and promote children
bd mol squash bd-abc123 --dry-run # Preview what would be squashed
bd mol squash bd-abc123 --keep-children # Keep wisps after digest
bd mol squash bd-abc123 --summary "Agent-generated summary of work done"
```
bd mol squash <molecule-id> [flags]
```
**Flags:**
```
--dry-run Preview what would be squashed
--keep-children Don't delete ephemeral children after squash
--summary string Agent-provided summary (bypasses auto-generation)
```
### bd mol stale
Detect molecules (epics with children) that are complete but still open.
A molecule is considered stale if:
1. All children are closed (Completed == Total)
2. Root issue is still open
3. Not assigned to anyone (optional, use --unassigned)
4. Is blocking other work (optional, use --blocking)
By default, shows all complete-but-unclosed molecules.
Examples:
bd mol stale # List all stale molecules
bd mol stale --json # Machine-readable output
bd mol stale --blocking # Only show those blocking other work
bd mol stale --unassigned # Only show unassigned molecules
bd mol stale --all # Include molecules with 0 children
```
bd mol stale [flags]
```
**Flags:**
```
--all Include molecules with 0 children
--blocking Only show molecules blocking other work
--unassigned Only show unassigned molecules
```
### bd mol wisp
Create or manage wisps - EPHEMERAL molecules for operational workflows.
When called with a proto-id argument, creates a wisp from that proto.
When called with a subcommand (list, gc), manages existing wisps.
Wisps are issues with Ephemeral=true in the main database. They're stored
locally but NOT synced via git.
WHEN TO USE WISP vs POUR:
wisp (vapor): Ephemeral work that auto-cleans up
- Release workflows (one-time execution)
- Operational loops and recurring cycles
- Health checks and diagnostics
- Any operational workflow without audit value
pour (liquid): Persistent work that needs audit trail
- Feature implementations spanning multiple sessions
- Work you may need to reference later
- Anything worth preserving in git history
TIP: Formulas can specify phase:"vapor" to recommend wisp usage.
If you use pour on a vapor-phase formula, you'll get a warning.
The wisp lifecycle:
1. Create: bd mol wisp &lt;proto&gt; or bd create --ephemeral
2. Execute: Normal bd operations work on wisp issues
3. Squash: bd mol squash &lt;id&gt; (clears Ephemeral flag, promotes to persistent)
4. Or burn: bd mol burn &lt;id&gt; (deletes without creating digest)
Examples:
bd mol wisp beads-release --var version=1.0 # Release workflow
bd mol wisp mol-my-workflow # Ephemeral operational cycle
bd mol wisp list # List all wisps
bd mol wisp gc # Garbage collect old wisps
Subcommands:
list List all wisps in current context
gc Garbage collect orphaned wisps
```
bd mol wisp [proto-id] [flags]
```
**Flags:**
```
--dry-run Preview what would be created
--root-only Create only the root issue (no child step issues)
--var stringArray Variable substitution (key=value)
```
#### bd mol wisp create
Create a wisp from a proto - sublimation from solid to vapor.
This is the chemistry-inspired command for creating ephemeral work from templates.
The resulting wisp is stored in the main database with Ephemeral=true and NOT synced via git.
Phase transition: Proto (solid) -&gt; Wisp (vapor)
Use wisp for:
- Operational loops and recurring cycles
- Health checks and monitoring
- One-shot orchestration runs
- Routine operations with no audit value
The wisp will:
- Be stored in main database with Ephemeral=true flag
- NOT be synced via git
- Either evaporate (burn) or condense to digest (squash)
Examples:
bd mol wisp create mol-patrol # Ephemeral patrol cycle
bd mol wisp create mol-health-check # One-time health check
bd mol wisp create mol-diagnostics --var target=db # Diagnostic run
```
bd mol wisp create <proto-id> [flags]
```
**Flags:**
```
--dry-run Preview what would be created
--root-only Create only the root issue (no child step issues)
--var stringArray Variable substitution (key=value)
```
#### bd mol wisp gc
Garbage collect old or abandoned wisps from the database.
A wisp is considered abandoned if:
- It hasn't been updated in --age duration and is not closed
Abandoned wisps are deleted without creating a digest. Use 'bd mol squash'
if you want to preserve a summary before garbage collection.
Use --closed to purge ALL closed wisps (regardless of age). This is the
fastest way to reclaim space from accumulated wisp bloat. Safe by default:
requires --force to actually delete.
Note: This uses time-based cleanup, appropriate for ephemeral wisps.
For graph-pressure staleness detection (blocking other work), see 'bd mol stale'.
Examples:
bd mol wisp gc # Clean abandoned wisps (default: 1h threshold)
bd mol wisp gc --dry-run # Preview what would be cleaned
bd mol wisp gc --age 24h # Custom age threshold
bd mol wisp gc --all # Also clean closed wisps older than threshold
bd mol wisp gc --closed # Preview closed wisp deletion
bd mol wisp gc --closed --force # Delete all closed wisps
bd mol wisp gc --closed --dry-run # Explicit dry-run (same as no --force)
bd mol wisp gc --exclude-type agent,rig # Protect agent and rig wisps from GC
bd mol wisp gc --closed --force --exclude-type mol # Delete closed wisps except mol type
```
bd mol wisp gc [flags]
```
**Flags:**
```
--age string Age threshold for abandoned wisp detection (default "1h")
--all Also clean closed wisps older than threshold
--closed Delete all closed wisps (ignores --age threshold)
--dry-run Preview what would be cleaned
--exclude-type strings Exclude wisps of these types from GC (comma-separated, e.g., agent,rig)
-f, --force Actually delete (default: preview only)
```
#### bd mol wisp list
List all wisps (ephemeral molecules) in the current context.
Wisps are issues with Ephemeral=true in the main database. They are stored
locally but not synced via git.
The list shows:
- ID: Issue ID of the wisp
- Title: Wisp title
- Status: Current status (open, in_progress, closed)
- Started: When the wisp was created
- Updated: Last modification time
Old wisp detection:
- Old wisps haven't been updated in 24+ hours
- Use 'bd mol wisp gc' to clean up old/abandoned wisps
Examples:
bd mol wisp list # List all wisps
bd mol wisp list --json # JSON output for programmatic use
bd mol wisp list --all # Include closed wisps
```
bd mol wisp list [flags]
```
**Flags:**
```
--all Include closed wisps
--type string Filter by issue type (e.g., agent, task, patrol)
```

View file

@ -1,32 +0,0 @@
---
id: note
title: bd note
slug: /cli-reference/note
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc note`
## bd note
Append a note to an issue's notes field.
Shorthand for 'bd update &lt;id&gt; --append-notes "text"'.
Examples:
bd note gt-abc "Fixed the flaky test"
bd note gt-abc Fixed the flaky test
echo "note from pipe" | bd note gt-abc --stdin
bd note gt-abc --file notes.txt
```
bd note <id> [text...] [flags]
```
**Flags:**
```
--file string Read note text from file
--stdin Read note text from stdin
```

View file

@ -1,112 +0,0 @@
---
id: notion
title: bd notion
slug: /cli-reference/notion
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc notion`
## bd notion
Commands for syncing issues between beads and Notion.
```
bd notion [flags]
```
### bd notion connect
Connect bd to an existing Notion database or data source
```
bd notion connect [flags]
```
**Flags:**
```
--url string Existing Notion database or data source URL
```
### bd notion init
Create a dedicated Beads database in Notion
```
bd notion init [flags]
```
**Flags:**
```
--parent string Parent page ID
--title string Database title (default "Beads Issues")
```
### bd notion pull
Pull one or more items from Notion.
Accepts bead IDs or external references as positional arguments.
Equivalent to: bd notion sync --pull --issues &lt;refs&gt;
```
bd notion pull [refs...] [flags]
```
**Flags:**
```
--dry-run Preview pull without making changes
```
### bd notion push
Push one or more beads issues to Notion.
Accepts bead IDs as positional arguments.
Equivalent to: bd notion sync --push --issues &lt;ids&gt;
```
bd notion push [bead-ids...] [flags]
```
**Flags:**
```
--dry-run Preview push without making changes
```
### bd notion status
Show Notion sync status
```
bd notion status [flags]
```
### bd notion sync
Synchronize issues between beads and Notion.
By default this performs bidirectional sync. Use --pull or --push to limit direction.
```
bd notion sync [flags]
```
**Flags:**
```
--create-only Only create missing remote pages, do not update existing ones
--dry-run Preview changes without making mutations
--issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
--parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues.
--prefer-local On conflict, keep the local beads version
--prefer-notion On conflict, use the Notion version
--pull Only pull issues from Notion
--push Only push issues to Notion
--state string Issue state to sync: open, closed, or all (default "all")
```

View file

@ -1,31 +0,0 @@
---
id: onboard
title: bd onboard
slug: /cli-reference/onboard
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc onboard`
## bd onboard
Display a minimal snippet to add to your agent instructions file for bd integration.
By default, the agent instructions file is AGENTS.md. Use 'bd init --agents-file'
to configure a different filename (e.g. BEADS.md).
This outputs a small (~10 line) snippet that points to 'bd prime' for full
workflow context. This is the same minimal profile that 'bd init' generates
by default. This approach:
• Keeps your agent file lean (doesn't bloat with instructions)
• bd prime provides dynamic, always-current workflow details
• Hooks auto-inject bd prime at session start
For agents or environments that do not auto-inject hook output, use
'bd init --agents-profile=full' to embed the complete command reference.
```
bd onboard [flags]
```

View file

@ -1,36 +0,0 @@
---
id: orphans
title: bd orphans
slug: /cli-reference/orphans
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc orphans`
## bd orphans
Identify orphaned issues - issues that are referenced in commit messages but remain open or in_progress in the database.
This helps identify work that has been implemented but not formally closed.
Examples:
bd orphans # Show orphaned issues
bd orphans --json # Machine-readable output
bd orphans --details # Show full commit information
bd orphans --fix # Close orphaned issues with confirmation
bd orphans --label theme:personal # Only orphans with this label
bd orphans --label-any theme:personal,theme:ventures # Orphans with either label
```
bd orphans [flags]
```
**Flags:**
```
--details Show full commit information
-f, --fix Close orphaned issues with confirmation
-l, --label strings Filter by labels (AND: must have ALL). Can combine with --label-any
--label-any strings Filter by labels (OR: must have AT LEAST ONE). Can combine with --label
```

View file

@ -1,29 +0,0 @@
---
id: ping
title: bd ping
slug: /cli-reference/ping
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc ping`
## bd ping
Lightweight health check that confirms bd can reach its database.
Steps:
1. Resolve the .beads workspace
2. Open the store (embedded or server)
3. Run a trivial query (issue count)
4. Report timing
Exit 0 on success, exit 1 on failure.
Examples:
bd ping # Quick connectivity check
bd ping --json # Structured output for automation
```
bd ping [flags]
```

View file

@ -1,41 +0,0 @@
---
id: preflight
title: bd preflight
slug: /cli-reference/preflight
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc preflight`
## bd preflight
Display a checklist of common pre-PR checks for contributors.
This command helps catch common issues before pushing to CI:
- Tests not run locally
- Lint errors
- Unformatted Go files
- .beads/issues.jsonl pollution
- Stale nix vendorHash
- Version mismatches
Examples:
bd preflight # Show checklist
bd preflight --check # Run checks automatically
bd preflight --check --json # JSON output for programmatic use
bd preflight --check --skip-lint # Explicitly skip lint check
```
bd preflight [flags]
```
**Flags:**
```
--check Run checks automatically
--fix Auto-fix issues where possible (vendorHash, version sync)
--json Output results as JSON
--skip-lint Skip lint check explicitly
```

View file

@ -1,63 +0,0 @@
---
id: prime
title: bd prime
slug: /cli-reference/prime
sidebar_position: 500
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc prime`
## bd prime
Output essential Beads workflow context in AI-optimized markdown format.
Automatically detects if MCP server is active and adapts output:
- MCP mode: Brief workflow reminders (~50 tokens)
- CLI mode: Full command reference (~1-2k tokens)
Designed for Claude Code, Gemini CLI, and Codex SessionStart hooks to prevent
agents from forgetting bd workflow after context compaction.
Config options:
- no-git-ops: When true, outputs stealth mode (no git commands in session close protocol).
Set via: bd config set no-git-ops true
Useful when you want to control when commits happen manually.
- agent.profile: Explicit policy profile for git/commit authority wording
(conservative | minimal | team-maintainer; default conservative).
Set via: bd config set agent.profile team-maintainer
Or per-session: BD_AGENT_PROFILE=team-maintainer (env var takes precedence).
See docs/SETUP.md#policy-profiles for what each profile means.
Workflow customization:
- Place a .beads/PRIME.md file in the local clone or resolved workspace to override the default output entirely.
- Use --export to dump the default content for customization.
- Use --memories-only for hook contexts that should inject only persistent memories.
Memory injection caps:
Large memory sets can exceed what a session-start hook host will ingest,
and hosts truncate silently. Cap what prime injects with --max-memories N
and/or --max-memory-chars N (or the prime.max-memories /
prime.max-memory-chars config keys; an explicit flag wins, and an explicit
0 forces unlimited). Caps apply at whole-memory boundaries, at least one
memory is always emitted, and a banner ahead of the entries reports how
many were elided and how to browse the rest with bd memories.
--max-memory-chars caps the total bytes of the injected memory entries;
the section header and elision banner are excluded from the budget.
```
bd prime [flags]
```
**Flags:**
```
--export Output default content (ignores PRIME.md override)
--full Force full CLI output (ignore MCP detection)
--hook-json Wrap output in the SessionStart hook JSON envelope (Claude Code, Gemini CLI, Codex)
--max-memories int Cap injected persistent memories to N entries (0 = unlimited; falls back to the prime.max-memories config key)
--max-memory-chars int Cap the total bytes of injected memory entries, at whole-memory boundaries; section header and banner are not counted (0 = unlimited; falls back to the prime.max-memory-chars config key)
--mcp Force MCP mode (minimal output)
--memories-only Output only persistent memories for compact hook contexts
--stealth Stealth mode (no git operations, flush only)
```

View file

@ -1,30 +0,0 @@
---
id: priority
title: bd priority
slug: /cli-reference/priority
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc priority`
## bd priority
Set the priority of an issue.
Shorthand for 'bd update &lt;id&gt; --priority &lt;n&gt;'.
Priority levels:
0 - Critical (security, data loss, broken builds)
1 - High (major features, important bugs)
2 - Medium (default)
3 - Low (polish, optimization)
4 - Backlog (future ideas)
Examples:
bd priority bd-123 0 # Critical
bd priority bd-123 2 # Medium
```
bd priority <id> <n> [flags]
```

View file

@ -1,33 +0,0 @@
---
id: promote
title: bd promote
slug: /cli-reference/promote
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc promote`
## bd promote
Promote a wisp (ephemeral issue) to a permanent bead.
This copies the issue from the wisps table (dolt_ignored) to the permanent
issues table (Dolt-versioned), preserving labels, dependencies, events, and
comments. The original ID is preserved so all links keep working.
A comment is added recording the promotion and optional reason.
Examples:
bd promote bd-wisp-abc123
bd promote bd-wisp-abc123 --reason "Worth tracking long-term"
```
bd promote <wisp-id> [flags]
```
**Flags:**
```
-r, --reason string Reason for promotion
```

View file

@ -1,57 +0,0 @@
---
id: prune
title: bd prune
slug: /cli-reference/prune
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc prune`
## bd prune
Permanently delete closed non-ephemeral beads and their associated data.
Use this to trim closed regular beads (tasks, features, bugs, chores, etc.)
that are no longer useful. The common case is a long-lived repo where
closed work has piled up and is bloating auto-export or slowing queries.
Requires --older-than or --pattern. The flag is a safety gate — without
it, a muscle-memory `--force` could wipe every closed bead in the repo.
Use `--pattern '*'` if you really do want to sweep everything closed.
Deletes: issues, dependencies, labels, events, and comments for matching beads.
Skips: pinned beads (protected), open/in-progress beads, and ephemeral beads.
Also skips closed beads whose ID appears in the description, notes, or
comments of any open / in-progress bead. This protects ADR / decision /
verification trails that downstream beads still cite. Use
--ignore-references to override (e.g., when bulk-decommissioning a
retired label across the rig).
To delete closed ephemeral beads (wisps, transient molecules) use
`bd purge` instead.
For full Dolt storage reclaim after deleting many rows, follow with `bd flatten`
so history can be collapsed and old chunks can be garbage-collected.
EXAMPLES:
bd prune --older-than 30d # Preview closed beads &gt;30d old
bd prune --older-than 30d --force # Delete them
bd prune --older-than 90d --dry-run # Detailed preview with stats
bd prune --pattern "*" --force # Delete all closed regular beads
bd prune --pattern "gm-temp-*" --force # Scope to a pattern
```
bd prune [flags]
```
**Flags:**
```
--dry-run Preview what would be pruned with stats
-f, --force Actually prune (without this, shows preview)
--ignore-references Delete closed beads even when referenced by open beads (use with care; see --help for details)
--older-than string Only prune beads closed more than N ago (e.g., 30d, 2w, 60)
--pattern string Only prune beads matching ID glob pattern (e.g., 'gm-old-*')
```

Some files were not shown because too many files have changed in this diff Show more