fix(docgen): generate CLI docs in one process (#4474)

Add a bulk help docs writer that emits the root CLI reference and website command pages from a single Cobra walk. Update the shell generator to call that mode, preserve the pure-Go docs binary guard, and refresh historical versioned CLI docs only when release snapshotting requests a specific version.

Agent-Signature: codex-gpt-5.5-medium on behalf of matt wilkie
This commit is contained in:
matt wilkie 2026-06-22 18:25:58 -07:00 • committed by GitHub
commit dfa8ea4813
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
64 changed files with 356 additions and 244 deletions

View file

@ -1,10 +1,12 @@
package main
import (
"bytes"
"errors"
"fmt"
"io"
"os"
"path/filepath"
"sort"
"strings"
"unicode"
@ -21,6 +23,12 @@ var helpDocFlag string
// helpListFlag is the --list flag for listing available commands
var helpListFlag bool
// helpDocsRootFlag is the --docs-root flag for generating repository docs in one process.
var helpDocsRootFlag string
// helpDocsVersionFlag is the --docs-version flag for refreshing one versioned docs snapshot.
var helpDocsVersionFlag string
// registerHelpAllFlag adds the --all, --doc, and --list flags to Cobra's auto-generated help command.
// Must be called after rootCmd.InitDefaultHelpCmd() has run (i.e., after first Execute
// or explicit init). We hook it in init() after all subcommands are registered.
@ -34,10 +42,19 @@ func registerHelpAllFlag() {
cmd.Flags().BoolVar(&helpAllFlag, "all", false, "Show help for all commands in a single document")
cmd.Flags().StringVar(&helpDocFlag, "doc", "", "Generate markdown docs for a single command")
cmd.Flags().BoolVar(&helpListFlag, "list", false, "List all available commands")
cmd.Flags().StringVar(&helpDocsRootFlag, "docs-root", "", "Generate repository CLI docs under this root")
cmd.Flags().StringVar(&helpDocsVersionFlag, "docs-version", "", "Also refresh one versioned website CLI reference, e.g. 1.0.5")
// Wrap the existing Run to check --all, --doc, and --list first
originalRun := cmd.Run
cmd.Run = func(cmd *cobra.Command, args []string) {
if helpDocsRootFlag != "" {
if err := writeGeneratedCLIDocs(rootCmd, helpDocsRootFlag, helpDocsVersionFlag); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
return
}
if helpListFlag {
// Handle --list flag: list all available commands
listAllCommands(os.Stdout, rootCmd)
@ -274,6 +291,102 @@ func writeSingleCommandDoc(w io.Writer, root *cobra.Command, cmdName string) err
return nil
}
func writeGeneratedCLIDocs(root *cobra.Command, repoRoot, docsVersion string) error {
repoRoot = filepath.Clean(repoRoot)
var all bytes.Buffer
writeAllHelp(&all, root)
if err := writeMarkdownFile(filepath.Join(repoRoot, "docs", "CLI_REFERENCE.md"), all.String()); err != nil {
return err
}
if err := writeCLIReferenceDir(filepath.Join(repoRoot, "website", "docs", "cli-reference"), root, "Latest"); err != nil {
return err
}
if docsVersion != "" {
versionDir := filepath.Join(repoRoot, "website", "versioned_docs", "version-"+docsVersion, "cli-reference")
if err := writeCLIReferenceDir(versionDir, root, "v"+docsVersion); err != nil {
return err
}
}
return nil
}
func writeCLIReferenceDir(outDir string, root *cobra.Command, versionLabel string) error {
if err := os.MkdirAll(outDir, 0o755); err != nil {
return err
}
if err := removeMarkdownFiles(outDir); err != nil {
return err
}
commands := availableCommandNames(root)
if err := writeMarkdownFile(filepath.Join(outDir, "index.md"), cliReferenceIndex(commands, versionLabel)); err != nil {
return err
}
for _, name := range commands {
var out bytes.Buffer
if err := writeSingleCommandDoc(&out, root, name); err != nil {
return err
}
path := filepath.Join(outDir, commandDocID(name)+".md")
if err := writeMarkdownFile(path, out.String()); err != nil {
return err
}
}
return nil
}
func cliReferenceIndex(commands []string, versionLabel string) string {
var b strings.Builder
fmt.Fprintf(&b, "---\n")
fmt.Fprintf(&b, "id: index\n")
fmt.Fprintf(&b, "title: CLI Reference\n")
fmt.Fprintf(&b, "sidebar_position: 0\n")
fmt.Fprintf(&b, "---\n\n")
fmt.Fprintf(&b, "# CLI Reference\n\n")
fmt.Fprintf(&b, "<!-- AUTO-GENERATED: do not edit manually -->\n")
fmt.Fprintf(&b, "Reference for bd %s. Generated from `bd help --docs-root`.\n\n", versionLabel)
fmt.Fprintf(&b, "This reference covers all %d live top-level `bd` commands. Regenerate it with:\n\n", len(commands))
fmt.Fprintf(&b, "```bash\n")
fmt.Fprintf(&b, "./scripts/generate-cli-docs.sh\n")
fmt.Fprintf(&b, "```\n\n")
fmt.Fprintf(&b, "## Commands\n\n")
for _, cmd := range commands {
fmt.Fprintf(&b, "- [`bd %s`](./%s.md)\n", cmd, commandDocID(cmd))
}
return b.String()
}
func writeMarkdownFile(path, content string) error {
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
return err
}
content = strings.TrimRight(content, "\n") + "\n"
// #nosec G306: generated repository Markdown should be readable like source files.
return os.WriteFile(path, []byte(content), 0o644)
}
func removeMarkdownFiles(dir string) error {
entries, err := os.ReadDir(dir)
if err != nil {
return err
}
for _, entry := range entries {
if entry.IsDir() || filepath.Ext(entry.Name()) != ".md" {
continue
}
if err := os.Remove(filepath.Join(dir, entry.Name())); err != nil {
return err
}
}
return nil
}
// findCommand finds a command by name in the command tree.
// Supports nested commands like "mol pour" by splitting on space.
func findCommand(root *cobra.Command, name string) *cobra.Command {

View file

@ -2,6 +2,8 @@ package main
import (
"bytes"
"os"
"path/filepath"
"strings"
"testing"
@ -163,3 +165,53 @@ func TestHelpDocFlagTextDoesNotClaimDashMeansStdout(t *testing.T) {
t.Fatalf("help --doc flag still documents unsupported '-' stdout sentinel: %q", flag.Usage)
}
}
func TestWriteGeneratedCLIDocsWritesLiveAndRequestedVersionedDocs(t *testing.T) {
root := &cobra.Command{Use: "bd"}
root.AddCommand(
testHelpCmd("show <id>", "Show an issue"),
testHelpCmd("create", "Create an issue"),
)
dir := t.TempDir()
if err := writeGeneratedCLIDocs(root, dir, "1.2.3"); err != nil {
t.Fatalf("writeGeneratedCLIDocs() error = %v", err)
}
assertFileContains(t, filepath.Join(dir, "docs", "CLI_REFERENCE.md"), "# bd — Complete Command Reference")
assertFileContains(t, filepath.Join(dir, "website", "docs", "cli-reference", "index.md"), "Reference for bd Latest")
assertFileContains(t, filepath.Join(dir, "website", "docs", "cli-reference", "create.md"), "Generated from `bd help --doc create`")
assertFileContains(t, filepath.Join(dir, "website", "versioned_docs", "version-1.2.3", "cli-reference", "index.md"), "Reference for bd v1.2.3")
assertFileContains(t, filepath.Join(dir, "website", "versioned_docs", "version-1.2.3", "cli-reference", "show.md"), "## bd show")
}
func TestWriteGeneratedCLIDocsDoesNotTouchVersionedDocsWithoutVersion(t *testing.T) {
root := &cobra.Command{Use: "bd"}
root.AddCommand(testHelpCmd("show <id>", "Show an issue"))
dir := t.TempDir()
versioned := filepath.Join(dir, "website", "versioned_docs", "version-1.0.0", "cli-reference")
if err := os.MkdirAll(versioned, 0o755); err != nil {
t.Fatal(err)
}
sentinel := filepath.Join(versioned, "sentinel.md")
if err := os.WriteFile(sentinel, []byte("keep me\n"), 0o644); err != nil {
t.Fatal(err)
}
if err := writeGeneratedCLIDocs(root, dir, ""); err != nil {
t.Fatalf("writeGeneratedCLIDocs() error = %v", err)
}
assertFileContains(t, sentinel, "keep me")
}
func assertFileContains(t *testing.T, path, want string) {
t.Helper()
data, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read %s: %v", path, err)
}
if !strings.Contains(string(data), want) {
t.Fatalf("%s missing %q in:\n%s", path, want, string(data))
}
}

View file

@ -5860,10 +5860,12 @@ bd help [command] [flags]
**Flags:**
```
--all Show help for all commands in a single document
--doc string Generate markdown docs for a single command
-h, --help help for help
--list List all available commands
--all Show help for all commands in a single document
--doc string Generate markdown docs for a single command
--docs-root string Generate repository CLI docs under this root
--docs-version string Also refresh one versioned website CLI reference, e.g. 1.0.5
-h, --help help for help
--list List all available commands
```
### bd init-safety

View file

@ -72,7 +72,6 @@ fi
GEN_PATHSPECS=(
"docs/CLI_REFERENCE.md"
"website/docs/cli-reference"
":(glob)website/versioned_docs/*/cli-reference/**"
"website/static/llms-full.txt"
)
@ -114,12 +113,8 @@ surface_fingerprint() {
cat "$f"
fi
done
local dirs=()
for d in website/docs/cli-reference website/versioned_docs/*/cli-reference; do
[ -d "$d" ] && dirs+=("$d")
done
if [ "${#dirs[@]}" -gt 0 ]; then
find "${dirs[@]}" -type f -name '*.md' | sort | while IFS= read -r f; do
if [ -d website/docs/cli-reference ]; then
find website/docs/cli-reference -type f -name '*.md' | sort | while IFS= read -r f; do
printf '== %s\n' "$f"
cat "$f"
done

View file

@ -133,12 +133,6 @@ if [ -f "$CLI_REF" ]; then
fi
WEBSITE_DIRS=("$PROJECT_ROOT/website/docs/cli-reference")
if [ -d "$PROJECT_ROOT/website/versioned_docs" ]; then
for vdir in "$PROJECT_ROOT"/website/versioned_docs/version-*; do
[ -d "$vdir" ] || continue
WEBSITE_DIRS+=("$vdir/cli-reference")
done
fi
for dir in "${WEBSITE_DIRS[@]}"; do
if [ ! -d "$dir" ]; then
continue

View file

@ -106,7 +106,7 @@ if [ "$MISMATCH" -ne 0 ]; then
echo " npx docusaurus docs:version $CANONICAL"
echo " cd .."
echo " # Ensure website/docusaurus.config.ts lastVersion is '$CANONICAL'"
echo " ./scripts/generate-cli-docs.sh ./bd"
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"
;;

View file

@ -18,6 +18,9 @@ Generates maintained CLI reference docs from the live Cobra command tree exposed
# Regenerate checked-in CLI docs using a temporary no-cgo build
./scripts/generate-cli-docs.sh
# Regenerate the live docs and one release snapshot
./scripts/generate-cli-docs.sh --versioned 1.0.5
# Regenerate/check against an existing binary
./scripts/generate-cli-docs.sh ./bd
./scripts/generate-cli-docs.sh --check ./bd
@ -25,12 +28,12 @@ Generates maintained CLI reference docs from the live Cobra command tree exposed
### Outputs
- `docs/CLI_REFERENCE.md` from `bd help --all`
- `website/docs/cli-reference/*.md` from `bd help --list` and `bd help --doc <command>`
- `website/versioned_docs/version-*/cli-reference/*.md` so published versioned docs and the llms artifact source stay in sync
- `docs/CLI_REFERENCE.md` from the live Cobra command tree
- `website/docs/cli-reference/*.md` from the live Cobra command tree
- `website/versioned_docs/version-X.Y.Z/cli-reference/*.md` only when `--versioned X.Y.Z` is supplied by the release snapshot workflow
- `website/static/llms-full.txt` freshness is checked from the same generated website docs tree
`scripts/check-doc-flags.sh` runs the `--check` mode in CI and fails when live top-level commands are missing from generated docs or `llms-full.txt` is stale.
`scripts/check-doc-flags.sh` runs the `--check` mode in CI and fails when live top-level commands are missing from live generated docs or `llms-full.txt` is stale. Historical Docusaurus CLI snapshots are release artifacts; ordinary PR checks do not rewrite them to match unreleased commands.
## check-docs-version.sh

View file

@ -8,15 +8,43 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
CHECK_MODE=0
if [ "${1:-}" = "--check" ]; then
CHECK_MODE=1
shift
fi
BD_ARG="${1:-}"
VERSIONED_VERSION=""
BD_ARG=""
TMP_BUILD_DIR=""
TMP_OUTPUT_DIR=""
while [ "$#" -gt 0 ]; do
case "$1" in
--check)
CHECK_MODE=1
shift
;;
--versioned)
[ "$#" -ge 2 ] || { echo "Error: --versioned needs a version" >&2; exit 2; }
VERSIONED_VERSION="$2"
shift 2
;;
-h|--help)
cat <<'EOF'
Usage: scripts/generate-cli-docs.sh [--check] [--versioned VERSION] [path-to-bd]
Generate live CLI docs from one bd process. Historical Docusaurus snapshots are
left untouched unless --versioned VERSION is supplied by the release snapshot
workflow.
EOF
exit 0
;;
*)
if [ -n "$BD_ARG" ]; then
echo "Error: multiple bd binaries supplied: $BD_ARG and $1" >&2
exit 2
fi
BD_ARG="$1"
shift
;;
esac
done
cleanup() {
if [ -n "$TMP_BUILD_DIR" ]; then
rm -rf "$TMP_BUILD_DIR"
@ -38,107 +66,31 @@ else
(cd "$PROJECT_ROOT" && CGO_ENABLED=0 go build -tags gms_pure_go -o "$BD" ./cmd/bd/)
fi
# Guard against a CGO-enabled bd: it exposes `bd federation` subcommands that CI never
# produces (scripts/ci/pr-policy.sh build_docs_binary uses env CGO_ENABLED=0 go build).
# If the resolved binary does not print the pure-go stub, rebuild pure-go internally.
if [ -x "$BD" ] && ! "$BD" federation --help 2>&1 | grep -q "Federation commands require CGO"; then
echo "CGO-enabled bd detected at $BD; rebuilding pure-go binary for CI-consistent docs..."
if [ -z "$TMP_BUILD_DIR" ]; then
TMP_BUILD_DIR="$(mktemp -d)"
fi
BD="$TMP_BUILD_DIR/bd-pure"
(cd "$PROJECT_ROOT" && CGO_ENABLED=0 go build -tags gms_pure_go -o "$BD" ./cmd/bd/)
fi
if [ ! -x "$BD" ]; then
echo "Error: bd binary not found or not executable: $BD" >&2
echo "Usage: $0 [--check] [path-to-bd]" >&2
echo "Usage: $0 [--check] [--versioned VERSION] [path-to-bd]" >&2
exit 1
fi
command_doc_id() {
printf '%s' "$1" \
| tr '[:upper:] ' '[:lower:]-' \
| sed -E 's/[^a-z0-9-]+/-/g; s/-+/-/g; s/^-//; s/-$//'
}
trim_trailing_blank_lines() {
perl -0pi -e 's/\n+\z/\n/' "$1"
}
generate_index() {
local out_dir="$1"
local commands_file="$2"
local version_label="$3"
local count
count="$(wc -l < "$commands_file" | tr -d ' ')"
cat > "$out_dir/index.md" << EOF
---
id: index
title: CLI Reference
sidebar_position: 0
---
# CLI Reference
<!-- AUTO-GENERATED: do not edit manually -->
Reference for bd ${version_label}. Generated from \`bd help --list\` and \`bd help --doc <command>\`.
This reference covers all ${count} live top-level \`bd\` commands. Regenerate it with:
\`\`\`bash
./scripts/generate-cli-docs.sh
\`\`\`
## Commands
EOF
while IFS= read -r cmd; do
cmd="${cmd%$'\r'}"
local doc_id
doc_id="$(command_doc_id "$cmd")"
printf -- "- [\`bd %s\`](./%s.md)\n" "$cmd" "$doc_id" >> "$out_dir/index.md"
done < "$commands_file"
}
generate_cli_dir() {
local out_dir="$1"
local commands_file="$2"
local version_label="$3"
mkdir -p "$out_dir"
rm -f "$out_dir"/*.md
generate_index "$out_dir" "$commands_file" "$version_label"
while IFS= read -r cmd; do
cmd="${cmd%$'\r'}"
local doc_id
doc_id="$(command_doc_id "$cmd")"
"$BD" help --doc "$cmd" < /dev/null > "$out_dir/$doc_id.md"
trim_trailing_blank_lines "$out_dir/$doc_id.md"
done < "$commands_file"
}
generate_all() {
local root="$1"
local commands_file="$root/.cli-commands.txt"
mkdir -p "$root/docs"
"$BD" help --list > "$commands_file"
"$BD" help --all > "$root/docs/CLI_REFERENCE.md"
trim_trailing_blank_lines "$root/docs/CLI_REFERENCE.md"
generate_cli_dir "$root/website/docs/cli-reference" "$commands_file" "Latest"
# Versioned snapshots: parse the semver tag from the directory name
# (e.g. "version-1.0.0" -> "v1.0.0") so a release bump alone produces
# zero diff on the dev tree.
local versioned_parent="$PROJECT_ROOT/website/versioned_docs"
if [ -d "$versioned_parent" ]; then
local versioned_dir
for versioned_dir in "$versioned_parent"/version-*; do
[ -d "$versioned_dir" ] || continue
local dir_name
dir_name="$(basename "$versioned_dir")"
local version_tag="v${dir_name#version-}"
generate_cli_dir \
"$root/website/versioned_docs/$dir_name/cli-reference" \
"$commands_file" \
"$version_tag"
done
local args=(help --docs-root "$root")
if [ -n "$VERSIONED_VERSION" ]; then
args+=(--docs-version "$VERSIONED_VERSION")
fi
rm -f "$commands_file"
"$BD" "${args[@]}"
}
if [ "$CHECK_MODE" -eq 1 ]; then
@ -164,11 +116,8 @@ if [ "$CHECK_MODE" -eq 1 ]; then
fi
check_dirs=("website/docs/cli-reference")
if [ -d "$PROJECT_ROOT/website/versioned_docs" ]; then
for vdir in "$PROJECT_ROOT/website/versioned_docs"/version-*; do
[ -d "$vdir" ] || continue
check_dirs+=("website/versioned_docs/$(basename "$vdir")/cli-reference")
done
if [ -n "$VERSIONED_VERSION" ]; then
check_dirs+=("website/versioned_docs/version-$VERSIONED_VERSION/cli-reference")
fi
for rel in "${check_dirs[@]}"; do
@ -188,5 +137,9 @@ if [ "$CHECK_MODE" -eq 1 ]; then
else
generate_all "$PROJECT_ROOT"
echo "Generated CLI docs from: $($BD version 2>/dev/null | head -1 || echo "$BD")"
echo "Updated docs/CLI_REFERENCE.md and website CLI reference pages"
if [ -n "$VERSIONED_VERSION" ]; then
echo "Updated docs/CLI_REFERENCE.md, website CLI reference pages, and version-$VERSIONED_VERSION CLI snapshot"
else
echo "Updated docs/CLI_REFERENCE.md and live website CLI reference pages"
fi
fi

View file

@ -79,7 +79,7 @@ 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 "$BD_DOCS"
./scripts/generate-cli-docs.sh --versioned "$VERSION" "$BD_DOCS"
echo " • generate-llms-full.sh"
./scripts/generate-llms-full.sh

View file

@ -21,7 +21,7 @@ For routine maintenance, prefer 'bd doctor --fix' which handles common repairs
automatically. Use these admin commands for targeted database operations.
```
bd admin
bd admin [flags]
```
### bd admin cleanup

View file

@ -20,7 +20,7 @@ Configuration can be set via 'bd config' or environment variables:
ado.url / AZURE_DEVOPS_URL - Custom base URL (on-prem)
```
bd ado
bd ado [flags]
```
### bd ado projects
@ -28,7 +28,7 @@ bd ado
List Azure DevOps projects that the configured token has access to.
```
bd ado projects
bd ado projects [flags]
```
### bd ado pull
@ -70,7 +70,7 @@ bd ado push [bead-ids...] [flags]
Display current Azure DevOps configuration and sync status.
```
bd ado status
bd ado status [flags]
```
### bd ado sync

View file

@ -19,5 +19,5 @@ Examples:
bd assign bd-123 "" # unassign
```
bd assign <id> <name>
bd assign <id> <name> [flags]
```

View file

@ -19,7 +19,7 @@ Each line is one event. This file is intended to be versioned in git and used fo
Entries are append-only. Labeling creates a new "label" entry that references a parent entry.
```
bd audit
bd audit [flags]
```
### bd audit label

View file

@ -29,7 +29,7 @@ DoltHub is recommended for cloud backup:
Set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD for authentication.
```
bd backup
bd backup [flags]
```
### bd backup init
@ -50,7 +50,7 @@ DoltHub (recommended for cloud backup):
After adding, run 'bd backup sync' to push your data.
```
bd backup init <path>
bd backup init <path> [flags]
```
**Aliases:** add
@ -63,7 +63,7 @@ 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
bd backup remove [flags]
```
**Aliases:** rm
@ -99,7 +99,7 @@ bd backup restore [path] [flags]
Show last backup status
```
bd backup status
bd backup status [flags]
```
### bd backup sync
@ -114,5 +114,5 @@ The backup is atomic — if the sync fails, the previous backup state is preserv
Run 'bd backup init &lt;path&gt;' first to configure a destination.
```
bd backup sync
bd backup sync [flags]
```

View file

@ -20,5 +20,5 @@ Examples:
bd branch feature-xyz # Create a new branch named feature-xyz
```
bd branch [name]
bd branch [name] [flags]
```

View file

@ -62,5 +62,5 @@ bd comments add [issue-id] [text] [flags]
Invalid — use bd comments &lt;issue-id&gt; to list comments
```
bd comments list
bd comments list [flags]
```

View file

@ -15,7 +15,7 @@ See each sub-command's help for details on how to use the generated script.
```
bd completion
bd completion [flags]
```
### bd completion bash

View file

@ -79,7 +79,7 @@ Examples:
bd config unset jira.url
```
bd config
bd config [flags]
```
### bd config apply
@ -131,7 +131,7 @@ Examples:
bd config drift --json
```
bd config drift
bd config drift [flags]
```
### bd config get
@ -139,7 +139,7 @@ bd config drift
Get a configuration value
```
bd config get <key>
bd config get <key> [flags]
```
### bd config list
@ -147,7 +147,7 @@ bd config get <key>
List all configuration
```
bd config list
bd config list [flags]
```
### bd config set
@ -221,7 +221,7 @@ bd config show [flags]
Delete a configuration value
```
bd config unset <key>
bd config unset <key> [flags]
```
### bd config validate
@ -239,5 +239,5 @@ Checks:
bd config validate --json
```
bd config validate
bd config validate [flags]
```

View file

@ -22,5 +22,5 @@ Examples:
```
bd context
bd context [flags]
```

View file

@ -84,7 +84,7 @@ bd dep add [issue-id] [depends-on-id] [flags]
Detect dependency cycles
```
bd dep cycles
bd dep cycles [flags]
```
### bd dep list
@ -129,7 +129,7 @@ Examples:
bd relate bd-123 bd-456 # Create see-also connection
```
bd dep relate <id1> <id2>
bd dep relate <id1> <id2> [flags]
```
### bd dep remove
@ -137,7 +137,7 @@ bd dep relate <id1> <id2>
Remove a dependency
```
bd dep remove [issue-id] [depends-on-id]
bd dep remove [issue-id] [depends-on-id] [flags]
```
**Aliases:** rm
@ -182,5 +182,5 @@ Example:
bd unrelate bd-abc bd-xyz
```
bd dep unrelate <id1> <id2>
bd dep unrelate <id1> <id2> [flags]
```

View file

@ -23,5 +23,5 @@ Examples:
bd diff abc123 def456 # Compare two specific commits
```
bd diff <from-ref> <to-ref>
bd diff <from-ref> <to-ref> [flags]
```

View file

@ -53,7 +53,7 @@ Examples:
bd dolt test
```
bd dolt
bd dolt [flags]
```
### bd dolt clean-databases
@ -113,7 +113,7 @@ project's Dolt data directory are eligible for cleanup. Other projects'
servers are preserved.
```
bd dolt killall
bd dolt killall [flags]
```
### bd dolt pull
@ -172,7 +172,7 @@ Subcommands:
remove &lt;name&gt; Remove a remote
```
bd dolt remote
bd dolt remote [flags]
```
#### bd dolt remote add
@ -180,7 +180,7 @@ bd dolt remote
Add a Dolt remote
```
bd dolt remote add <name> <url>
bd dolt remote add <name> <url> [flags]
```
#### bd dolt remote list
@ -188,7 +188,7 @@ bd dolt remote add <name> <url>
List configured Dolt remotes
```
bd dolt remote list
bd dolt remote list [flags]
```
#### bd dolt remote remove
@ -196,7 +196,7 @@ bd dolt remote list
Remove a Dolt remote
```
bd dolt remote remove <name>
bd dolt remote remove <name> [flags]
```
### bd dolt set
@ -233,7 +233,7 @@ bd dolt set <key> <value> [flags]
Show current Dolt configuration with connection status
```
bd dolt show
bd dolt show [flags]
```
### bd dolt start
@ -247,7 +247,7 @@ The server auto-starts transparently when needed, so manual start is rarely
required. Use this command for explicit control or diagnostics.
```
bd dolt start
bd dolt start [flags]
```
### bd dolt status
@ -263,7 +263,7 @@ sql-server) — pings the configured endpoint via SQL and reports
reachability, server version, and database.
```
bd dolt status
bd dolt status [flags]
```
### bd dolt stop
@ -294,5 +294,5 @@ This verifies that:
Use this before switching to server mode to ensure the server is running.
```
bd dolt test
bd dolt test [flags]
```

View file

@ -13,7 +13,7 @@ Generated from `bd help --doc epic`
Epic management commands
```
bd epic
bd epic [flags]
```
### bd epic close-eligible

View file

@ -20,5 +20,5 @@ Federation enables synchronized issue tracking across multiple workspaces,
each maintaining their own Dolt database while sharing updates via remotes.
```
bd federation
bd federation [flags]
```

View file

@ -19,5 +19,5 @@ Examples:
bd forget auth-jwt
```
bd forget <key>
bd forget <key> [flags]
```

View file

@ -26,7 +26,7 @@ Commands:
show Show formula details, steps, and composition rules
```
bd formula
bd formula [flags]
```
### bd formula convert
@ -105,5 +105,5 @@ Examples:
bd formula show security-audit --json
```
bd formula show <formula-name>
bd formula show <formula-name> [flags]
```

View file

@ -32,7 +32,7 @@ Examples:
bd gate resolve &lt;id&gt; # Close a gate manually
```
bd gate
bd gate [flags]
```
### bd gate add-waiter
@ -45,7 +45,7 @@ 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>
bd gate add-waiter <gate-id> <waiter> [flags]
```
### bd gate check
@ -203,5 +203,5 @@ 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>
bd gate show <gate-id> [flags]
```

View file

@ -20,7 +20,7 @@ Configuration can be set via 'bd config' or environment variables:
github.url / GITHUB_API_URL - Custom API URL (GitHub Enterprise)
```
bd github
bd github [flags]
```
### bd github pull
@ -62,7 +62,7 @@ bd github push [bead-ids...] [flags]
List GitHub repositories that the configured token has access to.
```
bd github repos
bd github repos [flags]
```
### bd github status
@ -70,7 +70,7 @@ bd github repos
Display current GitHub configuration and sync status.
```
bd github status
bd github status [flags]
```
### bd github sync

View file

@ -20,7 +20,7 @@ Configuration can be set via 'bd config' or environment variables:
gitlab.default_project_id / GITLAB_DEFAULT_PROJECT_ID - Project for creating issues in group mode
```
bd gitlab
bd gitlab [flags]
```
### bd gitlab projects
@ -28,7 +28,7 @@ bd gitlab
List GitLab projects that the configured token has access to.
```
bd gitlab projects
bd gitlab projects [flags]
```
### bd gitlab pull
@ -70,7 +70,7 @@ bd gitlab push [bead-ids...] [flags]
Display current GitLab configuration and sync status.
```
bd gitlab status
bd gitlab status [flags]
```
### bd gitlab sync

View file

@ -60,5 +60,5 @@ 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
bd graph check [flags]
```

View file

@ -20,7 +20,7 @@ The hooks provide:
- prepare-commit-msg: Add agent identity trailers for forensics
```
bd hooks
bd hooks [flags]
```
### bd hooks install
@ -60,7 +60,7 @@ bd hooks install [flags]
Show the status of bd git hooks (installed, outdated, missing).
```
bd hooks list
bd hooks list [flags]
```
### bd hooks run
@ -79,7 +79,7 @@ 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...]
bd hooks run <hook-name> [args...] [flags]
```
### bd hooks uninstall
@ -87,5 +87,5 @@ bd hooks run <hook-name> [args...]
Remove bd git hooks from .git/hooks/ directory.
```
bd hooks uninstall
bd hooks uninstall [flags]
```

View file

@ -24,7 +24,7 @@ SUBCOMMANDS:
human stats Show summary statistics for human-needed beads
```
bd human
bd human [flags]
```
### bd human dismiss
@ -99,5 +99,5 @@ Example:
bd human stats
```
bd human stats
bd human stats [flags]
```

View file

@ -7,7 +7,7 @@ sidebar_position: 0
# CLI Reference
<!-- AUTO-GENERATED: do not edit manually -->
Reference for bd Latest. Generated from `bd help --list` and `bd help --doc <command>`.
Reference for bd Latest. Generated from `bd help --docs-root`.
This reference covers all 107 live top-level `bd` commands. Regenerate it with:

View file

@ -79,5 +79,5 @@ RECOVERY
```
bd init-safety
bd init-safety [flags]
```

View file

@ -34,7 +34,7 @@ Examples:
bd jira status # Show sync status
```
bd jira
bd jira [flags]
```
### bd jira pull
@ -80,7 +80,7 @@ Show the current Jira sync status, including:
- Issues pending push (no external_ref)
```
bd jira status
bd jira status [flags]
```
### bd jira sync

View file

@ -22,7 +22,7 @@ Examples:
bd kv list # List all key-value pairs
```
bd kv
bd kv [flags]
```
### bd kv clear
@ -34,7 +34,7 @@ Examples:
bd kv clear api_endpoint
```
bd kv clear <key>
bd kv clear <key> [flags]
```
### bd kv get
@ -46,7 +46,7 @@ Examples:
bd kv get api_endpoint
```
bd kv get <key>
bd kv get <key> [flags]
```
### bd kv list
@ -58,7 +58,7 @@ Examples:
bd kv list --json
```
bd kv list
bd kv list [flags]
```
### bd kv set
@ -74,5 +74,5 @@ Examples:
bd kv set max_retries 3
```
bd kv set <key> <value>
bd kv set <key> <value> [flags]
```

View file

@ -13,7 +13,7 @@ Generated from `bd help --doc label`
Manage issue labels
```
bd label
bd label [flags]
```
### bd label add
@ -21,7 +21,7 @@ bd label
Add a label to one or more issues
```
bd label add [issue-id...] [label]
bd label add [issue-id...] [label] [flags]
```
### bd label list
@ -29,7 +29,7 @@ bd label add [issue-id...] [label]
List labels for an issue
```
bd label list [issue-id]
bd label list [issue-id] [flags]
```
### bd label list-all
@ -37,7 +37,7 @@ bd label list [issue-id]
List all unique labels in the database
```
bd label list-all
bd label list-all [flags]
```
### bd label propagate
@ -45,7 +45,7 @@ bd label list-all
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]
bd label propagate [parent-id] [label] [flags]
```
### bd label remove
@ -53,5 +53,5 @@ bd label propagate [parent-id] [label]
Remove a label from one or more issues
```
bd label remove [issue-id...] [label]
bd label remove [issue-id...] [label] [flags]
```

View file

@ -73,7 +73,7 @@ Examples:
bd linear status # Show sync status
```
bd linear
bd linear [flags]
```
### bd linear pull
@ -120,7 +120,7 @@ Show the current Linear sync status, including:
- Issues pending push (no external_ref)
```
bd linear status
bd linear status [flags]
```
### bd linear sync
@ -210,5 +210,5 @@ Example:
bd config set linear.team_id "12345678-1234-1234-1234-123456789abc"
```
bd linear teams
bd linear teams [flags]
```

View file

@ -32,5 +32,5 @@ Examples:
bd mail read msg-123 # Reads a message
```
bd mail [subcommand] [args...]
bd mail [subcommand] [args...] [flags]
```

View file

@ -18,5 +18,5 @@ Examples:
bd memories "race flag" # search for a phrase
```
bd memories [search]
bd memories [search] [flags]
```

View file

@ -30,7 +30,7 @@ Examples:
bd merge-slot release # Release the slot
```
bd merge-slot
bd merge-slot [flags]
```
### bd merge-slot acquire
@ -67,7 +67,7 @@ Returns:
- not found: no merge slot exists for this rig
```
bd merge-slot check
bd merge-slot check [flags]
```
### bd merge-slot create
@ -78,7 +78,7 @@ The slot ID is automatically generated based on the beads prefix (e.g., gt-merge
The slot is created with status=open (available).
```
bd merge-slot create
bd merge-slot create [flags]
```
### bd merge-slot release

View file

@ -34,7 +34,7 @@ Commands:
Use "bd formula list" to list available formulas.
```
bd mol
bd mol [flags]
```
**Aliases:** protomolecule
@ -233,7 +233,7 @@ Examples:
bd mol last-activity hq-wisp-0laki --json
```
bd mol last-activity <molecule-id>
bd mol last-activity <molecule-id> [flags]
```
### bd mol pour
@ -297,7 +297,7 @@ Example:
bd mol progress bd-hanoi-xyz
```
bd mol progress [molecule-id]
bd mol progress [molecule-id] [flags]
```
### bd mol ready
@ -318,7 +318,7 @@ Examples:
bd mol ready --gated --json # JSON output for automation
```
bd mol ready --gated
bd mol ready --gated [flags]
```
### bd mol seed

View file

@ -13,7 +13,7 @@ Generated from `bd help --doc notion`
Commands for syncing issues between beads and Notion.
```
bd notion
bd notion [flags]
```
### bd notion connect
@ -84,7 +84,7 @@ bd notion push [bead-ids...] [flags]
Show Notion sync status
```
bd notion status
bd notion status [flags]
```
### bd notion sync

View file

@ -27,5 +27,5 @@ 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
bd onboard [flags]
```

View file

@ -25,5 +25,5 @@ Examples:
bd ping --json # Structured output for automation
```
bd ping
bd ping [flags]
```

View file

@ -26,5 +26,5 @@ Examples:
bd priority bd-123 2 # Medium
```
bd priority <id> <n>
bd priority <id> <n> [flags]
```

View file

@ -13,5 +13,5 @@ Generated from `bd help --doc quickstart`
Display a quick start guide showing common bd workflows and patterns.
```
bd quickstart
bd quickstart [flags]
```

View file

@ -17,5 +17,5 @@ Examples:
bd recall auth-jwt
```
bd recall <key>
bd recall <key> [flags]
```

View file

@ -29,5 +29,5 @@ Examples:
bd recompute-blocked --json # Machine-parseable &#123;"rows_corrected": N&#125;
```
bd recompute-blocked
bd recompute-blocked [flags]
```

View file

@ -25,5 +25,5 @@ Examples:
Note: The new ID must use a valid prefix for this database.
```
bd rename <old-id> <new-id>
bd rename <old-id> <new-id> [flags]
```

View file

@ -31,7 +31,7 @@ Examples:
bd repo sync # Sync from all configured repos
```
bd repo
bd repo [flags]
```
### bd repo add

View file

@ -13,7 +13,7 @@ Generated from `bd help --doc rules`
Audit and compact Claude rules
```
bd rules
bd rules [flags]
```
### bd rules audit

View file

@ -25,7 +25,7 @@ Examples:
bd state witness-abc health # Output: healthy
```
bd state <issue-id> <dimension>
bd state <issue-id> <dimension> [flags]
```
### bd state list
@ -42,5 +42,5 @@ Example:
# health: healthy
```
bd state list <issue-id>
bd state list <issue-id> [flags]
```

View file

@ -31,5 +31,5 @@ Examples:
```
bd statuses
bd statuses [flags]
```

View file

@ -16,7 +16,7 @@ A swarm is a structured body of work defined by an epic and its children,
with dependencies forming a DAG (directed acyclic graph) of work.
```
bd swarm
bd swarm [flags]
```
### bd swarm create
@ -63,7 +63,7 @@ Examples:
bd swarm list --json # Machine-readable output
```
bd swarm list
bd swarm list [flags]
```
### bd swarm status
@ -89,7 +89,7 @@ Examples:
bd swarm status gt-epic-123 --json # Machine-readable output
```
bd swarm status [epic-or-swarm-id]
bd swarm status [epic-or-swarm-id] [flags]
```
### bd swarm validate

View file

@ -19,5 +19,5 @@ Examples:
bd tag bd-123 needs-review
```
bd tag <id> <label>
bd tag <id> <label> [flags]
```

View file

@ -21,7 +21,7 @@ TODOs can be promoted to full issues by changing type or priority:
bd update todo-123 --type bug --priority 0
```
bd todo
bd todo [flags]
```
### bd todo add

View file

@ -21,5 +21,5 @@ Examples:
```
bd types
bd types [flags]
```

View file

@ -20,5 +20,5 @@ Examples:
bd undefer bd-abc bd-def # Undefer multiple issues
```
bd undefer [id...]
bd undefer [id...] [flags]
```

View file

@ -20,7 +20,7 @@ The upgrade command helps you stay aware of bd version changes:
Version tracking is automatic - bd updates metadata.json on every run.
```
bd upgrade
bd upgrade [flags]
```
### bd upgrade ack
@ -39,7 +39,7 @@ Examples:
bd upgrade ack --json
```
bd upgrade ack
bd upgrade ack [flags]
```
### bd upgrade review
@ -57,7 +57,7 @@ Examples:
bd upgrade review --json
```
bd upgrade review
bd upgrade review [flags]
```
### bd upgrade status
@ -72,5 +72,5 @@ Examples:
bd upgrade status --json
```
bd upgrade status
bd upgrade status [flags]
```

View file

@ -19,7 +19,7 @@ Note: 'bd history', 'bd diff', and 'bd branch' also work for quick access.
This subcommand provides additional operations like merge and commit.
```
bd vc
bd vc [flags]
```
### bd vc commit
@ -72,5 +72,5 @@ Examples:
bd vc status
```
bd vc status
bd vc status [flags]
```

View file

@ -13,5 +13,5 @@ Generated from `bd help --doc version`
Print version information
```
bd version
bd version [flags]
```

View file

@ -21,5 +21,5 @@ Examples:
```
bd where
bd where [flags]
```

View file

@ -26,7 +26,7 @@ Examples:
bd worktree info # Show info about current worktree
```
bd worktree
bd worktree [flags]
```
### bd worktree create
@ -70,7 +70,7 @@ Examples:
bd worktree info --json # JSON output
```
bd worktree info
bd worktree info [flags]
```
### bd worktree list
@ -88,7 +88,7 @@ Examples:
bd worktree list --json # JSON output
```
bd worktree list
bd worktree list [flags]
```
### bd worktree remove