docs(emitter): emit Mintlify CLI reference and generated docs.json nav
bd help --docs-root now additionally writes docs/cli-reference/ in Mintlify form (frontmatter title as H1, extensionless root-relative links, JSX auto-generated markers since Mintlify parses .md through MDX) and rewrites the CLI Reference pages array inside docs/docs.json via a textual splice that leaves the rest of the file byte-identical — the ~113 nav entries are never hand-maintained. The Docusaurus outputs (docs/CLI_REFERENCE.md, website/docs/cli-reference/, versioned snapshots) are unchanged. generate-cli-docs.sh --check seeds docs/docs.json and docs/cli-reference/ into its scratch root and diffs both; check-cli-docs-drift.sh adds them to GEN_PATHSPECS and the regeneration fingerprint; docs-autofix-push.sh allowlists the new generated paths; check-doc-flags.sh scans the new docs/ subdirectories and requires command coverage in docs/cli-reference/. Includes the initial docs/docs.json scaffold (nav mirrors the Docusaurus sidebar IA) and the generated docs/cli-reference/ pages. TDD: new emitter behavior covered in cmd/bd/help_all_test.go (Mintlify page format, nav splice correctness + idempotence, bare-root generation without docs.json).
This commit is contained in:
parent
a86a2c5dfc
commit
4ea6fa3ac0
120 changed files with 8223 additions and 29 deletions
|
|
@ -182,6 +182,31 @@ func writeCommandHelp(w io.Writer, cmd *cobra.Command, parentPath string, depth
|
|||
|
||||
fmt.Fprintf(w, "%s %s\n\n", heading, fullPath)
|
||||
|
||||
writeCommandBody(w, cmd)
|
||||
|
||||
// Subcommands
|
||||
subCmds := cmd.Commands()
|
||||
hasVisibleSubs := false
|
||||
for _, sub := range subCmds {
|
||||
if sub.IsAvailableCommand() {
|
||||
hasVisibleSubs = true
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
if hasVisibleSubs {
|
||||
for _, sub := range subCmds {
|
||||
if !sub.IsAvailableCommand() {
|
||||
continue
|
||||
}
|
||||
writeCommandHelp(w, sub, fullPath, depth+1)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// writeCommandBody writes the heading-independent parts of a command's help:
|
||||
// description, usage, aliases, examples, and local flags.
|
||||
func writeCommandBody(w io.Writer, cmd *cobra.Command) {
|
||||
// Description
|
||||
if cmd.Long != "" {
|
||||
fmt.Fprintf(w, "%s\n\n", escapeMDXText(cmd.Long))
|
||||
|
|
@ -207,25 +232,6 @@ func writeCommandHelp(w io.Writer, cmd *cobra.Command, parentPath string, depth
|
|||
if localFlags.HasFlags() {
|
||||
fmt.Fprintf(w, "**Flags:**\n\n```\n%s```\n\n", localFlags.FlagUsages())
|
||||
}
|
||||
|
||||
// Subcommands
|
||||
subCmds := cmd.Commands()
|
||||
hasVisibleSubs := false
|
||||
for _, sub := range subCmds {
|
||||
if sub.IsAvailableCommand() {
|
||||
hasVisibleSubs = true
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
if hasVisibleSubs {
|
||||
for _, sub := range subCmds {
|
||||
if !sub.IsAvailableCommand() {
|
||||
continue
|
||||
}
|
||||
writeCommandHelp(w, sub, fullPath, depth+1)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// sidebarPositionMap maps command names to their Docusaurus sidebar position
|
||||
|
|
@ -308,6 +314,25 @@ func writeGeneratedCLIDocs(root *cobra.Command, repoRoot, docsVersion string) er
|
|||
return err
|
||||
}
|
||||
|
||||
if err := writeMintlifyCLIReferenceDir(filepath.Join(repoRoot, "docs", "cli-reference"), root); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// The Mintlify site's navigation lists every CLI page explicitly; those
|
||||
// entries are generated here, never hand-maintained. Roots without a
|
||||
// docs.json (bare output roots, --check scratch dirs before the copy)
|
||||
// simply get the pages.
|
||||
docsJSONPath := filepath.Join(repoRoot, "docs", "docs.json")
|
||||
if _, err := os.Stat(docsJSONPath); err == nil {
|
||||
navPages := []string{"cli-reference/index"}
|
||||
for _, name := range availableCommandNames(root) {
|
||||
navPages = append(navPages, "cli-reference/"+commandDocID(name))
|
||||
}
|
||||
if err := updateMintlifyCLINav(docsJSONPath, navPages); 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 {
|
||||
|
|
@ -318,6 +343,158 @@ func writeGeneratedCLIDocs(root *cobra.Command, repoRoot, docsVersion string) er
|
|||
return nil
|
||||
}
|
||||
|
||||
// writeMintlifyCLIReferenceDir emits the Mintlify-form CLI reference under
|
||||
// docs/cli-reference/: frontmatter title is the H1 (no body H1), links are
|
||||
// root-relative and extensionless, and the auto-generated marker is a JSX
|
||||
// comment because Mintlify parses .md through MDX (HTML comments break it).
|
||||
func writeMintlifyCLIReferenceDir(outDir string, root *cobra.Command) 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"), mintlifyCLIReferenceIndex(commands)); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
for _, name := range commands {
|
||||
var out bytes.Buffer
|
||||
if err := writeMintlifySingleCommandDoc(&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
|
||||
}
|
||||
|
||||
// writeMintlifySingleCommandDoc renders one command as a Mintlify page. The
|
||||
// frontmatter title renders as the page H1, so the top command emits its body
|
||||
// without its own heading; subcommands start at ##.
|
||||
func writeMintlifySingleCommandDoc(w io.Writer, root *cobra.Command, cmdName string) error {
|
||||
cmd := findCommand(root, cmdName)
|
||||
if cmd == nil {
|
||||
return fmt.Errorf("Error: command not found: %s", cmdName)
|
||||
}
|
||||
|
||||
docCommand := strings.TrimSpace(strings.TrimPrefix(commandPath(cmd), root.Name()))
|
||||
if docCommand == "" {
|
||||
return errors.New("Error: cannot generate docs for root command")
|
||||
}
|
||||
|
||||
fmt.Fprintf(w, "---\n")
|
||||
fmt.Fprintf(w, "title: %q\n", "bd "+docCommand)
|
||||
if cmd.Short != "" {
|
||||
fmt.Fprintf(w, "description: %q\n", cmd.Short)
|
||||
}
|
||||
fmt.Fprintf(w, "---\n\n")
|
||||
fmt.Fprintf(w, "{/* AUTO-GENERATED: do not edit manually */}\n\n")
|
||||
fmt.Fprintf(w, "Generated from `bd help --doc %s`.\n\n", docCommand)
|
||||
|
||||
writeCommandBody(w, cmd)
|
||||
|
||||
fullPath := commandPath(cmd)
|
||||
for _, sub := range cmd.Commands() {
|
||||
if !sub.IsAvailableCommand() {
|
||||
continue
|
||||
}
|
||||
writeCommandHelp(w, sub, fullPath, 2)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func mintlifyCLIReferenceIndex(commands []string) string {
|
||||
var b strings.Builder
|
||||
fmt.Fprintf(&b, "---\n")
|
||||
fmt.Fprintf(&b, "title: CLI Reference\n")
|
||||
fmt.Fprintf(&b, "description: Generated reference for every bd command\n")
|
||||
fmt.Fprintf(&b, "---\n\n")
|
||||
fmt.Fprintf(&b, "{/* AUTO-GENERATED: do not edit manually */}\n\n")
|
||||
fmt.Fprintf(&b, "Generated from `bd help --docs-root`.\n\n")
|
||||
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`](/cli-reference/%s)\n", cmd, commandDocID(cmd))
|
||||
}
|
||||
return b.String()
|
||||
}
|
||||
|
||||
// updateMintlifyCLINav rewrites the "pages" array of the "CLI Reference"
|
||||
// navigation group in docs.json, leaving every other byte of the file
|
||||
// untouched. A textual splice (rather than a JSON round-trip) preserves key
|
||||
// order and formatting so regeneration is diff-stable. The pages entries are
|
||||
// plain slugs, so bracket matching cannot be confused by string contents.
|
||||
func updateMintlifyCLINav(docsJSONPath string, pages []string) error {
|
||||
data, err := os.ReadFile(docsJSONPath)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
s := string(data)
|
||||
|
||||
groupIdx := strings.Index(s, `"group": "CLI Reference"`)
|
||||
if groupIdx < 0 {
|
||||
return fmt.Errorf("%s: no \"CLI Reference\" navigation group found", docsJSONPath)
|
||||
}
|
||||
pagesIdx := strings.Index(s[groupIdx:], `"pages"`)
|
||||
if pagesIdx < 0 {
|
||||
return fmt.Errorf("%s: \"CLI Reference\" group has no \"pages\" key", docsJSONPath)
|
||||
}
|
||||
pagesIdx += groupIdx
|
||||
openIdx := strings.Index(s[pagesIdx:], "[")
|
||||
if openIdx < 0 {
|
||||
return fmt.Errorf("%s: \"CLI Reference\" pages key has no array", docsJSONPath)
|
||||
}
|
||||
openIdx += pagesIdx
|
||||
|
||||
depth := 0
|
||||
closeIdx := -1
|
||||
for i := openIdx; i < len(s); i++ {
|
||||
switch s[i] {
|
||||
case '[':
|
||||
depth++
|
||||
case ']':
|
||||
depth--
|
||||
if depth == 0 {
|
||||
closeIdx = i
|
||||
}
|
||||
}
|
||||
if closeIdx >= 0 {
|
||||
break
|
||||
}
|
||||
}
|
||||
if closeIdx < 0 {
|
||||
return fmt.Errorf("%s: unbalanced \"pages\" array in \"CLI Reference\" group", docsJSONPath)
|
||||
}
|
||||
|
||||
lineStart := strings.LastIndex(s[:pagesIdx], "\n") + 1
|
||||
indent := s[lineStart:pagesIdx]
|
||||
entryIndent := indent + " "
|
||||
|
||||
var b strings.Builder
|
||||
b.WriteString("[\n")
|
||||
for i, p := range pages {
|
||||
fmt.Fprintf(&b, "%s%q", entryIndent, p)
|
||||
if i < len(pages)-1 {
|
||||
b.WriteString(",")
|
||||
}
|
||||
b.WriteString("\n")
|
||||
}
|
||||
b.WriteString(indent + "]")
|
||||
|
||||
out := s[:openIdx] + b.String() + s[closeIdx+1:]
|
||||
// #nosec G306: docs.json is repository source, readable like other source files.
|
||||
return os.WriteFile(docsJSONPath, []byte(out), 0o644)
|
||||
}
|
||||
|
||||
func writeCLIReferenceDir(outDir string, root *cobra.Command, versionLabel string) error {
|
||||
if err := os.MkdirAll(outDir, 0o755); err != nil {
|
||||
return err
|
||||
|
|
|
|||
|
|
@ -2,6 +2,7 @@ package main
|
|||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
|
|
@ -205,6 +206,171 @@ func TestWriteGeneratedCLIDocsDoesNotTouchVersionedDocsWithoutVersion(t *testing
|
|||
assertFileContains(t, sentinel, "keep me")
|
||||
}
|
||||
|
||||
func TestWriteGeneratedCLIDocsWritesMintlifyCLIReference(t *testing.T) {
|
||||
root := &cobra.Command{Use: "bd"}
|
||||
mol := testHelpCmd("mol", "Molecule commands")
|
||||
mol.AddCommand(testHelpCmd("pour <formula>", "Start a workflow"))
|
||||
root.AddCommand(
|
||||
testHelpCmd("show <id>", "Show an issue"),
|
||||
mol,
|
||||
)
|
||||
dir := t.TempDir()
|
||||
|
||||
if err := writeGeneratedCLIDocs(root, dir, ""); err != nil {
|
||||
t.Fatalf("writeGeneratedCLIDocs() error = %v", err)
|
||||
}
|
||||
|
||||
// Index page: Mintlify frontmatter, no body H1, extensionless links.
|
||||
indexPath := filepath.Join(dir, "docs", "cli-reference", "index.md")
|
||||
assertFileContains(t, indexPath, "title: CLI Reference")
|
||||
assertFileContains(t, indexPath, "](/cli-reference/show)")
|
||||
index, err := os.ReadFile(indexPath)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for _, banned := range []string{"\n# ", "<!--", "sidebar_position", "](./"} {
|
||||
if strings.Contains(string(index), banned) {
|
||||
t.Errorf("Mintlify index.md contains banned %q:\n%s", banned, index)
|
||||
}
|
||||
}
|
||||
|
||||
// Command page: Mintlify frontmatter, no Docusaurus keys, JSX comment marker.
|
||||
showPath := filepath.Join(dir, "docs", "cli-reference", "show.md")
|
||||
assertFileContains(t, showPath, "title: \"bd show\"")
|
||||
assertFileContains(t, showPath, "description: \"Show an issue\"")
|
||||
assertFileContains(t, showPath, "{/* AUTO-GENERATED: do not edit manually */}")
|
||||
assertFileContains(t, showPath, "bd show <id>")
|
||||
show, err := os.ReadFile(showPath)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for _, banned := range []string{"id: show", "slug:", "sidebar_position", "<!--", "\n# "} {
|
||||
if strings.Contains(string(show), banned) {
|
||||
t.Errorf("Mintlify show.md contains banned %q:\n%s", banned, show)
|
||||
}
|
||||
}
|
||||
|
||||
// Nested command page exists with the full command path.
|
||||
molPath := filepath.Join(dir, "docs", "cli-reference", "mol.md")
|
||||
assertFileContains(t, molPath, "## bd mol pour")
|
||||
}
|
||||
|
||||
func TestUpdateMintlifyCLINavReplacesOnlyCLIReferencePages(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
docsJSON := filepath.Join(dir, "docs.json")
|
||||
original := `{
|
||||
"$schema": "https://mintlify.com/docs.json",
|
||||
"name": "Beads Documentation",
|
||||
"navigation": {
|
||||
"groups": [
|
||||
{
|
||||
"group": "Getting Started",
|
||||
"pages": [
|
||||
"index",
|
||||
"getting-started/installation"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "CLI Reference",
|
||||
"pages": [
|
||||
"cli-reference/index",
|
||||
"cli-reference/stale-command"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Reference",
|
||||
"pages": [
|
||||
"reference/faq"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
`
|
||||
if err := os.WriteFile(docsJSON, []byte(original), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
if err := updateMintlifyCLINav(docsJSON, []string{"cli-reference/index", "cli-reference/create", "cli-reference/show"}); err != nil {
|
||||
t.Fatalf("updateMintlifyCLINav() error = %v", err)
|
||||
}
|
||||
|
||||
data, err := os.ReadFile(docsJSON)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
got := string(data)
|
||||
|
||||
for _, want := range []string{
|
||||
`"cli-reference/create"`,
|
||||
`"cli-reference/show"`,
|
||||
`"getting-started/installation"`,
|
||||
`"reference/faq"`,
|
||||
} {
|
||||
if !strings.Contains(got, want) {
|
||||
t.Errorf("updated docs.json missing %q:\n%s", want, got)
|
||||
}
|
||||
}
|
||||
if strings.Contains(got, "stale-command") {
|
||||
t.Errorf("updated docs.json still lists stale CLI page:\n%s", got)
|
||||
}
|
||||
|
||||
// The rewrite must remain valid JSON and preserve the other groups' pages.
|
||||
var decoded map[string]any
|
||||
if err := json.Unmarshal(data, &decoded); err != nil {
|
||||
t.Fatalf("updated docs.json is not valid JSON: %v\n%s", err, got)
|
||||
}
|
||||
|
||||
// Idempotent: running again must not change the file.
|
||||
if err := updateMintlifyCLINav(docsJSON, []string{"cli-reference/index", "cli-reference/create", "cli-reference/show"}); err != nil {
|
||||
t.Fatalf("updateMintlifyCLINav() second run error = %v", err)
|
||||
}
|
||||
again, err := os.ReadFile(docsJSON)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !bytes.Equal(data, again) {
|
||||
t.Errorf("updateMintlifyCLINav is not idempotent:\nfirst:\n%s\nsecond:\n%s", data, again)
|
||||
}
|
||||
}
|
||||
|
||||
func TestWriteGeneratedCLIDocsUpdatesMintlifyNavWhenPresent(t *testing.T) {
|
||||
root := &cobra.Command{Use: "bd"}
|
||||
root.AddCommand(
|
||||
testHelpCmd("show <id>", "Show an issue"),
|
||||
testHelpCmd("create", "Create an issue"),
|
||||
)
|
||||
dir := t.TempDir()
|
||||
docsDir := filepath.Join(dir, "docs")
|
||||
if err := os.MkdirAll(docsDir, 0o755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
docsJSON := filepath.Join(docsDir, "docs.json")
|
||||
seed := `{
|
||||
"navigation": {
|
||||
"groups": [
|
||||
{
|
||||
"group": "CLI Reference",
|
||||
"pages": [
|
||||
"cli-reference/index"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
`
|
||||
if err := os.WriteFile(docsJSON, []byte(seed), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
if err := writeGeneratedCLIDocs(root, dir, ""); err != nil {
|
||||
t.Fatalf("writeGeneratedCLIDocs() error = %v", err)
|
||||
}
|
||||
|
||||
assertFileContains(t, docsJSON, `"cli-reference/create"`)
|
||||
assertFileContains(t, docsJSON, `"cli-reference/show"`)
|
||||
}
|
||||
|
||||
func assertFileContains(t *testing.T, path, want string) {
|
||||
t.Helper()
|
||||
data, err := os.ReadFile(path)
|
||||
|
|
|
|||
158
docs/cli-reference/admin.md
Normal file
158
docs/cli-reference/admin.md
Normal file
|
|
@ -0,0 +1,158 @@
|
|||
---
|
||||
title: "bd admin"
|
||||
description: "Administrative commands for database maintenance"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc admin`.
|
||||
|
||||
Administrative commands for beads database maintenance.
|
||||
|
||||
These commands are for advanced users and should be used carefully:
|
||||
cleanup Delete closed issues (issue lifecycle)
|
||||
compact Compact old closed issues to save space (storage optimization)
|
||||
reset Remove all beads data and configuration (full reset)
|
||||
|
||||
For routine maintenance, prefer 'bd doctor --fix' which handles common repairs
|
||||
automatically. Use these admin commands for targeted database operations.
|
||||
|
||||
```
|
||||
bd admin [flags]
|
||||
```
|
||||
|
||||
## bd admin cleanup
|
||||
|
||||
Delete closed issues to reduce database size.
|
||||
|
||||
This command permanently removes closed issues from the database.
|
||||
|
||||
NOTE: This command only manages issue lifecycle (closed -> deleted). For general
|
||||
health checks and automatic repairs, use 'bd doctor --fix' instead.
|
||||
|
||||
By default, deletes ALL closed issues. Use --older-than to only delete
|
||||
issues closed before a certain date.
|
||||
|
||||
EXAMPLES:
|
||||
bd admin cleanup --force # Delete all closed issues
|
||||
bd admin cleanup --older-than 30 --force # Only issues closed 30+ days ago
|
||||
bd admin cleanup --ephemeral --force # Only closed wisps (transient molecules)
|
||||
bd admin cleanup --dry-run # Preview what would be deleted
|
||||
|
||||
SAFETY:
|
||||
- Requires --force flag to actually delete (unless --dry-run)
|
||||
- Supports --cascade to delete dependents
|
||||
- Shows preview of what will be deleted
|
||||
- Use --json for programmatic output
|
||||
|
||||
SEE ALSO:
|
||||
bd doctor --fix Automatic health checks and repairs (recommended for routine maintenance)
|
||||
bd admin compact Compact old closed issues to save space
|
||||
|
||||
```
|
||||
bd admin cleanup [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--cascade Recursively delete all dependent issues
|
||||
--dry-run Preview what would be deleted without making changes
|
||||
--ephemeral Only delete closed wisps (transient molecules)
|
||||
-f, --force Actually delete (without this flag, shows error)
|
||||
--older-than int Only delete issues closed more than N days ago (0 = all closed issues)
|
||||
```
|
||||
|
||||
## bd admin compact
|
||||
|
||||
Compact old closed issues using semantic summarization.
|
||||
|
||||
Compaction reduces database size by summarizing closed issues that are no longer
|
||||
actively referenced. This is permanent graceful decay - original content is discarded.
|
||||
|
||||
Modes:
|
||||
- Analyze: Export candidates for agent review (no API key needed)
|
||||
- Apply: Accept agent-provided summary (no API key needed)
|
||||
- Auto: AI-powered compaction (requires ANTHROPIC_API_KEY or ai.api_key, legacy)
|
||||
- Dolt: Run Dolt garbage collection (for Dolt-backend repositories)
|
||||
|
||||
Tiers:
|
||||
- Tier 1: Semantic compression (30 days closed, 70% reduction)
|
||||
- Tier 2: Ultra compression (90 days closed) - planned, not yet implemented
|
||||
|
||||
Dolt Garbage Collection:
|
||||
With auto-commit per mutation, Dolt commit history grows over time. Use
|
||||
--dolt to run Dolt garbage collection and reclaim disk space.
|
||||
|
||||
--dolt: Run Dolt GC on .beads/dolt directory to free disk space.
|
||||
This removes unreachable commits and compacts storage.
|
||||
|
||||
Examples:
|
||||
# Dolt garbage collection
|
||||
bd compact --dolt # Run Dolt GC
|
||||
bd compact --dolt --dry-run # Preview without running GC
|
||||
|
||||
# Agent-driven workflow (recommended)
|
||||
bd compact --analyze --json # Get candidates with full content
|
||||
bd compact --apply --id bd-42 --summary summary.txt
|
||||
bd compact --apply --id bd-42 --summary - < summary.txt
|
||||
|
||||
# Legacy AI-powered workflow
|
||||
bd compact --auto --dry-run # Preview candidates
|
||||
bd compact --auto --all # Compact all eligible issues
|
||||
bd compact --auto --id bd-42 # Compact specific issue
|
||||
|
||||
# Statistics
|
||||
bd compact --stats # Show statistics
|
||||
|
||||
|
||||
```
|
||||
bd admin compact [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--actor string Actor name for audit trail (default "agent")
|
||||
--all Process all candidates
|
||||
--analyze Analyze mode: export candidates for agent review
|
||||
--apply Apply mode: accept agent-provided summary
|
||||
--auto Auto mode: AI-powered compaction (legacy)
|
||||
--batch-size int Issues per batch (default 10)
|
||||
--dolt Dolt mode: run Dolt garbage collection on .beads/dolt
|
||||
--dry-run Preview without compacting
|
||||
--force Force compact (bypass checks, requires --id)
|
||||
--id string Compact specific issue
|
||||
--json Output JSON format
|
||||
--limit int Limit number of candidates (0 = no limit)
|
||||
--stats Show compaction statistics
|
||||
--summary string Path to summary file (use '-' for stdin)
|
||||
--tier int Compaction tier (only tier 1 is implemented) (default 1)
|
||||
--workers int Parallel workers (default 5)
|
||||
```
|
||||
|
||||
## bd admin reset
|
||||
|
||||
Reset beads to an uninitialized state, removing all local data.
|
||||
|
||||
This command removes:
|
||||
- The .beads directory (database, JSONL, config)
|
||||
- Git hooks installed by bd
|
||||
- Sync branch worktrees
|
||||
|
||||
By default, shows what would be deleted (dry-run mode).
|
||||
Use --force to actually perform the reset.
|
||||
|
||||
Examples:
|
||||
bd reset # Show what would be deleted
|
||||
bd reset --force # Actually delete everything
|
||||
|
||||
```
|
||||
bd admin reset [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--force Actually perform the reset (required)
|
||||
```
|
||||
115
docs/cli-reference/ado.md
Normal file
115
docs/cli-reference/ado.md
Normal file
|
|
@ -0,0 +1,115 @@
|
|||
---
|
||||
title: "bd ado"
|
||||
description: "Azure DevOps integration commands"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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")
|
||||
```
|
||||
20
docs/cli-reference/assign.md
Normal file
20
docs/cli-reference/assign.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
title: "bd assign"
|
||||
description: "Assign an issue to someone"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
57
docs/cli-reference/audit.md
Normal file
57
docs/cli-reference/audit.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
---
|
||||
title: "bd audit"
|
||||
description: "Record and label agent interactions (append-only JSONL)"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc audit`.
|
||||
|
||||
Audit log entries are appended to .beads/interactions.jsonl.
|
||||
|
||||
Each line is one event. This file is intended to be versioned in git and used for:
|
||||
- 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)
|
||||
```
|
||||
115
docs/cli-reference/backup.md
Normal file
115
docs/cli-reference/backup.md
Normal file
|
|
@ -0,0 +1,115 @@
|
|||
---
|
||||
title: "bd backup"
|
||||
description: "Back up your beads database"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
62
docs/cli-reference/batch.md
Normal file
62
docs/cli-reference/batch.md
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
---
|
||||
title: "bd batch"
|
||||
description: "Run multiple write operations in a single database transaction"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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>')
|
||||
```
|
||||
20
docs/cli-reference/blocked.md
Normal file
20
docs/cli-reference/blocked.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
title: "bd blocked"
|
||||
description: "Show blocked issues"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc blocked`.
|
||||
|
||||
Show blocked issues
|
||||
|
||||
```
|
||||
bd blocked [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--parent string Filter to descendants of this bead/epic
|
||||
```
|
||||
47
docs/cli-reference/bootstrap.md
Normal file
47
docs/cli-reference/bootstrap.md
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
---
|
||||
title: "bd bootstrap"
|
||||
description: "Non-destructive database setup for fresh clones and recovery"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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)
|
||||
```
|
||||
21
docs/cli-reference/branch.md
Normal file
21
docs/cli-reference/branch.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
---
|
||||
title: "bd branch"
|
||||
description: "List or create branches"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
29
docs/cli-reference/children.md
Normal file
29
docs/cli-reference/children.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
---
|
||||
title: "bd children"
|
||||
description: "List child beads of a parent"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
37
docs/cli-reference/close.md
Normal file
37
docs/cli-reference/close.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
title: "bd close"
|
||||
description: "Close one or more issues"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
29
docs/cli-reference/comment.md
Normal file
29
docs/cli-reference/comment.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
---
|
||||
title: "bd comment"
|
||||
description: "Add a comment to an issue"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
63
docs/cli-reference/comments.md
Normal file
63
docs/cli-reference/comments.md
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
title: "bd comments"
|
||||
description: "View or manage comments on an issue"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
42
docs/cli-reference/compact.md
Normal file
42
docs/cli-reference/compact.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
title: "bd compact"
|
||||
description: "Squash old Dolt commits to reduce history size"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
133
docs/cli-reference/completion.md
Normal file
133
docs/cli-reference/completion.md
Normal file
|
|
@ -0,0 +1,133 @@
|
|||
---
|
||||
title: "bd completion"
|
||||
description: "Generate the autocompletion script for the specified shell"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
243
docs/cli-reference/config.md
Normal file
243
docs/cli-reference/config.md
Normal file
|
|
@ -0,0 +1,243 @@
|
|||
---
|
||||
title: "bd config"
|
||||
description: "Manage configuration settings"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
23
docs/cli-reference/context.md
Normal file
23
docs/cli-reference/context.md
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
---
|
||||
title: "bd context"
|
||||
description: "Show effective backend identity and repository context"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
72
docs/cli-reference/cook.md
Normal file
72
docs/cli-reference/cook.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
---
|
||||
title: "bd cook"
|
||||
description: "Compile a formula into a proto (ephemeral by default)"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
62
docs/cli-reference/count.md
Normal file
62
docs/cli-reference/count.md
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
---
|
||||
title: "bd count"
|
||||
description: "Count issues matching filters"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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)
|
||||
```
|
||||
32
docs/cli-reference/create-form.md
Normal file
32
docs/cli-reference/create-form.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
title: "bd create-form"
|
||||
description: "Create a new issue using an interactive form"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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')
|
||||
```
|
||||
64
docs/cli-reference/create.md
Normal file
64
docs/cli-reference/create.md
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
---
|
||||
title: "bd create"
|
||||
description: "Create a new issue (or batch from markdown/graph JSON)"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
34
docs/cli-reference/defer.md
Normal file
34
docs/cli-reference/defer.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
title: "bd defer"
|
||||
description: "Defer one or more issues for later"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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)
|
||||
```
|
||||
49
docs/cli-reference/delete.md
Normal file
49
docs/cli-reference/delete.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
title: "bd delete"
|
||||
description: "Delete one or more issues and clean up references"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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)
|
||||
```
|
||||
183
docs/cli-reference/dep.md
Normal file
183
docs/cli-reference/dep.md
Normal file
|
|
@ -0,0 +1,183 @@
|
|||
---
|
||||
title: "bd dep"
|
||||
description: "Manage dependencies"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
24
docs/cli-reference/diff.md
Normal file
24
docs/cli-reference/diff.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
title: "bd diff"
|
||||
description: "Show changes between two commits or branches"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
150
docs/cli-reference/doctor.md
Normal file
150
docs/cli-reference/doctor.md
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
---
|
||||
title: "bd doctor"
|
||||
description: "Check and fix beads installation health (start here)"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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)
|
||||
```
|
||||
301
docs/cli-reference/dolt.md
Normal file
301
docs/cli-reference/dolt.md
Normal file
|
|
@ -0,0 +1,301 @@
|
|||
---
|
||||
title: "bd dolt"
|
||||
description: "Configure Dolt database settings"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
26
docs/cli-reference/duplicate.md
Normal file
26
docs/cli-reference/duplicate.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
title: "bd duplicate"
|
||||
description: "Mark an issue as a duplicate of another"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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)
|
||||
```
|
||||
30
docs/cli-reference/duplicates.md
Normal file
30
docs/cli-reference/duplicates.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
title: "bd duplicates"
|
||||
description: "Find and optionally merge duplicate issues"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
33
docs/cli-reference/edit.md
Normal file
33
docs/cli-reference/edit.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
title: "bd edit"
|
||||
description: "Edit an issue field in $EDITOR"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
42
docs/cli-reference/epic.md
Normal file
42
docs/cli-reference/epic.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
title: "bd epic"
|
||||
description: "Epic management commands"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
49
docs/cli-reference/export.md
Normal file
49
docs/cli-reference/export.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
title: "bd export"
|
||||
description: "Export issues to JSONL format"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
21
docs/cli-reference/federation.md
Normal file
21
docs/cli-reference/federation.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
---
|
||||
title: "bd federation"
|
||||
description: "Manage peer-to-peer federation (requires CGO)"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
50
docs/cli-reference/find-duplicates.md
Normal file
50
docs/cli-reference/find-duplicates.md
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
---
|
||||
title: "bd find-duplicates"
|
||||
description: "Find semantically similar issues using text analysis or AI"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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)
|
||||
```
|
||||
41
docs/cli-reference/flatten.md
Normal file
41
docs/cli-reference/flatten.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
title: "bd flatten"
|
||||
description: "Squash all Dolt history into a single commit"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
20
docs/cli-reference/forget.md
Normal file
20
docs/cli-reference/forget.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
title: "bd forget"
|
||||
description: "Remove a persistent memory"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
144
docs/cli-reference/formula.md
Normal file
144
docs/cli-reference/formula.md
Normal file
|
|
@ -0,0 +1,144 @@
|
|||
---
|
||||
title: "bd formula"
|
||||
description: "Manage workflow formulas"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
204
docs/cli-reference/gate.md
Normal file
204
docs/cli-reference/gate.md
Normal file
|
|
@ -0,0 +1,204 @@
|
|||
---
|
||||
title: "bd gate"
|
||||
description: "Manage async coordination gates"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
40
docs/cli-reference/gc.md
Normal file
40
docs/cli-reference/gc.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
title: "bd gc"
|
||||
description: "Garbage collect: decay old issues, compact Dolt commits, run Dolt GC"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
98
docs/cli-reference/github.md
Normal file
98
docs/cli-reference/github.md
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
---
|
||||
title: "bd github"
|
||||
description: "GitHub integration commands"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
105
docs/cli-reference/gitlab.md
Normal file
105
docs/cli-reference/gitlab.md
Normal file
|
|
@ -0,0 +1,105 @@
|
|||
---
|
||||
title: "bd gitlab"
|
||||
description: "GitLab integration commands"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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')
|
||||
```
|
||||
61
docs/cli-reference/graph.md
Normal file
61
docs/cli-reference/graph.md
Normal file
|
|
@ -0,0 +1,61 @@
|
|||
---
|
||||
title: "bd graph"
|
||||
description: "Display issue dependency graph"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
31
docs/cli-reference/heartbeat.md
Normal file
31
docs/cli-reference/heartbeat.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
---
|
||||
title: "bd heartbeat"
|
||||
description: "Refresh the lease on an issue you hold in_progress"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
25
docs/cli-reference/history.md
Normal file
25
docs/cli-reference/history.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
---
|
||||
title: "bd history"
|
||||
description: "Show version history for an issue"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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 <id> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--limit int Limit number of history entries (0 = all)
|
||||
```
|
||||
88
docs/cli-reference/hooks.md
Normal file
88
docs/cli-reference/hooks.md
Normal file
|
|
@ -0,0 +1,88 @@
|
|||
---
|
||||
title: "bd hooks"
|
||||
description: "Manage git hooks for beads integration"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
100
docs/cli-reference/human.md
Normal file
100
docs/cli-reference/human.md
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
---
|
||||
title: "bd human"
|
||||
description: "Show essential commands for human users"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
84
docs/cli-reference/import.md
Normal file
84
docs/cli-reference/import.md
Normal file
|
|
@ -0,0 +1,84 @@
|
|||
---
|
||||
title: "bd import"
|
||||
description: "Import issues from a JSONL file or stdin into the database"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
129
docs/cli-reference/index.md
Normal file
129
docs/cli-reference/index.md
Normal file
|
|
@ -0,0 +1,129 @@
|
|||
---
|
||||
title: CLI Reference
|
||||
description: Generated reference for every bd command
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
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`](/cli-reference/admin)
|
||||
- [`bd ado`](/cli-reference/ado)
|
||||
- [`bd assign`](/cli-reference/assign)
|
||||
- [`bd audit`](/cli-reference/audit)
|
||||
- [`bd backup`](/cli-reference/backup)
|
||||
- [`bd batch`](/cli-reference/batch)
|
||||
- [`bd blocked`](/cli-reference/blocked)
|
||||
- [`bd bootstrap`](/cli-reference/bootstrap)
|
||||
- [`bd branch`](/cli-reference/branch)
|
||||
- [`bd children`](/cli-reference/children)
|
||||
- [`bd close`](/cli-reference/close)
|
||||
- [`bd comment`](/cli-reference/comment)
|
||||
- [`bd comments`](/cli-reference/comments)
|
||||
- [`bd compact`](/cli-reference/compact)
|
||||
- [`bd completion`](/cli-reference/completion)
|
||||
- [`bd config`](/cli-reference/config)
|
||||
- [`bd context`](/cli-reference/context)
|
||||
- [`bd cook`](/cli-reference/cook)
|
||||
- [`bd count`](/cli-reference/count)
|
||||
- [`bd create`](/cli-reference/create)
|
||||
- [`bd create-form`](/cli-reference/create-form)
|
||||
- [`bd defer`](/cli-reference/defer)
|
||||
- [`bd delete`](/cli-reference/delete)
|
||||
- [`bd dep`](/cli-reference/dep)
|
||||
- [`bd diff`](/cli-reference/diff)
|
||||
- [`bd doctor`](/cli-reference/doctor)
|
||||
- [`bd dolt`](/cli-reference/dolt)
|
||||
- [`bd duplicate`](/cli-reference/duplicate)
|
||||
- [`bd duplicates`](/cli-reference/duplicates)
|
||||
- [`bd edit`](/cli-reference/edit)
|
||||
- [`bd epic`](/cli-reference/epic)
|
||||
- [`bd export`](/cli-reference/export)
|
||||
- [`bd federation`](/cli-reference/federation)
|
||||
- [`bd find-duplicates`](/cli-reference/find-duplicates)
|
||||
- [`bd flatten`](/cli-reference/flatten)
|
||||
- [`bd forget`](/cli-reference/forget)
|
||||
- [`bd formula`](/cli-reference/formula)
|
||||
- [`bd gate`](/cli-reference/gate)
|
||||
- [`bd gc`](/cli-reference/gc)
|
||||
- [`bd github`](/cli-reference/github)
|
||||
- [`bd gitlab`](/cli-reference/gitlab)
|
||||
- [`bd graph`](/cli-reference/graph)
|
||||
- [`bd heartbeat`](/cli-reference/heartbeat)
|
||||
- [`bd history`](/cli-reference/history)
|
||||
- [`bd hooks`](/cli-reference/hooks)
|
||||
- [`bd human`](/cli-reference/human)
|
||||
- [`bd import`](/cli-reference/import)
|
||||
- [`bd info`](/cli-reference/info)
|
||||
- [`bd init`](/cli-reference/init)
|
||||
- [`bd init-safety`](/cli-reference/init-safety)
|
||||
- [`bd jira`](/cli-reference/jira)
|
||||
- [`bd kv`](/cli-reference/kv)
|
||||
- [`bd label`](/cli-reference/label)
|
||||
- [`bd linear`](/cli-reference/linear)
|
||||
- [`bd link`](/cli-reference/link)
|
||||
- [`bd lint`](/cli-reference/lint)
|
||||
- [`bd list`](/cli-reference/list)
|
||||
- [`bd mail`](/cli-reference/mail)
|
||||
- [`bd memories`](/cli-reference/memories)
|
||||
- [`bd merge-slot`](/cli-reference/merge-slot)
|
||||
- [`bd metrics`](/cli-reference/metrics)
|
||||
- [`bd migrate`](/cli-reference/migrate)
|
||||
- [`bd migrate-personal`](/cli-reference/migrate-personal)
|
||||
- [`bd mol`](/cli-reference/mol)
|
||||
- [`bd note`](/cli-reference/note)
|
||||
- [`bd notion`](/cli-reference/notion)
|
||||
- [`bd onboard`](/cli-reference/onboard)
|
||||
- [`bd orphans`](/cli-reference/orphans)
|
||||
- [`bd ping`](/cli-reference/ping)
|
||||
- [`bd preflight`](/cli-reference/preflight)
|
||||
- [`bd prime`](/cli-reference/prime)
|
||||
- [`bd priority`](/cli-reference/priority)
|
||||
- [`bd promote`](/cli-reference/promote)
|
||||
- [`bd prune`](/cli-reference/prune)
|
||||
- [`bd purge`](/cli-reference/purge)
|
||||
- [`bd q`](/cli-reference/q)
|
||||
- [`bd query`](/cli-reference/query)
|
||||
- [`bd quickstart`](/cli-reference/quickstart)
|
||||
- [`bd ready`](/cli-reference/ready)
|
||||
- [`bd recall`](/cli-reference/recall)
|
||||
- [`bd reclaim`](/cli-reference/reclaim)
|
||||
- [`bd recompute-blocked`](/cli-reference/recompute-blocked)
|
||||
- [`bd remember`](/cli-reference/remember)
|
||||
- [`bd rename`](/cli-reference/rename)
|
||||
- [`bd rename-prefix`](/cli-reference/rename-prefix)
|
||||
- [`bd reopen`](/cli-reference/reopen)
|
||||
- [`bd repo`](/cli-reference/repo)
|
||||
- [`bd restore`](/cli-reference/restore)
|
||||
- [`bd rules`](/cli-reference/rules)
|
||||
- [`bd search`](/cli-reference/search)
|
||||
- [`bd set-state`](/cli-reference/set-state)
|
||||
- [`bd setup`](/cli-reference/setup)
|
||||
- [`bd ship`](/cli-reference/ship)
|
||||
- [`bd show`](/cli-reference/show)
|
||||
- [`bd sql`](/cli-reference/sql)
|
||||
- [`bd stale`](/cli-reference/stale)
|
||||
- [`bd state`](/cli-reference/state)
|
||||
- [`bd status`](/cli-reference/status)
|
||||
- [`bd statuses`](/cli-reference/statuses)
|
||||
- [`bd supersede`](/cli-reference/supersede)
|
||||
- [`bd swarm`](/cli-reference/swarm)
|
||||
- [`bd tag`](/cli-reference/tag)
|
||||
- [`bd todo`](/cli-reference/todo)
|
||||
- [`bd types`](/cli-reference/types)
|
||||
- [`bd unclaim`](/cli-reference/unclaim)
|
||||
- [`bd undefer`](/cli-reference/undefer)
|
||||
- [`bd update`](/cli-reference/update)
|
||||
- [`bd upgrade`](/cli-reference/upgrade)
|
||||
- [`bd vc`](/cli-reference/vc)
|
||||
- [`bd version`](/cli-reference/version)
|
||||
- [`bd where`](/cli-reference/where)
|
||||
- [`bd worktree`](/cli-reference/worktree)
|
||||
37
docs/cli-reference/info.md
Normal file
37
docs/cli-reference/info.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
title: "bd info"
|
||||
description: "Show database information"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
80
docs/cli-reference/init-safety.md
Normal file
80
docs/cli-reference/init-safety.md
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
---
|
||||
title: "bd init-safety"
|
||||
description: "Explain bd init flag semantics and the destroy-token format"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
101
docs/cli-reference/init.md
Normal file
101
docs/cli-reference/init.md
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
---
|
||||
title: "bd init"
|
||||
description: "Initialize bd in the current directory"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
120
docs/cli-reference/jira.md
Normal file
120
docs/cli-reference/jira.md
Normal file
|
|
@ -0,0 +1,120 @@
|
|||
---
|
||||
title: "bd jira"
|
||||
description: "Jira integration commands"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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")
|
||||
```
|
||||
75
docs/cli-reference/kv.md
Normal file
75
docs/cli-reference/kv.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
---
|
||||
title: "bd kv"
|
||||
description: "Key-value store commands"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
54
docs/cli-reference/label.md
Normal file
54
docs/cli-reference/label.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
title: "bd label"
|
||||
description: "Manage issue labels"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc label`.
|
||||
|
||||
Manage issue labels
|
||||
|
||||
```
|
||||
bd label [flags]
|
||||
```
|
||||
|
||||
## bd label add
|
||||
|
||||
Add a label to one or more issues
|
||||
|
||||
```
|
||||
bd label add [issue-id...] [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 a label from one or more issues
|
||||
|
||||
```
|
||||
bd label remove [issue-id...] [label] [flags]
|
||||
```
|
||||
223
docs/cli-reference/linear.md
Normal file
223
docs/cli-reference/linear.md
Normal file
|
|
@ -0,0 +1,223 @@
|
|||
---
|
||||
title: "bd linear"
|
||||
description: "Linear integration commands"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
28
docs/cli-reference/link.md
Normal file
28
docs/cli-reference/link.md
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
---
|
||||
title: "bd link"
|
||||
description: "Link two issues with a dependency"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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")
|
||||
```
|
||||
38
docs/cli-reference/lint.md
Normal file
38
docs/cli-reference/lint.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
title: "bd lint"
|
||||
description: "Check issues for missing template sections"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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)
|
||||
```
|
||||
77
docs/cli-reference/list.md
Normal file
77
docs/cli-reference/list.md
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
---
|
||||
title: "bd list"
|
||||
description: "List issues"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
33
docs/cli-reference/mail.md
Normal file
33
docs/cli-reference/mail.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
title: "bd mail"
|
||||
description: "Delegate to mail provider (e.g., gt mail)"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
19
docs/cli-reference/memories.md
Normal file
19
docs/cli-reference/memories.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
title: "bd memories"
|
||||
description: "List or search persistent memories"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
96
docs/cli-reference/merge-slot.md
Normal file
96
docs/cli-reference/merge-slot.md
Normal file
|
|
@ -0,0 +1,96 @@
|
|||
---
|
||||
title: "bd merge-slot"
|
||||
description: "Manage merge-slot gates for serialized conflict resolution"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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)
|
||||
```
|
||||
49
docs/cli-reference/metrics.md
Normal file
49
docs/cli-reference/metrics.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
title: "bd metrics"
|
||||
description: "Show or change anonymous usage-metrics settings"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
33
docs/cli-reference/migrate-personal.md
Normal file
33
docs/cli-reference/migrate-personal.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
title: "bd migrate-personal"
|
||||
description: "Move personal planning issues from the project database to your planning repo"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
156
docs/cli-reference/migrate.md
Normal file
156
docs/cli-reference/migrate.md
Normal file
|
|
@ -0,0 +1,156 @@
|
|||
---
|
||||
title: "bd migrate"
|
||||
description: "Database migration commands"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
616
docs/cli-reference/mol.md
Normal file
616
docs/cli-reference/mol.md
Normal file
|
|
@ -0,0 +1,616 @@
|
|||
---
|
||||
title: "bd mol"
|
||||
description: "Molecule commands (work templates)"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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)
|
||||
```
|
||||
29
docs/cli-reference/note.md
Normal file
29
docs/cli-reference/note.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
---
|
||||
title: "bd note"
|
||||
description: "Append a note to an issue"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
109
docs/cli-reference/notion.md
Normal file
109
docs/cli-reference/notion.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
---
|
||||
title: "bd notion"
|
||||
description: "Notion integration commands"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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")
|
||||
```
|
||||
28
docs/cli-reference/onboard.md
Normal file
28
docs/cli-reference/onboard.md
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
---
|
||||
title: "bd onboard"
|
||||
description: "Display minimal snippet for agent instructions file"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
33
docs/cli-reference/orphans.md
Normal file
33
docs/cli-reference/orphans.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
title: "bd orphans"
|
||||
description: "Identify orphaned issues (referenced in commits but still open)"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
26
docs/cli-reference/ping.md
Normal file
26
docs/cli-reference/ping.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
title: "bd ping"
|
||||
description: "Check database connectivity"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
38
docs/cli-reference/preflight.md
Normal file
38
docs/cli-reference/preflight.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
title: "bd preflight"
|
||||
description: "Show PR readiness checklist"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
60
docs/cli-reference/prime.md
Normal file
60
docs/cli-reference/prime.md
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
---
|
||||
title: "bd prime"
|
||||
description: "Output AI-optimized workflow context"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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)
|
||||
```
|
||||
27
docs/cli-reference/priority.md
Normal file
27
docs/cli-reference/priority.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
---
|
||||
title: "bd priority"
|
||||
description: "Set the priority of an issue"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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]
|
||||
```
|
||||
30
docs/cli-reference/promote.md
Normal file
30
docs/cli-reference/promote.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
title: "bd promote"
|
||||
description: "Promote a wisp to a permanent bead"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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
|
||||
```
|
||||
54
docs/cli-reference/prune.md
Normal file
54
docs/cli-reference/prune.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
title: "bd prune"
|
||||
description: "Delete old closed beads to reclaim space and shrink exports"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc 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-*')
|
||||
```
|
||||
42
docs/cli-reference/purge.md
Normal file
42
docs/cli-reference/purge.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
title: "bd purge"
|
||||
description: "Delete closed ephemeral beads to reclaim space"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc purge`.
|
||||
|
||||
Permanently delete closed ephemeral beads and their associated data.
|
||||
|
||||
Closed ephemeral beads (wisps, transient molecules) accumulate rapidly and
|
||||
have no value once closed. This command removes them to reclaim storage.
|
||||
|
||||
Deletes: issues, dependencies, labels, events, and comments for matching beads.
|
||||
Skips: pinned beads (protected).
|
||||
|
||||
To delete closed non-ephemeral beads (regular tasks, features, bugs, etc.)
|
||||
use `bd prune` 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 purge # Preview what would be purged
|
||||
bd purge --force # Delete all closed ephemeral beads
|
||||
bd purge --older-than 7d --force # Only purge items closed 7+ days ago
|
||||
bd purge --pattern "*-wisp-*" # Only purge matching ID pattern
|
||||
bd purge --dry-run # Detailed preview with stats
|
||||
|
||||
```
|
||||
bd purge [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--dry-run Preview what would be purged with stats
|
||||
-f, --force Actually purge (without this, shows preview)
|
||||
--older-than string Only purge beads closed more than N ago (e.g., 7d, 2w, 30)
|
||||
--pattern string Only purge beads matching ID glob pattern (e.g., *-wisp-*)
|
||||
```
|
||||
30
docs/cli-reference/q.md
Normal file
30
docs/cli-reference/q.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
title: "bd q"
|
||||
description: "Quick capture: create issue and output only ID"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc q`.
|
||||
|
||||
Quick capture creates an issue and outputs only the issue ID.
|
||||
Designed for scripting and AI agent integration.
|
||||
|
||||
Example:
|
||||
bd q "Fix login bug" # Outputs: bd-a1b2
|
||||
ISSUE=$(bd q "New feature") # Capture ID in variable
|
||||
bd q "Task" | xargs bd show # Pipe to other commands
|
||||
bd q "Subtask" --parent=bd-a1b2 # Hierarchical child (outputs: bd-a1b2.1)
|
||||
|
||||
```
|
||||
bd q [title] [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
-l, --labels strings Labels
|
||||
--parent string Parent issue ID for hierarchical child (e.g., 'bd-a3f8e9')
|
||||
-p, --priority string Priority (0-4 or P0-P4) (default "2")
|
||||
-t, --type string Issue type (default "task")
|
||||
```
|
||||
82
docs/cli-reference/query.md
Normal file
82
docs/cli-reference/query.md
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
---
|
||||
title: "bd query"
|
||||
description: "Query issues using a simple query language"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc query`.
|
||||
|
||||
Query issues using a simple query language that supports compound filters,
|
||||
boolean operators, and date-relative expressions.
|
||||
|
||||
The query language enables complex filtering that would otherwise require
|
||||
multiple flags or piping through jq.
|
||||
|
||||
Syntax:
|
||||
field=value Equality comparison
|
||||
field!=value Inequality comparison
|
||||
field>value Greater than
|
||||
field>=value Greater than or equal
|
||||
field<value Less than
|
||||
field<=value Less than or equal
|
||||
|
||||
Boolean operators (case-insensitive):
|
||||
expr AND expr Both conditions must match
|
||||
expr OR expr Either condition can match
|
||||
NOT expr Negates the condition
|
||||
(expr) Grouping with parentheses
|
||||
|
||||
Supported fields:
|
||||
status Stored status (open, in_progress, blocked, deferred, closed). Note: dependency-blocked issues stay "open"; use 'bd blocked' to find them
|
||||
priority Priority level (0-4)
|
||||
type Issue type (bug, feature, task, epic, chore, decision)
|
||||
assignee Assigned user (use "none" for unassigned)
|
||||
owner Issue owner
|
||||
label Issue label (use "none" for unlabeled)
|
||||
title Search in title (contains)
|
||||
description Search in description (contains, "none" for empty)
|
||||
notes Search in notes (contains)
|
||||
created Creation date/time
|
||||
updated Last update date/time
|
||||
started Date/time issue first transitioned to in_progress
|
||||
closed Close date/time
|
||||
id Issue ID (supports wildcards: bd-*)
|
||||
spec Spec ID (supports wildcards)
|
||||
pinned Boolean (true/false)
|
||||
ephemeral Boolean (true/false)
|
||||
template Boolean (true/false)
|
||||
parent Parent issue ID
|
||||
mol_type Molecule type (swarm, patrol, work)
|
||||
|
||||
Date values:
|
||||
Relative durations: 7d (7 days ago), 24h (24 hours ago), 2w (2 weeks ago)
|
||||
Absolute dates: 2025-01-15, 2025-01-15T10:00:00Z
|
||||
Natural language: tomorrow, "next monday", "in 3 days"
|
||||
|
||||
Examples:
|
||||
bd query "status=open AND priority>1"
|
||||
bd query "status=open AND priority<=2 AND updated>7d"
|
||||
bd query "(status=open OR status=blocked) AND priority<2"
|
||||
bd query "type=bug AND label=urgent"
|
||||
bd query "NOT status=closed"
|
||||
bd query "assignee=none AND type=task"
|
||||
bd query "created>30d AND status!=closed"
|
||||
bd query "label=frontend OR label=backend"
|
||||
bd query "title=authentication AND priority=0"
|
||||
|
||||
```
|
||||
bd query [expression] [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
-a, --all Include closed issues (default: exclude closed)
|
||||
-n, --limit int Limit results (default: 50, 0 = unlimited) (default 50)
|
||||
--long Show detailed multi-line output for each issue
|
||||
--offset int Skip the first N matching results (0-based). Only supported under --proxied-server.
|
||||
--parse-only Only parse the query and show the AST (for debugging)
|
||||
-r, --reverse Reverse sort order
|
||||
--sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee
|
||||
```
|
||||
14
docs/cli-reference/quickstart.md
Normal file
14
docs/cli-reference/quickstart.md
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
---
|
||||
title: "bd quickstart"
|
||||
description: "Quick start guide for bd"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc quickstart`.
|
||||
|
||||
Display a quick start guide showing common bd workflows and patterns.
|
||||
|
||||
```
|
||||
bd quickstart [flags]
|
||||
```
|
||||
58
docs/cli-reference/ready.md
Normal file
58
docs/cli-reference/ready.md
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
---
|
||||
title: "bd ready"
|
||||
description: "Show ready work (open, no active blockers)"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc ready`.
|
||||
|
||||
Show ready work (open issues with no active blockers).
|
||||
|
||||
Excludes in_progress, blocked, deferred, and hooked issues. This uses the
|
||||
GetReadyWork API which applies blocker-aware semantics to find truly claimable work.
|
||||
|
||||
Note: 'bd list --ready' uses the same blocker-aware ready-work semantics.
|
||||
|
||||
Use --mol to filter to a specific molecule's steps:
|
||||
bd ready --mol bd-patrol # Show ready steps within molecule
|
||||
|
||||
Use --gated to find molecules ready for gate-resume dispatch:
|
||||
bd ready --gated # Find molecules where a gate closed
|
||||
|
||||
Use --claim to atomically claim the first ready issue matching the filters:
|
||||
bd ready --claim --json
|
||||
|
||||
This is useful for agents executing molecules to see which steps can run next.
|
||||
|
||||
```
|
||||
bd ready [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
-a, --assignee string Filter by assignee
|
||||
--claim Atomically claim the first ready issue matching the filters
|
||||
--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)
|
||||
--explain Show dependency-aware reasoning for why issues are ready or blocked
|
||||
--gated Find molecules ready for gate-resume dispatch
|
||||
--has-metadata-key string Filter issues that have this metadata key set
|
||||
--include-deferred Include issues with future defer_until timestamps
|
||||
--include-ephemeral Include ephemeral issues (wisps) in results
|
||||
-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
|
||||
-n, --limit int Maximum issues to show (use 0 for unlimited) (default 100)
|
||||
--metadata-field stringArray Filter by metadata field (key=value, repeatable)
|
||||
--mol string Filter to steps within a specific molecule
|
||||
--mol-type string Filter by molecule type: swarm, patrol, or work
|
||||
--offset int Skip the first N matching results (0-based). Only supported under --proxied-server.
|
||||
--parent string Filter to descendants of this bead/epic
|
||||
--plain Display issues as a plain numbered list
|
||||
--pretty Display issues in a tree format with status/priority symbols (default true)
|
||||
-p, --priority int Filter by priority
|
||||
-s, --sort string Sort policy: priority (default), hybrid, oldest (default "priority")
|
||||
-t, --type string Filter by issue type (task, bug, feature, epic, decision, merge-request). Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision
|
||||
-u, --unassigned Show only unassigned issues
|
||||
```
|
||||
18
docs/cli-reference/recall.md
Normal file
18
docs/cli-reference/recall.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
title: "bd recall"
|
||||
description: "Retrieve a specific memory"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc recall`.
|
||||
|
||||
Retrieve the full content of a memory by its key.
|
||||
|
||||
Examples:
|
||||
bd recall dolt-phantoms
|
||||
bd recall auth-jwt
|
||||
|
||||
```
|
||||
bd recall <key> [flags]
|
||||
```
|
||||
37
docs/cli-reference/reclaim.md
Normal file
37
docs/cli-reference/reclaim.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
title: "bd reclaim"
|
||||
description: "Revert stale-lease in_progress issues back to ready (dead-worker recovery)"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc reclaim`.
|
||||
|
||||
Revert in_progress issues whose lease has gone stale back to ready.
|
||||
|
||||
When a worker claims an issue it takes a lease that expires after a TTL, kept
|
||||
alive by 'bd heartbeat'. A worker that dies stops heartbeating, so its lease
|
||||
expires and its issue would otherwise stay in_progress forever. reclaim is the
|
||||
reaper: it finds in_progress issues whose lease expired more than --older-than
|
||||
ago, clears the assignee, and sets them back to open so another worker can
|
||||
claim them. The previous owner's stale lease is recorded as a recovery event.
|
||||
|
||||
--older-than is a grace window past lease expiry: only leases that expired at
|
||||
least this long ago are reclaimed, so a worker briefly paused (GC, clock skew)
|
||||
is not robbed of live work. Run it from a supervisor on a timer with a window
|
||||
of roughly 2× the claim TTL.
|
||||
|
||||
Examples:
|
||||
bd reclaim # default grace window (2× the lease TTL)
|
||||
bd reclaim --older-than 10m # reclaim leases expired >10m ago
|
||||
bd reclaim --older-than 0s # reclaim every currently-expired lease
|
||||
|
||||
```
|
||||
bd reclaim [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--older-than duration Only reclaim leases that expired at least this long ago (grace window) (default 10m0s)
|
||||
```
|
||||
30
docs/cli-reference/recompute-blocked.md
Normal file
30
docs/cli-reference/recompute-blocked.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
title: "bd recompute-blocked"
|
||||
description: "Recompute is_blocked for all issues (repairs stale flags after a pull)"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc recompute-blocked`.
|
||||
|
||||
Recompute the denormalized is_blocked flag for every issue and wisp.
|
||||
|
||||
is_blocked is derived from the dependency graph and maintained automatically by
|
||||
local writes and by a post-pull recompute scoped to what the merge changed. If
|
||||
that scoped recompute is skipped — a recompute that failed after its merge
|
||||
committed, or a conflicted pull resolved by hand — the flag can go stale, and a
|
||||
later pull that merges nothing will not refresh it (bd-6dnrw.37). 'bd ready'
|
||||
trusts the flag, so stale values silently hide ready work or surface blocked
|
||||
work.
|
||||
|
||||
This command runs the full recompute unconditionally and commits the result.
|
||||
It is idempotent: on a consistent database it changes nothing. Works in both
|
||||
embedded and server mode (unlike 'bd doctor', which is server-mode only).
|
||||
|
||||
Examples:
|
||||
bd recompute-blocked # Repair stale is_blocked flags
|
||||
bd recompute-blocked --json # Machine-parseable {"rows_corrected": N}
|
||||
|
||||
```
|
||||
bd recompute-blocked [flags]
|
||||
```
|
||||
34
docs/cli-reference/remember.md
Normal file
34
docs/cli-reference/remember.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
title: "bd remember"
|
||||
description: "Store a persistent memory"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc remember`.
|
||||
|
||||
Store a memory that persists across sessions and account rotations.
|
||||
|
||||
Memories are injected at prime time (bd prime) so you have them
|
||||
in every session without manual loading.
|
||||
|
||||
The positional arg is the memory CONTENT (the key is auto-generated from it
|
||||
unless --key is given). As a convenience, if the arg is a bare key naming an
|
||||
existing memory, it is RECALLED instead of stored (same as 'bd recall');
|
||||
a bare key naming nothing is refused. Use --key to store slug-like content.
|
||||
|
||||
Examples:
|
||||
bd remember "always run tests with -race flag"
|
||||
bd remember "Dolt phantom DBs hide in three places" --key dolt-phantoms
|
||||
bd remember "auth module uses JWT not sessions" --key auth-jwt
|
||||
bd remember dolt-phantoms # bare existing key: reads it (= bd recall)
|
||||
|
||||
```
|
||||
bd remember "<insight>" [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--key string Explicit key for the memory (auto-generated from content if not set). If a memory with this key already exists, it will be updated in place
|
||||
```
|
||||
47
docs/cli-reference/rename-prefix.md
Normal file
47
docs/cli-reference/rename-prefix.md
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
---
|
||||
title: "bd rename-prefix"
|
||||
description: "Rename the issue prefix for all issues in the database"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc rename-prefix`.
|
||||
|
||||
Rename the issue prefix for all issues in the database.
|
||||
This will update all issue IDs and all text references across all fields.
|
||||
|
||||
USE CASES:
|
||||
- Shortening long prefixes (e.g., 'knowledge-work-' → 'kw-')
|
||||
- Rebranding project naming conventions
|
||||
- Consolidating multiple prefixes after database corruption
|
||||
- Migrating to team naming standards
|
||||
|
||||
Prefix validation rules:
|
||||
- Max length: 8 characters
|
||||
- Allowed characters: lowercase letters, numbers, hyphens
|
||||
- Must start with a letter
|
||||
- Must end with a hyphen (e.g., 'kw-', 'work-')
|
||||
- Cannot be empty or just a hyphen
|
||||
|
||||
Multiple prefix detection and repair:
|
||||
If issues have multiple prefixes (corrupted database), use --repair to consolidate them.
|
||||
The --repair flag will rename all issues with incorrect prefixes to the new prefix,
|
||||
preserving issues that already have the correct prefix.
|
||||
|
||||
EXAMPLES:
|
||||
bd rename-prefix kw- # Rename from 'knowledge-work-' to 'kw-'
|
||||
bd rename-prefix mtg- --repair # Consolidate multiple prefixes into 'mtg-'
|
||||
bd rename-prefix team- --dry-run # Preview changes without applying
|
||||
|
||||
NOTE: This is a rare operation. Most users never need this command.
|
||||
|
||||
```
|
||||
bd rename-prefix <new-prefix> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--dry-run Preview changes without applying them
|
||||
--repair Repair database with multiple prefixes by consolidating them
|
||||
```
|
||||
26
docs/cli-reference/rename.md
Normal file
26
docs/cli-reference/rename.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
title: "bd rename"
|
||||
description: "Rename an issue ID"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc rename`.
|
||||
|
||||
Rename an issue from one ID to another.
|
||||
|
||||
This updates:
|
||||
- The issue's primary ID
|
||||
- All references in other issues (descriptions, titles, notes, etc.)
|
||||
- Dependencies pointing to/from this issue
|
||||
- Labels, comments, and events
|
||||
|
||||
Examples:
|
||||
bd rename bd-w382l bd-dolt # Rename to memorable ID
|
||||
bd rename gt-abc123 gt-auth # Use descriptive ID
|
||||
|
||||
Note: The new ID must use a valid prefix for this database.
|
||||
|
||||
```
|
||||
bd rename <old-id> <new-id> [flags]
|
||||
```
|
||||
21
docs/cli-reference/reopen.md
Normal file
21
docs/cli-reference/reopen.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
---
|
||||
title: "bd reopen"
|
||||
description: "Reopen one or more closed issues"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc reopen`.
|
||||
|
||||
Reopen closed issues by setting status to 'open' and clearing the closed_at timestamp.
|
||||
This is more explicit than 'bd update --status open' and emits a Reopened event.
|
||||
|
||||
```
|
||||
bd reopen [id...] [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
-r, --reason string Reason for reopening
|
||||
```
|
||||
110
docs/cli-reference/repo.md
Normal file
110
docs/cli-reference/repo.md
Normal file
|
|
@ -0,0 +1,110 @@
|
|||
---
|
||||
title: "bd repo"
|
||||
description: "Manage multiple repository configuration"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc repo`.
|
||||
|
||||
Configure and manage multiple repository support for multi-repo hydration.
|
||||
|
||||
Multi-repo support allows hydrating issues from multiple beads repositories
|
||||
into a single database for unified cross-repo issue tracking.
|
||||
|
||||
Configuration is stored in .beads/config.yaml under the 'repos' section:
|
||||
|
||||
repos:
|
||||
primary: "."
|
||||
additional:
|
||||
- ~/beads-planning
|
||||
- ~/work-repo
|
||||
|
||||
Examples:
|
||||
bd repo add ~/beads-planning # Add planning repo
|
||||
bd repo add ../other-repo # Add relative path repo
|
||||
bd repo list # Show all configured repos
|
||||
bd repo remove ~/beads-planning # Remove by path
|
||||
bd repo sync # Sync from all configured repos
|
||||
|
||||
```
|
||||
bd repo [flags]
|
||||
```
|
||||
|
||||
## bd repo add
|
||||
|
||||
Add a repository path to the repos.additional list in config.yaml.
|
||||
|
||||
The path should point to a directory containing a .beads folder.
|
||||
Paths can be absolute or relative (they are stored as-is).
|
||||
|
||||
This modifies .beads/config.yaml, which is version-controlled and
|
||||
shared across all clones of this repository.
|
||||
|
||||
```
|
||||
bd repo add <path> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--json Output JSON
|
||||
```
|
||||
|
||||
## bd repo list
|
||||
|
||||
List all repositories configured in .beads/config.yaml.
|
||||
|
||||
Shows the primary repository (always ".") and any additional
|
||||
repositories configured for hydration.
|
||||
|
||||
```
|
||||
bd repo list [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--json Output JSON
|
||||
```
|
||||
|
||||
## bd repo remove
|
||||
|
||||
Remove a repository path from the repos.additional list in config.yaml.
|
||||
|
||||
The path must exactly match what was added (e.g., if you added "~/foo",
|
||||
you must remove "~/foo", not "/home/user/foo").
|
||||
|
||||
This command also removes any previously-hydrated issues from the database
|
||||
that came from the removed repository.
|
||||
|
||||
```
|
||||
bd repo remove <path> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--json Output JSON
|
||||
```
|
||||
|
||||
## bd repo sync
|
||||
|
||||
Synchronize issues from all configured additional repositories.
|
||||
|
||||
Reads issues.jsonl from each additional repository and imports them into
|
||||
the primary database with their original prefixes and source_repo set.
|
||||
Uses mtime caching to skip repos whose JSONL hasn't changed.
|
||||
|
||||
Also triggers Dolt push/pull if a remote is configured.
|
||||
|
||||
```
|
||||
bd repo sync [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--json Output JSON
|
||||
--verbose Show detailed sync progress
|
||||
```
|
||||
33
docs/cli-reference/restore.md
Normal file
33
docs/cli-reference/restore.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
title: "bd restore"
|
||||
description: "Restore the pre-compaction content of a compacted issue"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc restore`.
|
||||
|
||||
Restore the pre-compaction content of a compacted issue.
|
||||
|
||||
When an issue is compacted, its description/design/notes/acceptance criteria
|
||||
are summarized and the originals are archived to a compaction snapshot. This
|
||||
command recovers that original content.
|
||||
|
||||
By default it is read-only: it displays the archived content without modifying
|
||||
the database. Pass --apply to write the original content back into the issue
|
||||
and step its compaction level back down.
|
||||
|
||||
If no archived snapshot exists (e.g. the issue was compacted by an older bd
|
||||
before snapshot archiving), restore falls back to a best-effort reconstruction
|
||||
from Dolt version history, which can only be displayed, not applied.
|
||||
|
||||
```
|
||||
bd restore <issue-id> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--apply Write the restored content back into the issue (default: display only)
|
||||
--json Output restore results in JSON format
|
||||
```
|
||||
46
docs/cli-reference/rules.md
Normal file
46
docs/cli-reference/rules.md
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
---
|
||||
title: "bd rules"
|
||||
description: "Audit and compact Claude rules"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc rules`.
|
||||
|
||||
Audit and compact Claude rules
|
||||
|
||||
```
|
||||
bd rules [flags]
|
||||
```
|
||||
|
||||
## bd rules audit
|
||||
|
||||
Scan rules for contradictions and merge opportunities
|
||||
|
||||
```
|
||||
bd rules audit [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--path string Path to rules directory (default ".claude/rules/")
|
||||
--threshold float Jaccard similarity threshold (default 0.6)
|
||||
```
|
||||
|
||||
## bd rules compact
|
||||
|
||||
Merge related rules into composites
|
||||
|
||||
```
|
||||
bd rules compact [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--auto Apply audit suggestions
|
||||
--dry-run Preview without applying
|
||||
--group strings Rule names to merge
|
||||
--path string Path to rules directory (default ".claude/rules/")
|
||||
```
|
||||
63
docs/cli-reference/search.md
Normal file
63
docs/cli-reference/search.md
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
title: "bd search"
|
||||
description: "Search issues by text query"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc search`.
|
||||
|
||||
Search issues across title and ID (excludes closed issues by default).
|
||||
|
||||
ID-like queries (e.g., "bd-123", "hq-319") use fast exact/prefix matching.
|
||||
Text queries search titles. Use --desc-contains for description search.
|
||||
Use --status all to include closed issues.
|
||||
|
||||
Examples:
|
||||
bd search "authentication bug"
|
||||
bd search "login" --status open
|
||||
bd search "database" --label backend --limit 10
|
||||
bd search --query "performance" --assignee alice
|
||||
bd search "bd-5q" # Search by partial ID (fast prefix match)
|
||||
bd search "security" --priority-min 0 --priority-max 2
|
||||
bd search "bug" --created-after 2025-01-01
|
||||
bd search "refactor" --status all # Include closed issues
|
||||
bd search "bug" --sort priority
|
||||
bd search "task" --sort created --reverse
|
||||
bd search "api" --desc-contains "endpoint"
|
||||
bd search "cleanup" --no-assignee --no-labels
|
||||
|
||||
```
|
||||
bd search [query] [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
-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)
|
||||
--desc-contains string Filter by description substring (case-insensitive)
|
||||
--empty-description Filter issues with empty or missing description
|
||||
--external-contains string Filter by external ref substring (case-insensitive)
|
||||
--has-metadata-key string Filter issues that have this metadata key set
|
||||
-l, --label strings Filter by labels (AND: must have ALL)
|
||||
--label-any strings Filter by labels (OR: must have AT LEAST ONE)
|
||||
-n, --limit int Limit results (default: 50) (default 50)
|
||||
--long Show detailed multi-line output for each issue
|
||||
--metadata-field stringArray Filter by metadata field (key=value, repeatable)
|
||||
--no-assignee Filter issues with no assignee
|
||||
--no-labels Filter issues with no labels
|
||||
--notes-contains string Filter by notes substring (case-insensitive)
|
||||
--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)
|
||||
--query string Search query (alternative to positional argument)
|
||||
-r, --reverse Reverse sort order
|
||||
--sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee
|
||||
-s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed, all). Default excludes closed; use 'all' to include closed. Note: dependency-blocked issues use 'bd blocked'
|
||||
-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)
|
||||
```
|
||||
37
docs/cli-reference/set-state.md
Normal file
37
docs/cli-reference/set-state.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
title: "bd set-state"
|
||||
description: "Set operational state (creates event + updates label)"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc set-state`.
|
||||
|
||||
Atomically set operational state on an issue.
|
||||
|
||||
This command:
|
||||
1. Creates an event bead recording the state change (source of truth)
|
||||
2. Removes any existing label for the dimension
|
||||
3. Adds the new dimension:value label (fast lookup cache)
|
||||
|
||||
State labels follow the convention <dimension>:<value>, for example:
|
||||
patrol:active, patrol:muted
|
||||
mode:normal, mode:degraded
|
||||
health:healthy, health:failing
|
||||
|
||||
Examples:
|
||||
bd set-state agent-abc patrol=muted --reason "Investigating stuck worker"
|
||||
bd set-state agent-abc mode=degraded --reason "High error rate detected"
|
||||
bd set-state agent-abc health=healthy
|
||||
|
||||
The --reason flag provides context for the event bead (recommended).
|
||||
|
||||
```
|
||||
bd set-state <issue-id> <dimension>=<value> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--reason string Reason for the state change (recorded in event)
|
||||
```
|
||||
48
docs/cli-reference/setup.md
Normal file
48
docs/cli-reference/setup.md
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
title: "bd setup"
|
||||
description: "Setup integration with AI editors"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc setup`.
|
||||
|
||||
Setup integration files for AI editors and coding assistants.
|
||||
|
||||
Recipes define where beads workflow instructions are written. Built-in recipes
|
||||
include cursor, claude, copilot, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode.
|
||||
|
||||
Examples:
|
||||
bd setup cursor # Install Cursor IDE integration (rules + agent hooks)
|
||||
bd setup cursor --global # Install global Cursor hooks (~/.cursor/hooks.json)
|
||||
bd setup codex # Install Codex skill + AGENTS.md guidance + native hooks
|
||||
bd setup codex --global # Install global Codex skill + guidance + native hooks
|
||||
bd setup copilot # Install Copilot CLI plugin + repository instructions
|
||||
bd setup mux --project # Install Mux workspace layer (.mux/AGENTS.md)
|
||||
bd setup mux --global # Install Mux global layer (~/.mux/AGENTS.md)
|
||||
bd setup mux --project --global # Install both Mux layers
|
||||
bd setup --list # Show all available recipes
|
||||
bd setup --print # Print the template to stdout
|
||||
bd setup -o rules.md # Write template to custom path
|
||||
bd setup --add myeditor .myeditor/rules.md # Add custom recipe
|
||||
|
||||
Use 'bd setup <recipe> --check' to verify installation status.
|
||||
Use 'bd setup <recipe> --remove' to uninstall.
|
||||
|
||||
```
|
||||
bd setup [recipe] [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--add string Add a custom recipe with given name
|
||||
--check Check if integration is installed
|
||||
--global Install globally (claude/codex/cursor/mux; writes to ~/.claude/settings.json, $CODEX_HOME/AGENTS.md or ~/.codex/AGENTS.md, ~/.cursor/hooks.json, or ~/.mux/AGENTS.md)
|
||||
--list List all available recipes
|
||||
-o, --output string Write template to custom path
|
||||
--print Print the template to stdout
|
||||
--project Install for this project only (gemini/mux)
|
||||
--remove Remove the integration
|
||||
--stealth Use stealth mode (claude/gemini)
|
||||
```
|
||||
37
docs/cli-reference/ship.md
Normal file
37
docs/cli-reference/ship.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
title: "bd ship"
|
||||
description: "Publish a capability for cross-project dependencies"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc ship`.
|
||||
|
||||
Ship a capability to satisfy cross-project dependencies.
|
||||
|
||||
This command:
|
||||
1. Finds issue with export:<capability> label
|
||||
2. Validates issue is closed (or --force to override)
|
||||
3. Adds provides:<capability> label
|
||||
|
||||
External projects can depend on this capability using:
|
||||
bd dep add <issue> external:<project>:<capability>
|
||||
|
||||
The capability is resolved when the external project has a closed issue
|
||||
with the provides:<capability> label.
|
||||
|
||||
Examples:
|
||||
bd ship mol-run-assignee # Ship the mol-run-assignee capability
|
||||
bd ship mol-run-assignee --force # Ship even if issue is not closed
|
||||
bd ship mol-run-assignee --dry-run # Preview without making changes
|
||||
|
||||
```
|
||||
bd ship <capability> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--dry-run Preview without making changes
|
||||
--force Ship even if issue is not closed
|
||||
```
|
||||
33
docs/cli-reference/show.md
Normal file
33
docs/cli-reference/show.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
title: "bd show"
|
||||
description: "Show issue details"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc show`.
|
||||
|
||||
Show issue details
|
||||
|
||||
```
|
||||
bd show [id...] [--id=<id>...] [--current] [flags]
|
||||
```
|
||||
|
||||
**Aliases:** view
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--as-of string Show issue as it existed at a specific commit hash or branch (requires Dolt)
|
||||
--children Show only the children of this issue
|
||||
--current Show the currently active issue (in-progress, hooked, or last touched)
|
||||
--id stringArray Issue ID (use for IDs that look like flags, e.g., --id=gt--xyz)
|
||||
--include-comments Stream full comment bodies in JSON output (--json only; may be slow on issues with many comments)
|
||||
--include-dependents Stream full dependent issues in JSON output (--json only; may be slow on hub beads)
|
||||
--local-time Show timestamps in local time instead of UTC
|
||||
--long Show all available fields (extended metadata, agent identity, gate fields, etc.)
|
||||
--refs Show issues that reference this issue (reverse lookup)
|
||||
--short Show compact one-line output per issue
|
||||
--thread Show full conversation thread (for messages)
|
||||
-w, --watch Watch for changes and auto-refresh display
|
||||
```
|
||||
34
docs/cli-reference/sql.md
Normal file
34
docs/cli-reference/sql.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
title: "bd sql"
|
||||
description: "Execute raw SQL against the beads database"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc sql`.
|
||||
|
||||
Execute a raw SQL query against the underlying database (SQLite or Dolt).
|
||||
|
||||
Useful for debugging, maintenance, and working around bugs in higher-level commands.
|
||||
|
||||
Examples:
|
||||
bd sql 'SELECT COUNT(*) FROM issues'
|
||||
bd sql 'SELECT id, title FROM issues WHERE status = "open" LIMIT 5'
|
||||
bd sql 'DELETE FROM dirty_issues WHERE issue_id = "bd-abc123"'
|
||||
bd sql --csv 'SELECT id, title, status FROM issues'
|
||||
|
||||
The query is passed directly to the database. SELECT queries return results as a
|
||||
table (or JSON/CSV with --json/--csv). Non-SELECT queries (INSERT, UPDATE, DELETE)
|
||||
report the number of rows affected.
|
||||
|
||||
WARNING: Direct database access bypasses the storage layer. Use with caution.
|
||||
|
||||
```
|
||||
bd sql <query> [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--csv Output results in CSV format
|
||||
```
|
||||
26
docs/cli-reference/stale.md
Normal file
26
docs/cli-reference/stale.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
title: "bd stale"
|
||||
description: "Show stale issues (not updated recently)"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc stale`.
|
||||
|
||||
Show issues that haven't been updated recently and may need attention.
|
||||
This helps identify:
|
||||
- In-progress issues with no recent activity (may be abandoned)
|
||||
- Open issues that have been forgotten
|
||||
- Issues that might be outdated or no longer relevant
|
||||
|
||||
```
|
||||
bd stale [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
-d, --days int Issues not updated in this many days (default 30)
|
||||
-n, --limit int Maximum issues to show (default 50)
|
||||
-s, --status string Filter by status (open|in_progress|blocked|deferred)
|
||||
```
|
||||
43
docs/cli-reference/state.md
Normal file
43
docs/cli-reference/state.md
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
title: "bd state"
|
||||
description: "Query the current value of a state dimension"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc state`.
|
||||
|
||||
Query the current value of a state dimension from an issue's labels.
|
||||
|
||||
State labels follow the convention <dimension>:<value>, for example:
|
||||
patrol:active
|
||||
mode:degraded
|
||||
health:healthy
|
||||
|
||||
This command extracts the value for a given dimension.
|
||||
|
||||
Examples:
|
||||
bd state witness-abc patrol # Output: active
|
||||
bd state witness-abc mode # Output: normal
|
||||
bd state witness-abc health # Output: healthy
|
||||
|
||||
```
|
||||
bd state <issue-id> <dimension> [flags]
|
||||
```
|
||||
|
||||
## bd state list
|
||||
|
||||
List all state labels (dimension:value format) on an issue.
|
||||
|
||||
This filters labels to only show those following the state convention.
|
||||
|
||||
Example:
|
||||
bd state list witness-abc
|
||||
# Output:
|
||||
# patrol: active
|
||||
# mode: normal
|
||||
# health: healthy
|
||||
|
||||
```
|
||||
bd state list <issue-id> [flags]
|
||||
```
|
||||
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