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:
parent
73a4d95fbc
commit
52aea3f7e3
810 changed files with 31 additions and 108635 deletions
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
31
.github/workflows/ci-measurements.yml
vendored
31
.github/workflows/ci-measurements.yml
vendored
|
|
@ -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
|
||||
|
|
|
|||
102
.github/workflows/deploy-docs.yml
vendored
102
.github/workflows/deploy-docs.yml
vendored
|
|
@ -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
|
||||
28
.github/workflows/main.yml
vendored
28
.github/workflows/main.yml
vendored
|
|
@ -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)
|
||||
|
|
|
|||
31
.github/workflows/pr.yml
vendored
31
.github/workflows/pr.yml
vendored
|
|
@ -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 }}
|
||||
|
|
|
|||
19
.github/workflows/release.yml
vendored
19
.github/workflows/release.yml
vendored
|
|
@ -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
|
||||
|
|
|
|||
6
Makefile
6
Makefile
|
|
@ -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)"
|
||||
|
|
|
|||
26
RELEASING.md
26
RELEASING.md
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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}"
|
||||
|
|
@ -65,9 +65,6 @@ check_version "npm-package/package.json" \
|
|||
|
||||
echo ""
|
||||
|
||||
if ! ./scripts/check-docs-version.sh; then
|
||||
MISMATCH=1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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}"
|
||||
|
|
@ -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
20
website/.gitignore
vendored
|
|
@ -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*
|
||||
|
|
@ -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).
|
||||
2603
website/bun.lock
2603
website/bun.lock
File diff suppressed because it is too large
Load diff
|
|
@ -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
|
||||
|
|
@ -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 -> deleted). For general
|
||||
health checks and automatic repairs, use 'bd doctor --fix' instead.
|
||||
|
||||
By default, deletes ALL closed issues. Use --older-than to only delete
|
||||
issues closed before a certain date.
|
||||
|
||||
EXAMPLES:
|
||||
bd admin cleanup --force # Delete all closed issues
|
||||
bd admin cleanup --older-than 30 --force # Only issues closed 30+ days ago
|
||||
bd admin cleanup --ephemeral --force # Only closed wisps (transient molecules)
|
||||
bd admin cleanup --dry-run # Preview what would be deleted
|
||||
|
||||
SAFETY:
|
||||
- Requires --force flag to actually delete (unless --dry-run)
|
||||
- Supports --cascade to delete dependents
|
||||
- Shows preview of what will be deleted
|
||||
- Use --json for programmatic output
|
||||
|
||||
SEE ALSO:
|
||||
bd doctor --fix Automatic health checks and repairs (recommended for routine maintenance)
|
||||
bd admin compact Compact old closed issues to save space
|
||||
|
||||
```
|
||||
bd admin cleanup [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--cascade Recursively delete all dependent issues
|
||||
--dry-run Preview what would be deleted without making changes
|
||||
--ephemeral Only delete closed wisps (transient molecules)
|
||||
-f, --force Actually delete (without this flag, shows error)
|
||||
--older-than int Only delete issues closed more than N days ago (0 = all closed issues)
|
||||
```
|
||||
|
||||
### bd admin compact
|
||||
|
||||
Compact old closed issues using semantic summarization.
|
||||
|
||||
Compaction reduces database size by summarizing closed issues that are no longer
|
||||
actively referenced. This is permanent graceful decay - original content is discarded.
|
||||
|
||||
Modes:
|
||||
- Analyze: Export candidates for agent review (no API key needed)
|
||||
- Apply: Accept agent-provided summary (no API key needed)
|
||||
- Auto: AI-powered compaction (requires ANTHROPIC_API_KEY or ai.api_key, legacy)
|
||||
- Dolt: Run Dolt garbage collection (for Dolt-backend repositories)
|
||||
|
||||
Tiers:
|
||||
- Tier 1: Semantic compression (30 days closed, 70% reduction)
|
||||
- Tier 2: Ultra compression (90 days closed) - planned, not yet implemented
|
||||
|
||||
Dolt Garbage Collection:
|
||||
With auto-commit per mutation, Dolt commit history grows over time. Use
|
||||
--dolt to run Dolt garbage collection and reclaim disk space.
|
||||
|
||||
--dolt: Run Dolt GC on .beads/dolt directory to free disk space.
|
||||
This removes unreachable commits and compacts storage.
|
||||
|
||||
Examples:
|
||||
# Dolt garbage collection
|
||||
bd compact --dolt # Run Dolt GC
|
||||
bd compact --dolt --dry-run # Preview without running GC
|
||||
|
||||
# Agent-driven workflow (recommended)
|
||||
bd compact --analyze --json # Get candidates with full content
|
||||
bd compact --apply --id bd-42 --summary summary.txt
|
||||
bd compact --apply --id bd-42 --summary - < summary.txt
|
||||
|
||||
# Legacy AI-powered workflow
|
||||
bd compact --auto --dry-run # Preview candidates
|
||||
bd compact --auto --all # Compact all eligible issues
|
||||
bd compact --auto --id bd-42 # Compact specific issue
|
||||
|
||||
# Statistics
|
||||
bd compact --stats # Show statistics
|
||||
|
||||
|
||||
```
|
||||
bd admin compact [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--actor string Actor name for audit trail (default "agent")
|
||||
--all Process all candidates
|
||||
--analyze Analyze mode: export candidates for agent review
|
||||
--apply Apply mode: accept agent-provided summary
|
||||
--auto Auto mode: AI-powered compaction (legacy)
|
||||
--batch-size int Issues per batch (default 10)
|
||||
--dolt Dolt mode: run Dolt garbage collection on .beads/dolt
|
||||
--dry-run Preview without compacting
|
||||
--force Force compact (bypass checks, requires --id)
|
||||
--id string Compact specific issue
|
||||
--json Output JSON format
|
||||
--limit int Limit number of candidates (0 = no limit)
|
||||
--stats Show compaction statistics
|
||||
--summary string Path to summary file (use '-' for stdin)
|
||||
--tier int Compaction tier (only tier 1 is implemented) (default 1)
|
||||
--workers int Parallel workers (default 5)
|
||||
```
|
||||
|
||||
### bd admin reset
|
||||
|
||||
Reset beads to an uninitialized state, removing all local data.
|
||||
|
||||
This command removes:
|
||||
- The .beads directory (database, JSONL, config)
|
||||
- Git hooks installed by bd
|
||||
- Sync branch worktrees
|
||||
|
||||
By default, shows what would be deleted (dry-run mode).
|
||||
Use --force to actually perform the reset.
|
||||
|
||||
Examples:
|
||||
bd reset # Show what would be deleted
|
||||
bd reset --force # Actually delete everything
|
||||
|
||||
```
|
||||
bd admin reset [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--force Actually perform the reset (required)
|
||||
```
|
||||
|
|
@ -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 <refs>
|
||||
|
||||
```
|
||||
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 <ids>
|
||||
|
||||
```
|
||||
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")
|
||||
```
|
||||
|
|
@ -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 <id> --assignee <name>'.
|
||||
|
||||
Examples:
|
||||
bd assign bd-123 alice
|
||||
bd assign bd-123 "" # unassign
|
||||
|
||||
```
|
||||
bd assign <id> <name> [flags]
|
||||
```
|
||||
|
|
@ -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 <id> --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)
|
||||
```
|
||||
|
|
@ -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 <path> 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/<user>/<repo>
|
||||
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 && 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 <path>' first to configure a destination.
|
||||
|
||||
```
|
||||
bd backup sync [flags]
|
||||
```
|
||||
|
|
@ -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 <id> [reason...]
|
||||
update <id> <key>=<value> [<key>=<value> ...]
|
||||
create <type> <priority> <title...>
|
||||
dep add <from-id> <to-id> [type]
|
||||
dep remove <from-id> <to-id>
|
||||
#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 '{print "close",$1," stale"}' | 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>')
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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)
|
||||
```
|
||||
|
|
@ -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]
|
||||
```
|
||||
|
|
@ -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 <id> --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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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 <id> "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
|
||||
```
|
||||
|
|
@ -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 <issue-id> to list comments
|
||||
|
||||
```
|
||||
bd comments list [flags]
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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 <(bd completion bash)
|
||||
|
||||
To load completions for every new session, execute once:
|
||||
|
||||
#### Linux:
|
||||
|
||||
bd completion bash > /etc/bash_completion.d/bd
|
||||
|
||||
#### macOS:
|
||||
|
||||
bd completion bash > $(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 > ~/.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" >> ~/.zshrc
|
||||
|
||||
To load completions in your current shell session:
|
||||
|
||||
source <(bd completion zsh)
|
||||
|
||||
To load completions for every new session, execute once:
|
||||
|
||||
#### Linux:
|
||||
|
||||
bd completion zsh > "${fpath[1]}/_bd"
|
||||
|
||||
#### macOS:
|
||||
|
||||
bd completion zsh > $(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
|
||||
```
|
||||
|
|
@ -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.<slug>
|
||||
|
||||
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]
|
||||
```
|
||||
|
|
@ -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]
|
||||
```
|
||||
|
|
@ -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 {{variable}} 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 {{vars}}
|
||||
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
|
||||
```
|
||||
|
|
@ -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)
|
||||
```
|
||||
|
|
@ -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')
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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)
|
||||
```
|
||||
|
|
@ -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)
|
||||
```
|
||||
|
|
@ -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 <blocker-id> --blocks <blocked-id>
|
||||
|
||||
This is equivalent to:
|
||||
bd dep add <blocked-id> <blocker-id>
|
||||
|
||||
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:<project>:<capability>
|
||||
|
||||
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: {"from":"bd-42","to":"bd-41"}
|
||||
|
||||
```
|
||||
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]
|
||||
```
|
||||
|
|
@ -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]
|
||||
```
|
||||
|
|
@ -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.<check-slug> 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.<slug>
|
||||
|
||||
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)
|
||||
```
|
||||
|
|
@ -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 <k> <v> 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 <name> <url> Add a Dolt remote
|
||||
bd dolt remote list List configured remotes
|
||||
bd dolt remote remove <name> 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 <N>)
|
||||
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 <name> <url> Add a new remote
|
||||
list List all configured remotes
|
||||
remove <name> 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 <N>)
|
||||
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]
|
||||
```
|
||||
|
|
@ -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)
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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]
|
||||
```
|
||||
|
|
@ -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)
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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]
|
||||
```
|
||||
|
|
@ -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. <resolved-beads-dir>/formulas/ (active project)
|
||||
2. <checkout-root>/.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. <resolved-beads-dir>/formulas/ (active project - highest priority)
|
||||
2. <checkout-root>/.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 <primitive>'.
|
||||
|
||||
Examples:
|
||||
bd formula show shiny
|
||||
bd formula show rule-of-five
|
||||
bd formula show security-audit --json
|
||||
|
||||
```
|
||||
bd formula show <formula-name> [flags]
|
||||
```
|
||||
|
|
@ -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 <rig>:<bead-id> (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 <id> # 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 <id> --json status,conclusion'
|
||||
- gh:pr checks 'gh pr view <id> --json state,title'
|
||||
|
||||
A gate is resolved when:
|
||||
- gh:run: status=completed AND conclusion=success
|
||||
- gh:pr: state=MERGED
|
||||
- timer: current time > 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 <gate-id>' 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]
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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 <refs>
|
||||
|
||||
```
|
||||
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 <ids>
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
|
@ -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 <refs>
|
||||
|
||||
```
|
||||
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 <ids>
|
||||
|
||||
```
|
||||
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')
|
||||
```
|
||||
|
|
@ -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 > 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 > graph.svg # SVG via Graphviz
|
||||
bd graph --dot issue-id | dot -Tpng > graph.png # PNG via Graphviz
|
||||
bd graph --html issue-id > graph.html # Interactive browser view
|
||||
bd graph --all --html > 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]
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
@ -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)
|
||||
```
|
||||
|
|
@ -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]
|
||||
```
|
||||
|
|
@ -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 <id> Respond to a human-needed bead (adds comment and closes)
|
||||
human dismiss <id> 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]
|
||||
```
|
||||
|
|
@ -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 {issue_id, depends_on_id, type, ...}.
|
||||
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
|
||||
```
|
||||
|
|
@ -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)
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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-<issue-prefix>
|
||||
|
||||
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]
|
||||
```
|
||||
|
|
@ -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=<postgres|mysql|sqlite>;
|
||||
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 <claude|cursor|aider|...> --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
|
||||
```
|
||||
|
|
@ -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 <refs>
|
||||
|
||||
```
|
||||
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 <ids>
|
||||
|
||||
```
|
||||
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")
|
||||
```
|
||||
|
|
@ -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]
|
||||
```
|
||||
|
|
@ -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]
|
||||
```
|
||||
|
|
@ -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 > LINEAR_API_KEY > 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 -> Backlog
|
||||
bd config set linear.priority_map.1 0 # Urgent -> Critical
|
||||
bd config set linear.priority_map.2 1 # High -> High
|
||||
bd config set linear.priority_map.3 2 # Medium -> Medium
|
||||
bd config set linear.priority_map.4 3 # Low -> 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 <refs>
|
||||
|
||||
```
|
||||
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 <ids>
|
||||
|
||||
```
|
||||
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]
|
||||
```
|
||||
|
|
@ -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 <id1> <id2>'. 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")
|
||||
```
|
||||
|
|
@ -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)
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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]
|
||||
```
|
||||
|
|
@ -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]
|
||||
```
|
||||
|
|
@ -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: <prefix>-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 <holder>: 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)
|
||||
```
|
||||
|
|
@ -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]
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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 ({{key}}) 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-{{worker_name}} --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-{{name}} --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 (>100 steps), a summary is shown instead.
|
||||
Use --limit or --range to view specific steps:
|
||||
bd mol current <id> --limit 50 # Show first 50 steps
|
||||
bd mol current <id> --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 {{variable}} 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. <resolved-beads-dir>/formulas/ (project-level, default)
|
||||
2. <checkout-root>/.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) -> pour -> 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. <resolved-beads-dir>/formulas/ (active project)
|
||||
2. <checkout-root>/.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 <proto> or bd create --ephemeral
|
||||
2. Execute: Normal bd operations work on wisp issues
|
||||
3. Squash: bd mol squash <id> (clears Ephemeral flag, promotes to persistent)
|
||||
4. Or burn: bd mol burn <id> (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) -> 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)
|
||||
```
|
||||
|
|
@ -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 <id> --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
|
||||
```
|
||||
|
|
@ -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 <refs>
|
||||
|
||||
```
|
||||
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 <ids>
|
||||
|
||||
```
|
||||
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")
|
||||
```
|
||||
|
|
@ -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]
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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]
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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)
|
||||
```
|
||||
|
|
@ -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 <id> --priority <n>'.
|
||||
|
||||
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]
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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 >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
Loading…
Add table
Add a link
Reference in a new issue