docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876)
* docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a regeneration from main's source onto the PR branch, so the squash landed a contradictory mix — the release-aligned hand-written docs plus a CLI reference re-documenting unreleased commands and flags, with docs.json referencing four pages (heartbeat, migrate-personal, reclaim, unclaim) whose files do not exist. That broken nav fails the docsync guard on main and on every branch cut from it. This restores the intended end state of #4874 and lands the pin that prevents the race from recurring. - Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's canonical pure-Go build), removing the unreleased commands/flags and fixing the dangling nav entries. - docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh builds and caches a canonical pure-Go bd from that tag, fetching the tag first in shallow CI checkouts. - generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh resolve bd through the pin and ignore a supplied binary while pinned (BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot now enforce docs-match-release instead of docs-match-main. - tools/docsmint detects the pre-overhaul Docusaurus staging layout that bd <= v1.1.0 emits and converts it to the generic form before its normal Mintlify transform (tested); removable once the pin reaches a release whose emitter writes build/cli-docs. - check-doc-flags.sh: run without timeout(1) on macOS instead of failing Check 4. - Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the beads-docs skill §8 updated to match. * lint: annotate gosec G705 false positive in the docsmint legacy bridge Same class as the existing nav-splice annotation: a developer tool writing repo Markdown, not a web-output sink.
This commit is contained in:
parent
8c974d8dc4
commit
d2f87d50de
118 changed files with 882 additions and 1056 deletions
|
|
@ -190,6 +190,14 @@ style, nav), edit `tools/docsmint` and its tests. The drift gates
|
|||
(`generate-cli-docs.sh --check`, `scripts/check-cli-docs-drift.sh` in PR CI,
|
||||
and the docs-autofix bot) fail or auto-fix any hand edit.
|
||||
|
||||
**The docs describe the pinned release, not main.** `docs/cli-docs.pin`
|
||||
names the release tag the whole docs corpus targets; the pipeline builds bd
|
||||
from that tag and validates against it, so a Go-source edit on main shows up
|
||||
in the committed docs only after the pin is bumped (at release time,
|
||||
followed by a regeneration). Hand-written pages follow the same policy:
|
||||
document what the pinned release does, never main-only features. See
|
||||
`engdocs/decisions/2026-07-17-docs-release-pin.md`.
|
||||
|
||||
## 9. Verify before you call it done
|
||||
|
||||
Run the gates in [references/verification.md](references/verification.md).
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
12
docs/cli-docs.pin
Normal file
12
docs/cli-docs.pin
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
# Pins the bd version that the generated CLI docs are produced from and
|
||||
# validated against: docs/CLI_REFERENCE.md, docs/cli-reference/, and the
|
||||
# CLI Reference pages array in docs/docs.json.
|
||||
#
|
||||
# The published docs site describes the latest *release*, not main's source,
|
||||
# so the docs pipeline builds bd from this tag (CGO_ENABLED=0, pure Go —
|
||||
# CI's canonical build) instead of the current checkout. Bump this tag as
|
||||
# part of each release, then run ./scripts/generate-cli-docs.sh.
|
||||
#
|
||||
# Set to HEAD to track the current checkout's source instead (the pre-pin
|
||||
# behavior).
|
||||
v1.1.0
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd admin"
|
||||
description: "Administrative commands for database maintenance"
|
||||
description: "Administrative commands for beads database maintenance."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -18,7 +18,7 @@ For routine maintenance, prefer 'bd doctor --fix' which handles common repairs
|
|||
automatically. Use these admin commands for targeted database operations.
|
||||
|
||||
```
|
||||
bd admin [command]
|
||||
bd admin [flags]
|
||||
```
|
||||
|
||||
## bd admin cleanup
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd ado"
|
||||
description: "Azure DevOps integration commands"
|
||||
description: "Commands for syncing issues between beads and Azure DevOps."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -17,7 +17,7 @@ Configuration can be set via 'bd config' or environment variables:
|
|||
ado.url / AZURE_DEVOPS_URL - Custom base URL (on-prem)
|
||||
|
||||
```
|
||||
bd ado [command]
|
||||
bd ado [flags]
|
||||
```
|
||||
|
||||
## bd ado projects
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd assign"
|
||||
description: "Assign an issue to someone"
|
||||
description: "Assign an issue to someone."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,27 +1,22 @@
|
|||
---
|
||||
title: "bd audit"
|
||||
description: "Record and label agent interactions (append-only JSONL)"
|
||||
description: "Audit log entries are appended to .beads/interactions.jsonl."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
||||
Generated from `bd help --doc audit`.
|
||||
|
||||
Record explicit agent/tool interaction audit entries in .beads/interactions.jsonl.
|
||||
Audit log entries are appended to .beads/interactions.jsonl.
|
||||
|
||||
This optional JSONL sidecar is disabled by default. Enable it with:
|
||||
|
||||
bd config set audit.enabled true
|
||||
|
||||
Issue history is always recorded in the database and is visible with
|
||||
bd history <id> --events. The JSONL sidecar is for explicit interaction capture:
|
||||
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 [command]
|
||||
bd audit [flags]
|
||||
```
|
||||
|
||||
## bd audit label
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd backup"
|
||||
description: "Back up your beads database"
|
||||
description: "Back up your beads database for off-machine recovery."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -25,18 +25,8 @@ 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.
|
||||
|
||||
Auto-backup default:
|
||||
When backup.enabled is unset, auto-backup turns ON in embedded mode if a
|
||||
git remote exists, and stays OFF in sql-server / shared-server mode. In
|
||||
server mode many bd clients share one Dolt server, and each would register
|
||||
a server-side backup remote under the same name pointing at its own local
|
||||
dir and full-sync the whole database — a self-amplifying storm. To back up
|
||||
a shared server, run 'bd backup' explicitly (or set backup.enabled=true and
|
||||
coordinate destinations). 'bd config get backup.enabled' shows the effective
|
||||
value and its source.
|
||||
|
||||
```
|
||||
bd backup [command]
|
||||
bd backup [flags]
|
||||
```
|
||||
|
||||
## bd backup init
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd batch"
|
||||
description: "Run multiple write operations in a single database transaction"
|
||||
description: "Run multiple write operations in a single database transaction."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd bootstrap"
|
||||
description: "Non-destructive database setup for fresh clones and recovery"
|
||||
description: "Bootstrap sets up the beads database without destroying existing data."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd branch"
|
||||
description: "List or create branches"
|
||||
description: "List all branches or create a new branch."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd children"
|
||||
description: "List child beads of a parent"
|
||||
description: "List all beads that are children of the specified parent bead."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd close"
|
||||
description: "Close one or more issues"
|
||||
description: "Close one or more issues."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd comment"
|
||||
description: "Add a comment to an issue"
|
||||
description: "Add a comment to an issue."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd comments"
|
||||
description: "View or manage comments on an issue"
|
||||
description: "View or manage comments on an issue."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -24,7 +24,6 @@ Examples:
|
|||
|
||||
```
|
||||
bd comments [issue-id] [flags]
|
||||
bd comments [command]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd compact"
|
||||
description: "Squash old Dolt commits to reduce history size"
|
||||
description: "Squash Dolt commits older than N days into a single commit."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd completion"
|
||||
description: "Generate the autocompletion script for the specified shell"
|
||||
description: "Generate the autocompletion script for bd for the specified shell."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -12,7 +12,7 @@ See each sub-command's help for details on how to use the generated script.
|
|||
|
||||
|
||||
```
|
||||
bd completion [command]
|
||||
bd completion [flags]
|
||||
```
|
||||
|
||||
## bd completion bash
|
||||
|
|
@ -28,11 +28,11 @@ To load completions in your current shell session:
|
|||
|
||||
To load completions for every new session, execute once:
|
||||
|
||||
#### Linux:
|
||||
### Linux:
|
||||
|
||||
bd completion bash > /etc/bash_completion.d/bd
|
||||
|
||||
#### macOS:
|
||||
### macOS:
|
||||
|
||||
bd completion bash > $(brew --prefix)/etc/bash_completion.d/bd
|
||||
|
||||
|
|
@ -111,11 +111,11 @@ To load completions in your current shell session:
|
|||
|
||||
To load completions for every new session, execute once:
|
||||
|
||||
#### Linux:
|
||||
### Linux:
|
||||
|
||||
bd completion zsh > "${fpath[1]}/_bd"
|
||||
|
||||
#### macOS:
|
||||
### macOS:
|
||||
|
||||
bd completion zsh > $(brew --prefix)/share/zsh/site-functions/_bd
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd config"
|
||||
description: "Manage configuration settings"
|
||||
description: "Manage configuration settings for external integrations and preferences."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -17,12 +17,8 @@ Common namespaces:
|
|||
- 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
|
||||
- claim.* Claim arbitration settings (pool-aware claiming)
|
||||
- doctor.suppress.* Suppress specific bd doctor warnings (GH#1095)
|
||||
|
||||
Auto-Export (config.yaml):
|
||||
|
|
@ -56,18 +52,6 @@ Custom Status States:
|
|||
This enables issues to use statuses like 'awaiting_review' in addition to
|
||||
the built-in statuses (open, in_progress, blocked, deferred, closed).
|
||||
|
||||
Claim Pools:
|
||||
A dispatcher can pre-assign issues to a pool pseudo-assignee (e.g.
|
||||
"fable-crew") and let any actor take them with --claim. List the pool
|
||||
aliases in the claim.pools config key, comma-separated:
|
||||
|
||||
bd config set claim.pools "fable-crew,night-crew"
|
||||
|
||||
Issues assigned to a real actor (or to an alias not in the list) keep
|
||||
their anti-steal protection. Pool takes carry the normal lease; note
|
||||
that if a taker's lease expires, bd reclaim returns the issue to the
|
||||
unassigned pool, not to the pool alias it was dispatched to.
|
||||
|
||||
Suppressing Doctor Warnings:
|
||||
Suppress specific bd doctor warnings by check name slug:
|
||||
bd config set doctor.suppress.pending-migrations true
|
||||
|
|
@ -84,7 +68,6 @@ Examples:
|
|||
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 claim.pools "fable-crew,night-crew" # Pool aliases claimable by any actor
|
||||
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
|
||||
|
|
@ -93,7 +76,7 @@ Examples:
|
|||
bd config unset jira.url
|
||||
|
||||
```
|
||||
bd config [command]
|
||||
bd config [flags]
|
||||
```
|
||||
|
||||
## bd config apply
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd context"
|
||||
description: "Show effective backend identity and repository context"
|
||||
description: "Show the effective backend identity information including repository paths,"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd cook"
|
||||
description: "Compile a formula into a proto (ephemeral by default)"
|
||||
description: "Cook transforms a .formula.json file into a proto."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd count"
|
||||
description: "Count issues matching filters"
|
||||
description: "Count issues matching the specified filters."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd create-form"
|
||||
description: "Create a new issue using an interactive form"
|
||||
description: "Create a new issue using an interactive terminal form."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -53,10 +53,9 @@ bd create [title] [flags]
|
|||
--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")
|
||||
-t, --type string Issue type (bug|feature|task|epic|chore|decision); 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")
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd defer"
|
||||
description: "Defer one or more issues for later"
|
||||
description: "Defer issues to put them on ice for later."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd delete"
|
||||
description: "Delete one or more issues and clean up references"
|
||||
description: "Delete one or more issues and clean up all references to them."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd dep"
|
||||
description: "Manage dependencies"
|
||||
description: "Manage dependencies between issues."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -21,7 +21,6 @@ Examples:
|
|||
|
||||
```
|
||||
bd dep [issue-id] [flags]
|
||||
bd dep [command]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd diff"
|
||||
description: "Show changes between two commits or branches"
|
||||
description: "Show the differences in issues between two commits or branches."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd doctor"
|
||||
description: "Check and fix beads installation health (start here)"
|
||||
description: "Sanity check the beads installation for the current directory or specified path."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd dolt"
|
||||
description: "Configure Dolt database settings"
|
||||
description: "Configure and manage Dolt database settings and server lifecycle."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -50,7 +50,7 @@ Examples:
|
|||
bd dolt test
|
||||
|
||||
```
|
||||
bd dolt [command]
|
||||
bd dolt [flags]
|
||||
```
|
||||
|
||||
## bd dolt clean-databases
|
||||
|
|
@ -58,7 +58,7 @@ bd dolt [command]
|
|||
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_*
|
||||
Stale database prefixes: testdb_*, doctest_*, doctortest_*, beads_pt*, beads_vr*, beads_t*
|
||||
|
||||
These waste server memory and can degrade performance under concurrent load.
|
||||
Use --dry-run to see what would be dropped without actually dropping.
|
||||
|
|
@ -169,7 +169,7 @@ Subcommands:
|
|||
remove <name> Remove a remote
|
||||
|
||||
```
|
||||
bd dolt remote [command]
|
||||
bd dolt remote [flags]
|
||||
```
|
||||
|
||||
### bd dolt remote add
|
||||
|
|
@ -180,12 +180,6 @@ 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
|
||||
|
|
@ -260,10 +254,10 @@ 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.
|
||||
managed servers — either 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]
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd duplicate"
|
||||
description: "Mark an issue as a duplicate of another"
|
||||
description: "Mark an issue as a duplicate of a canonical issue."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd duplicates"
|
||||
description: "Find and optionally merge duplicate issues"
|
||||
description: "Find issues with identical content (title, description, design, acceptance criteria)."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd edit"
|
||||
description: "Edit an issue field in $EDITOR"
|
||||
description: "Edit an issue field using your configured $EDITOR."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ Generated from `bd help --doc epic`.
|
|||
Epic management commands
|
||||
|
||||
```
|
||||
bd epic [command]
|
||||
bd epic [flags]
|
||||
```
|
||||
|
||||
## bd epic close-eligible
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd export"
|
||||
description: "Export issues to JSONL format"
|
||||
description: "Export all issues to JSONL (newline-delimited JSON) format."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -39,11 +39,9 @@ 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
|
||||
--all Include all records (infra, templates, gates, memories)
|
||||
--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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd federation"
|
||||
description: "Manage peer-to-peer federation (requires CGO)"
|
||||
description: "Federation commands require CGO and the Dolt storage backend."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd find-duplicates"
|
||||
description: "Find semantically similar issues using text analysis or AI"
|
||||
description: "Find issues that are semantically similar but not exact duplicates."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd flatten"
|
||||
description: "Squash all Dolt history into a single commit"
|
||||
description: "Nuclear option: squash ALL Dolt commit history into a single commit."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd forget"
|
||||
description: "Remove a persistent memory"
|
||||
description: "Remove a memory by its key."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd formula"
|
||||
description: "Manage workflow formulas"
|
||||
description: "Manage workflow formulas - the source layer for molecule templates."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -19,19 +19,11 @@ Search paths (in order):
|
|||
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
|
||||
docs/workflows/formulas.md # narrative reference
|
||||
list List available formulas from all search paths
|
||||
show Show formula details, steps, and composition rules
|
||||
|
||||
```
|
||||
bd formula [command]
|
||||
bd formula [flags]
|
||||
```
|
||||
|
||||
## bd formula convert
|
||||
|
|
@ -77,9 +69,6 @@ Search paths (in order of priority):
|
|||
|
||||
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
|
||||
|
|
@ -96,30 +85,6 @@ bd formula list [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.
|
||||
|
|
@ -131,9 +96,6 @@ Displays:
|
|||
- 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd gate"
|
||||
description: "Manage async coordination gates"
|
||||
description: "Gates are async wait conditions that block workflow steps."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -17,11 +17,9 @@ Gate types:
|
|||
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 another bead to close (Phase 4)
|
||||
bead - Waits for cross-rig bead to close (Phase 4)
|
||||
|
||||
For bead gates, await_id is a bead ID in this rig's database (e.g., "bd-abc123").
|
||||
The historical cross-rig form <rig>:<bead-id> can no longer be evaluated
|
||||
(multi-rig routing removed) and stays pending until resolved manually.
|
||||
For bead gates, await_id format is <rig>:<bead-id> (e.g., "other-project:op-abc123").
|
||||
|
||||
Examples:
|
||||
bd gate list # Show all open gates
|
||||
|
|
@ -31,7 +29,7 @@ Examples:
|
|||
bd gate resolve <id> # Close a gate manually
|
||||
|
||||
```
|
||||
bd gate [command]
|
||||
bd gate [flags]
|
||||
```
|
||||
|
||||
## bd gate add-waiter
|
||||
|
|
@ -163,16 +161,12 @@ bd gate discover [flags]
|
|||
|
||||
## bd gate list
|
||||
|
||||
List gate issues.
|
||||
|
||||
With no argument, lists all gate issues in the current beads database.
|
||||
With an [issue-id] argument, lists ONLY the gates that block that issue
|
||||
(its own dependency gates) — not every gate in the database.
|
||||
List all gate issues in the current beads database.
|
||||
|
||||
By default, shows only open gates. Use --all to include closed gates.
|
||||
|
||||
```
|
||||
bd gate list [issue-id] [flags]
|
||||
bd gate list [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd gc"
|
||||
description: "Garbage collect: decay old issues, compact Dolt commits, run Dolt GC"
|
||||
description: "Full lifecycle garbage collection for standalone Beads databases."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd github"
|
||||
description: "GitHub integration commands"
|
||||
description: "Commands for syncing issues between beads and GitHub."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -17,7 +17,7 @@ Configuration can be set via 'bd config' or environment variables:
|
|||
github.url / GITHUB_API_URL - Custom API URL (GitHub Enterprise)
|
||||
|
||||
```
|
||||
bd github [command]
|
||||
bd github [flags]
|
||||
```
|
||||
|
||||
## bd github pull
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd gitlab"
|
||||
description: "GitLab integration commands"
|
||||
description: "Commands for syncing issues between beads and GitLab."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -17,7 +17,7 @@ Configuration can be set via 'bd config' or environment variables:
|
|||
gitlab.default_project_id / GITLAB_DEFAULT_PROJECT_ID - Project for creating issues in group mode
|
||||
|
||||
```
|
||||
bd gitlab [command]
|
||||
bd gitlab [flags]
|
||||
```
|
||||
|
||||
## bd gitlab projects
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd graph"
|
||||
description: "Display issue dependency graph"
|
||||
description: "Display a visualization of an issue's dependency graph."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -13,7 +13,6 @@ 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.
|
||||
With --open, filters to only open/actionable issues (compact layer format).
|
||||
|
||||
Display formats:
|
||||
(default) DAG with columns and box-drawing edges (terminal-native)
|
||||
|
|
@ -21,7 +20,6 @@ Display formats:
|
|||
--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
|
||||
--open Open issues only, compact layers (LLM-friendly)
|
||||
|
||||
The graph shows execution order:
|
||||
- Layer 0 / leftmost = no dependencies (can start immediately)
|
||||
|
|
@ -37,12 +35,9 @@ Examples:
|
|||
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 --open issue-id # Open issues only, layered by blocking order
|
||||
bd graph --all --open # All open issues, compact layers
|
||||
|
||||
```
|
||||
bd graph [issue-id] [flags]
|
||||
bd graph [command]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
|
@ -53,7 +48,6 @@ bd graph [command]
|
|||
--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)
|
||||
--open Show only open issues (filters out closed/deferred), forces compact layer format
|
||||
```
|
||||
|
||||
## bd graph check
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd history"
|
||||
description: "Show version history for an issue"
|
||||
description: "Show the complete version history of an issue, including all commits"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -13,7 +13,6 @@ where the issue was modified.
|
|||
Examples:
|
||||
bd history bd-123 # Show all history for issue bd-123
|
||||
bd history bd-123 --limit 5 # Show last 5 changes
|
||||
bd history bd-123 --events # Show database audit events
|
||||
|
||||
```
|
||||
bd history <id> [flags]
|
||||
|
|
@ -22,6 +21,5 @@ bd history <id> [flags]
|
|||
**Flags:**
|
||||
|
||||
```
|
||||
--events Show database audit events instead of commit snapshots
|
||||
--limit int Limit number of history entries (0 = all)
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd hooks"
|
||||
description: "Manage git hooks for beads integration"
|
||||
description: "Install, uninstall, or list git hooks for beads integration."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -17,7 +17,7 @@ The hooks provide:
|
|||
- prepare-commit-msg: Add agent identity trailers for forensics
|
||||
|
||||
```
|
||||
bd hooks [command]
|
||||
bd hooks [flags]
|
||||
```
|
||||
|
||||
## bd hooks install
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd human"
|
||||
description: "Show essential commands for human users"
|
||||
description: "Display a focused help menu showing only the most common commands."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -22,7 +22,6 @@ SUBCOMMANDS:
|
|||
|
||||
```
|
||||
bd human [flags]
|
||||
bd human [command]
|
||||
```
|
||||
|
||||
## bd human dismiss
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd import"
|
||||
description: "Import issues from a JSONL file or stdin into the database"
|
||||
description: "Import issues from a JSONL file (newline-delimited JSON) into the database."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -7,32 +7,12 @@ description: Generated reference for every bd command
|
|||
|
||||
Generated from `bd help --docs-root`.
|
||||
|
||||
This reference covers all 112 live top-level `bd` commands. Regenerate it with:
|
||||
This reference covers all 108 live top-level `bd` commands. Regenerate it with:
|
||||
|
||||
```bash
|
||||
./scripts/generate-cli-docs.sh
|
||||
```
|
||||
|
||||
## Global Flags
|
||||
|
||||
These flags apply to all commands:
|
||||
|
||||
```
|
||||
--actor string Actor name for audit trail (default: $BEADS_ACTOR, git user.name, $USER)
|
||||
--db string Database path (default: auto-discover .beads/*.db)
|
||||
-C, --directory string Change to this directory before running the command (like git -C)
|
||||
--dolt-auto-commit string Dolt auto-commit policy (off|on|batch). 'on': commit after each write. 'batch': defer commits to bd dolt commit; uncommitted changes persist in the working set until then. SIGTERM/SIGHUP flush pending batch commits. Default: off. Override via config key dolt.auto-commit
|
||||
--global Use the global shared-server database (beads_global)
|
||||
--ignore-schema-skew Proceed despite forward schema drift (some queries may fail)
|
||||
--json Output in JSON format
|
||||
--no-color Disable color output (also: NO_COLOR=1 or CLICOLOR=0)
|
||||
--profile Generate CPU profile for performance analysis
|
||||
-q, --quiet Suppress non-essential output (errors only)
|
||||
--readonly Read-only mode: block write operations (for worker sandboxes)
|
||||
--sandbox Sandbox mode: disables Dolt auto-push
|
||||
-v, --verbose Enable verbose/debug output
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
- [`bd admin`](/cli-reference/admin)
|
||||
|
|
@ -77,7 +57,6 @@ These flags apply to all commands:
|
|||
- [`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)
|
||||
|
|
@ -97,7 +76,6 @@ These flags apply to all commands:
|
|||
- [`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)
|
||||
|
|
@ -115,7 +93,6 @@ These flags apply to all commands:
|
|||
- [`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)
|
||||
|
|
@ -139,7 +116,6 @@ These flags apply to all commands:
|
|||
- [`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)
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd info"
|
||||
description: "Show database information"
|
||||
description: "Display information about the current database."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd init-safety"
|
||||
description: "Explain bd init flag semantics and the destroy-token format"
|
||||
description: "bd init flag safety contract."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -59,7 +59,7 @@ DESTROY-TOKEN (non-interactive only)
|
|||
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
|
||||
engdocs/adr/0002-init-safety-invariants.md).
|
||||
docs/adr/0002-init-safety-invariants.md).
|
||||
|
||||
EXIT CODES
|
||||
|
||||
|
|
@ -71,7 +71,7 @@ EXIT CODES
|
|||
|
||||
RECOVERY
|
||||
|
||||
If you hit a refusal, see docs/recovery/init-safety.md for step-by-step recovery
|
||||
If you hit a refusal, see docs/RECOVERY.md for step-by-step recovery
|
||||
playbooks for each exit code.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd init"
|
||||
description: "Initialize bd in the current directory"
|
||||
description: "Initialize bd in the current directory by creating a .beads/ directory"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -8,11 +8,10 @@ description: "Initialize bd in the current directory"
|
|||
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.
|
||||
and Dolt database. 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/architecture/storage-backends.md for the trade-offs and setup.
|
||||
Dolt is the default (and only supported) storage backend. The legacy SQLite
|
||||
backend has been removed. Use --backend=sqlite to see migration instructions.
|
||||
|
||||
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)
|
||||
|
|
@ -49,56 +48,46 @@ 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/architecture/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/dolt
|
||||
--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-ca-cert-path string [EXPERIMENTAL] Absolute path to a CA certificate (PEM) used to verify the externally-managed dolt sql-server. Empty uses the system trust store. Relative paths are rejected.
|
||||
--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-tls-server-name string [EXPERIMENTAL] Server name to verify in the external dolt sql-server's TLS certificate. Defaults to the external host. Required with a unix socket unless --proxied-server-external-tls-skip-verify is set.
|
||||
--proxied-server-external-tls-skip-verify [EXPERIMENTAL] Skip TLS certificate verification for the external dolt sql-server. Insecure; testing only.
|
||||
--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>/dolt/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>/dolt. 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
|
||||
--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 (default: dolt). --backend=sqlite prints deprecation notice.
|
||||
--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)
|
||||
--non-interactive Skip all interactive prompts (auto-detected in CI or non-TTY environments)
|
||||
-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-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-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 setup generation
|
||||
--skip-hooks Skip git hooks installation
|
||||
--stealth Enable stealth mode: global gitattributes and gitignore, no local repo tracking
|
||||
--team Run team workflow setup wizard
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd jira"
|
||||
description: "Jira integration commands"
|
||||
description: "Synchronize issues between beads and Jira."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -31,7 +31,7 @@ Examples:
|
|||
bd jira status # Show sync status
|
||||
|
||||
```
|
||||
bd jira [command]
|
||||
bd jira [flags]
|
||||
```
|
||||
|
||||
## bd jira pull
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd kv"
|
||||
description: "Key-value store commands"
|
||||
description: "Commands for working with the beads key-value store."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -19,7 +19,7 @@ Examples:
|
|||
bd kv list # List all key-value pairs
|
||||
|
||||
```
|
||||
bd kv [command]
|
||||
bd kv [flags]
|
||||
```
|
||||
|
||||
## bd kv clear
|
||||
|
|
|
|||
|
|
@ -10,15 +10,15 @@ Generated from `bd help --doc label`.
|
|||
Manage issue labels
|
||||
|
||||
```
|
||||
bd label [command]
|
||||
bd label [flags]
|
||||
```
|
||||
|
||||
## bd label add
|
||||
|
||||
Add labels to issues. Issue IDs come first; the final argument is the label. Pass multiple labels comma-separated: bd label add bd-123 label1,label2
|
||||
Add a label to one or more issues
|
||||
|
||||
```
|
||||
bd label add [issue-id...] [label[,label...]] [flags]
|
||||
bd label add [issue-id...] [label] [flags]
|
||||
```
|
||||
|
||||
## bd label list
|
||||
|
|
@ -47,8 +47,8 @@ bd label propagate [parent-id] [label] [flags]
|
|||
|
||||
## bd label remove
|
||||
|
||||
Remove labels from issues. Issue IDs come first; the final argument is the label. Pass multiple labels comma-separated: bd label remove bd-123 label1,label2
|
||||
Remove a label from one or more issues
|
||||
|
||||
```
|
||||
bd label remove [issue-id...] [label[,label...]] [flags]
|
||||
bd label remove [issue-id...] [label] [flags]
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd linear"
|
||||
description: "Linear integration commands"
|
||||
description: "Synchronize issues between beads and Linear."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -70,7 +70,7 @@ Examples:
|
|||
bd linear status # Show sync status
|
||||
|
||||
```
|
||||
bd linear [command]
|
||||
bd linear [flags]
|
||||
```
|
||||
|
||||
## bd linear pull
|
||||
|
|
@ -151,18 +151,6 @@ Type Filtering (--push only):
|
|||
--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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd link"
|
||||
description: "Link two issues with a dependency"
|
||||
description: "Link two issues with a dependency."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd lint"
|
||||
description: "Check issues for missing template sections"
|
||||
description: "Check issues for missing recommended sections based on issue type."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -15,7 +15,7 @@ Section requirements by type:
|
|||
bug: Steps to Reproduce, Acceptance Criteria
|
||||
task: Acceptance Criteria
|
||||
feature: Acceptance Criteria
|
||||
epic: Success Criteria (or Acceptance Criteria)
|
||||
epic: Success Criteria
|
||||
chore: (none)
|
||||
|
||||
Examples:
|
||||
|
|
@ -34,5 +34,5 @@ bd lint [issue-id...] [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)
|
||||
-t, --type string Filter by issue type (bug, task, feature, epic)
|
||||
```
|
||||
|
|
|
|||
|
|
@ -31,8 +31,6 @@ bd list [flags]
|
|||
--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)
|
||||
--external-contains string Filter by external ref substring (case-insensitive)
|
||||
--external-ref string Filter by exact external_ref value
|
||||
--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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd mail"
|
||||
description: "Delegate to mail provider (e.g., gt mail)"
|
||||
description: "Delegates mail operations to an external mail provider."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd memories"
|
||||
description: "List or search persistent memories"
|
||||
description: "List all memories, or search by keyword."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd merge-slot"
|
||||
description: "Manage merge-slot gates for serialized conflict resolution"
|
||||
description: "Merge-slot gates serialize conflict resolution in the merge queue."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -27,7 +27,7 @@ Examples:
|
|||
bd merge-slot release # Release the slot
|
||||
|
||||
```
|
||||
bd merge-slot [command]
|
||||
bd merge-slot [flags]
|
||||
```
|
||||
|
||||
## bd merge-slot acquire
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd metrics"
|
||||
description: "Show or change anonymous usage-metrics settings"
|
||||
description: "Show whether anonymous usage metrics are on, see exactly what is sent, and"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -22,7 +22,6 @@ any user-supplied text.
|
|||
|
||||
```
|
||||
bd metrics [flags]
|
||||
bd metrics [command]
|
||||
```
|
||||
|
||||
## bd metrics example
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd migrate"
|
||||
description: "Database migration commands"
|
||||
description: "Database migration and data transformation commands."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -12,125 +12,26 @@ 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
|
||||
from-server-to-proxied-server [EXPERIMENTAL] Switch server mode to proxied-server mode
|
||||
from-proxied-server-to-server [EXPERIMENTAL] Switch proxied-server mode to server mode
|
||||
from-shared-server-to-proxied-server [EXPERIMENTAL] Switch shared-server mode to proxied-server mode
|
||||
from-proxied-server-to-shared-server [EXPERIMENTAL] Switch proxied-server mode to shared-server mode
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
|
||||
```
|
||||
bd migrate [flags]
|
||||
bd migrate [command]
|
||||
```
|
||||
|
||||
**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 from-proxied-server-to-server
|
||||
|
||||
Switch a repo from proxied-server mode to server mode (bd init --server).
|
||||
|
||||
Both modes root their dolt sql-server at the same .beads/dolt directory, so this
|
||||
only rewrites .beads/metadata.json (dolt_mode) and removes the proxied-server
|
||||
sidecar — no Dolt data is copied or moved. Stop the running proxy first with
|
||||
'bd dolt stop'.
|
||||
|
||||
Note: dolt_mode lives in the committed metadata.json, so this change propagates
|
||||
to clones on the next push.
|
||||
|
||||
```
|
||||
bd migrate from-proxied-server-to-server [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--dry-run Show what would be done without making changes
|
||||
```
|
||||
|
||||
## bd migrate from-proxied-server-to-shared-server
|
||||
|
||||
Switch a repo from proxied-server mode back to shared-server mode.
|
||||
|
||||
Only applies to a proxied-server repo rooted at the shared dolt directory
|
||||
(~/.beads/shared-server/dolt) — the reverse of from-shared-server-to-proxied-server.
|
||||
This rewrites .beads/metadata.json (dolt_mode), re-enables dolt.shared-server, and
|
||||
removes the proxied-server sidecar; no Dolt data is copied or moved. Stop the
|
||||
running proxy first with 'bd dolt stop'.
|
||||
|
||||
```
|
||||
bd migrate from-proxied-server-to-shared-server [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--dry-run Show what would be done without making changes
|
||||
```
|
||||
|
||||
## bd migrate from-server-to-proxied-server
|
||||
|
||||
Switch a repo from server mode (bd init --server) to proxied-server mode.
|
||||
|
||||
Both modes root their dolt sql-server at the same .beads/dolt directory, so this
|
||||
only rewrites .beads/metadata.json (dolt_mode) and writes the proxied-server
|
||||
sidecar — no Dolt data is copied or moved. Stop the running server first with
|
||||
'bd dolt stop'.
|
||||
|
||||
Note: dolt_mode lives in the committed metadata.json, so this change propagates
|
||||
to clones on the next push.
|
||||
|
||||
```
|
||||
bd migrate from-server-to-proxied-server [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--dry-run Show what would be done without making changes
|
||||
--idle-timeout duration Proxy idle timeout; omit for the 30s default, 0 for indefinite uptime
|
||||
```
|
||||
|
||||
## bd migrate from-shared-server-to-proxied-server
|
||||
|
||||
Switch a repo from shared-server mode to proxied-server mode.
|
||||
|
||||
The proxied server is rooted at the shared dolt directory
|
||||
(~/.beads/shared-server/dolt), so no Dolt data is copied or moved; this rewrites
|
||||
.beads/metadata.json (dolt_mode), turns off dolt.shared-server for this repo, and
|
||||
writes the proxied-server sidecar. Stop the running shared server first with
|
||||
'bd dolt stop' — note that stops it for every project sharing it.
|
||||
|
||||
```
|
||||
bd migrate from-shared-server-to-proxied-server [flags]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
||||
```
|
||||
--dry-run Show what would be done without making changes
|
||||
--idle-timeout duration Proxy idle timeout; omit for the 30s default, 0 for indefinite uptime
|
||||
```
|
||||
|
||||
## bd migrate hooks
|
||||
|
||||
Analyze git hook files and sidecar artifacts for migration to marker-managed format.
|
||||
|
|
@ -221,8 +122,7 @@ 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
|
||||
--json Output in JSON format
|
||||
```
|
||||
|
||||
## bd migrate sync
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd mol"
|
||||
description: "Molecule commands (work templates)"
|
||||
description: "Manage molecules - work templates for agent workflows."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -31,7 +31,7 @@ Commands:
|
|||
Use "bd formula list" to list available formulas.
|
||||
|
||||
```
|
||||
bd mol [command]
|
||||
bd mol [flags]
|
||||
```
|
||||
|
||||
**Aliases:** protomolecule
|
||||
|
|
@ -238,8 +238,7 @@ bd mol last-activity <molecule-id> [flags]
|
|||
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 is stored as persistent beads in the issue database and
|
||||
syncs like any other bead (bd dolt push / pull).
|
||||
The resulting mol lives in .beads/ (permanent storage) and is synced with git.
|
||||
|
||||
Phase transition: Proto (solid) -> pour -> Mol (liquid)
|
||||
|
||||
|
|
@ -319,12 +318,6 @@ Examples:
|
|||
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.
|
||||
|
|
@ -492,7 +485,6 @@ Subcommands:
|
|||
|
||||
```
|
||||
bd mol wisp [proto-id] [flags]
|
||||
bd mol wisp [command]
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd note"
|
||||
description: "Append a note to an issue"
|
||||
description: "Append a note to an issue's notes field."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd notion"
|
||||
description: "Notion integration commands"
|
||||
description: "Commands for syncing issues between beads and Notion."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -10,7 +10,7 @@ Generated from `bd help --doc notion`.
|
|||
Commands for syncing issues between beads and Notion.
|
||||
|
||||
```
|
||||
bd notion [command]
|
||||
bd notion [flags]
|
||||
```
|
||||
|
||||
## bd notion connect
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd onboard"
|
||||
description: "Display minimal snippet for agent instructions file"
|
||||
description: "Display a minimal snippet to add to your agent instructions file for bd integration."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd orphans"
|
||||
description: "Identify orphaned issues (referenced in commits but still open)"
|
||||
description: "Identify orphaned issues - issues that are referenced in commit messages but remain open or in_progress in the database."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd ping"
|
||||
description: "Check database connectivity"
|
||||
description: "Lightweight health check that confirms bd can reach its database."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd preflight"
|
||||
description: "Show PR readiness checklist"
|
||||
description: "Display a checklist of common pre-PR checks for contributors."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -32,7 +32,7 @@ bd preflight [flags]
|
|||
|
||||
```
|
||||
--check Run checks automatically
|
||||
--fix Auto-fix issues where possible (vendorHash, version sync)
|
||||
--fix Auto-fix issues where possible (not yet implemented)
|
||||
--json Output results as JSON
|
||||
--skip-lint Skip lint check explicitly
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd prime"
|
||||
description: "Output AI-optimized workflow context"
|
||||
description: "Output essential Beads workflow context in AI-optimized markdown format."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -20,28 +20,11 @@ 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/getting-started/ide-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 workflow text. Persistent memories (from bd remember) are still appended so memory injection keeps working under a custom template.
|
||||
- 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; this returns only the memories section even when a custom PRIME.md is present.
|
||||
- Use --no-memories to omit the persistent memories section (useful when the memories section is large and would dominate a context budget). --memories-only takes precedence if both are set.
|
||||
|
||||
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.
|
||||
- Use --memories-only for hook contexts that should inject only persistent memories.
|
||||
|
||||
```
|
||||
bd prime [flags]
|
||||
|
|
@ -50,13 +33,10 @@ 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
|
||||
--no-memories Omit the persistent memories section (ignored when --memories-only is set, which wins)
|
||||
--stealth Stealth mode (no git operations, flush only)
|
||||
--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)
|
||||
--mcp Force MCP mode (minimal output)
|
||||
--memories-only Output only persistent memories for compact hook contexts
|
||||
--stealth Stealth mode (no git operations, flush only)
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd priority"
|
||||
description: "Set the priority of an issue"
|
||||
description: "Set the priority of an issue."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd promote"
|
||||
description: "Promote a wisp to a permanent bead"
|
||||
description: "Promote a wisp (ephemeral issue) to a permanent bead."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd prune"
|
||||
description: "Delete old closed beads to reclaim space and shrink exports"
|
||||
description: "Permanently delete closed non-ephemeral beads and their associated data."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -20,12 +20,6 @@ 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.
|
||||
|
||||
|
|
@ -48,7 +42,6 @@ bd prune [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-*')
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd purge"
|
||||
description: "Delete closed ephemeral beads to reclaim space"
|
||||
description: "Permanently delete closed ephemeral beads and their associated data."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd q"
|
||||
description: "Quick capture: create issue and output only ID"
|
||||
description: "Quick capture creates an issue and outputs only the issue ID."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -14,7 +14,6 @@ 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]
|
||||
|
|
@ -24,7 +23,6 @@ bd q [title] [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")
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd query"
|
||||
description: "Query issues using a simple query language"
|
||||
description: "Query issues using a simple query language that supports compound filters,"
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd quickstart"
|
||||
description: "Quick start guide for bd"
|
||||
description: "Display a quick start guide showing common bd workflows and patterns."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd ready"
|
||||
description: "Show ready work (open, no active blockers)"
|
||||
description: "Show ready work (open issues with no active blockers)."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd recall"
|
||||
description: "Retrieve a specific memory"
|
||||
description: "Retrieve the full content of a memory by its key."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd recompute-blocked"
|
||||
description: "Recompute is_blocked for all issues (repairs stale flags after a pull)"
|
||||
description: "Recompute the denormalized is_blocked flag for every issue and wisp."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd remember"
|
||||
description: "Store a persistent memory"
|
||||
description: "Store a memory that persists across sessions and account rotations."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd rename-prefix"
|
||||
description: "Rename the issue prefix for all issues in the database"
|
||||
description: "Rename the issue prefix for all issues in the database."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd rename"
|
||||
description: "Rename an issue ID"
|
||||
description: "Rename an issue from one ID to another."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd reopen"
|
||||
description: "Reopen one or more closed issues"
|
||||
description: "Reopen closed issues by setting status to 'open' and clearing the closed_at timestamp."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd repo"
|
||||
description: "Manage multiple repository configuration"
|
||||
description: "Configure and manage multiple repository support for multi-repo hydration."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -28,7 +28,7 @@ Examples:
|
|||
bd repo sync # Sync from all configured repos
|
||||
|
||||
```
|
||||
bd repo [command]
|
||||
bd repo [flags]
|
||||
```
|
||||
|
||||
## bd repo add
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd restore"
|
||||
description: "Restore the pre-compaction content of a compacted issue"
|
||||
description: "Restore the pre-compaction content of a compacted issue."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ Generated from `bd help --doc rules`.
|
|||
Audit and compact Claude rules
|
||||
|
||||
```
|
||||
bd rules [command]
|
||||
bd rules [flags]
|
||||
```
|
||||
|
||||
## bd rules audit
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd search"
|
||||
description: "Search issues by text query"
|
||||
description: "Search issues across title and ID (excludes closed issues by default)."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd set-state"
|
||||
description: "Set operational state (creates event + updates label)"
|
||||
description: "Atomically set operational state on an issue."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd setup"
|
||||
description: "Setup integration with AI editors"
|
||||
description: "Setup integration files for AI editors and coding assistants."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -13,8 +13,7 @@ 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 cursor # Install Cursor IDE integration
|
||||
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
|
||||
|
|
@ -38,7 +37,7 @@ bd setup [recipe] [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)
|
||||
--global Install globally (claude/codex/mux; writes to ~/.claude/settings.json, $CODEX_HOME/AGENTS.md or ~/.codex/AGENTS.md, or ~/.mux/AGENTS.md)
|
||||
--list List all available recipes
|
||||
-o, --output string Write template to custom path
|
||||
--print Print the template to stdout
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd ship"
|
||||
description: "Publish a capability for cross-project dependencies"
|
||||
description: "Ship a capability to satisfy cross-project dependencies."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd sql"
|
||||
description: "Execute raw SQL against the beads database"
|
||||
description: "Execute a raw SQL query against the underlying database (SQLite or Dolt)."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd stale"
|
||||
description: "Show stale issues (not updated recently)"
|
||||
description: "Show issues that haven't been updated recently and may need attention."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd state"
|
||||
description: "Query the current value of a state dimension"
|
||||
description: "Query the current value of a state dimension from an issue's labels."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -23,7 +23,6 @@ Examples:
|
|||
|
||||
```
|
||||
bd state <issue-id> <dimension> [flags]
|
||||
bd state [command]
|
||||
```
|
||||
|
||||
## bd state list
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd status"
|
||||
description: "Show issue database overview and statistics"
|
||||
description: "Show a quick snapshot of the issue database state and statistics."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd statuses"
|
||||
description: "List valid issue statuses"
|
||||
description: "List all valid issue statuses and their categories."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd supersede"
|
||||
description: "Mark an issue as superseded by a newer one"
|
||||
description: "Mark an issue as superseded by a newer version."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "bd swarm"
|
||||
description: "Swarm management for structured epics"
|
||||
description: "Swarm management commands for coordinating parallel work on epics."
|
||||
---
|
||||
|
||||
{/* AUTO-GENERATED: do not edit manually */}
|
||||
|
|
@ -13,7 +13,7 @@ A swarm is a structured body of work defined by an epic and its children,
|
|||
with dependencies forming a DAG (directed acyclic graph) of work.
|
||||
|
||||
```
|
||||
bd swarm [command]
|
||||
bd swarm [flags]
|
||||
```
|
||||
|
||||
## bd swarm create
|
||||
|
|
|
|||
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