* test(cmd/bd): pin the command tree and representative --help output Add two in-process goldens for the bd command surface, so any added, removed, hidden or reworded command or flag fails until the goldens are regenerated and shows up as a reviewed testdata diff: - TestCommandTreeGolden walks the whole cobra tree (hidden commands included) and records, per command, Use, Aliases, Short, Long, Example, group, hidden/deprecated state, runnability and annotations, plus every local and persistent flag it defines (name, shorthand, type, default, usage, hidden, deprecation, annotations). Output is sorted and rendered twice to prove it is deterministic. - TestCommandHelpGolden runs `bd <cmd> --help` through rootCmd for root, create, show, list, update, close, version, versions, config and serve. --help returns before the root pre-run, so no store is opened; color escapes are stripped. The snapshots are byte-identical to a built bd binary's --help output. Both run from a fresh ordinary (dependency-mode) workspace: a .beads/metadata.json with no graph marker and no database behind it. The tree is primed the way the binary is (main()'s help command and its --all/--doc/--list/--docs-root flags, ExecuteC's completion command), and cobra's history-dependent pieces (the lazily added per-command --help flag, the __complete request commands) are excluded, so the result does not depend on which in-process tests ran first. The help runs reset every flag afterwards so a later in-process command does not inherit --help. docs/cli-docs.pin holds check-doc-flags at the v1.2.2 release, so drift on main is not caught there; these goldens are the live guard. They pin the cgo build (the !cgo build swaps in a federation stub). Regenerate with BD_UPDATE_GOLDEN=1 go test -tags gms_pure_go ./cmd/bd -run '^TestCommand(Tree|Help)Golden$'. Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> * test(cmd/bd): keep the command goldens from merging flags into the shared tree TestCommandTreeGolden read each command's flags through LocalNonPersistentFlags, and TestCommandHelpGolden dispatches `bd serve --help`. Both run cobra's mergePersistentFlags, which copies every inherited persistent flag (--json, --db, ...) into the command's own flag set for the rest of the process. TestServeFlags pins serveCmd's exact flag set, so it failed whenever a golden test ran before it in the same test binary: tree then serve flags, help then serve flags, and -test.shuffle seeds 2 and 3, on the PR head and on its merge with main. CI passes only because bd_test's 16 Bazel shards happen to run them in different processes. Of 37 candidate tests, TestServeFlags is the only one affected. - goldenLocalFlags reads the set LocalNonPersistentFlags reports without calling it: c.Flags() minus c's own persistent flags and minus inherited copies. Like cobra, it treats a flag as inherited only if it is the nearest ancestor's own *pflag.Flag, so copies left by an earlier in-process execution are skipped and a flag that shadows an inherited one still renders. - TestCommandTreeGolden fails if rendering changes the number of flags in any command's flag set. - TestCommandHelpGolden calls restoreServeGlobals, which re-registers serveCmd's flags after the `bd serve --help` dispatch. Review minors: - The regeneration command (doc comment, failure-message constant, tree.golden header) sets CGO_ENABLED=1. Without cgo the file does not build, so the command matches no test and exits 0. - enterOrdinaryWorkspaceForGolden calls isolateBeadsDirForTest. - renderCommandHelpGolden's comment says when the ANSI strip matters. - cmd/bd/AGENTS.md lists the goldens under "Adding a command" and "Guard tests". Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Co-authored-by: Eddie the Engineer <338826946+gascity-eddie[bot]@users.noreply.github.com>
163 lines
9.6 KiB
Text
163 lines
9.6 KiB
Text
Issues chained together like beads. A lightweight issue tracker with first-class dependency support.
|
|
|
|
Usage:
|
|
bd [flags]
|
|
bd [command]
|
|
|
|
Working With Issues:
|
|
assign Assign an issue to someone
|
|
children List child beads of a parent
|
|
close Close one or more issues
|
|
comment Add a comment to an issue
|
|
comments View or manage comments on an issue
|
|
create Create a new issue (or batch from markdown/graph JSON)
|
|
create-form Create a new issue using an interactive form
|
|
delete Delete one or more issues and clean up references
|
|
edit Edit an issue field in $EDITOR
|
|
gate Manage async coordination gates
|
|
heartbeat Refresh the lease on an issue you hold in_progress
|
|
label Manage issue labels
|
|
link Link two issues with a dependency
|
|
list List issues
|
|
merge-slot Manage merge-slot gates for serialized conflict resolution
|
|
note Append a note to an issue
|
|
priority Set the priority of an issue
|
|
promote Promote a wisp to a permanent bead
|
|
provenance Append-only provenance event log
|
|
q Quick capture: create issue and output only ID
|
|
query Query issues using a simple query language
|
|
reclaim Revert stale-lease in_progress issues back to ready (dead-worker recovery)
|
|
reopen Reopen one or more closed issues
|
|
search Search issues by text query
|
|
set-state Set operational state (creates event + updates label)
|
|
show Show issue details
|
|
state Query the current value of a state dimension
|
|
tag Add a label to an issue
|
|
todo Manage TODO items (convenience wrapper for task issues)
|
|
unclaim Release a claimed issue
|
|
update Update one or more issues
|
|
|
|
Views & Reports:
|
|
count Count issues matching filters
|
|
diff Show changes between two commits or branches
|
|
find-duplicates Find semantically similar issues using text analysis or AI
|
|
history Show version history for an issue
|
|
lint Check issues for missing template sections
|
|
stale Show stale issues (not updated recently)
|
|
status Show issue database overview and statistics
|
|
statuses List valid issue statuses
|
|
types List valid issue types
|
|
versions List the recorded versions of a bead
|
|
|
|
Dependencies & Structure:
|
|
dep Manage dependencies
|
|
duplicate Mark an issue as a duplicate of another
|
|
duplicates Find and optionally merge duplicate issues
|
|
epic Epic management commands
|
|
graph Display issue dependency graph
|
|
supersede Mark an issue as superseded by a replacement issue
|
|
swarm Swarm management for structured epics
|
|
|
|
Sync & Data:
|
|
backup Back up your beads database
|
|
branch List or create branches
|
|
conflicts Inspect and resolve live merge conflicts
|
|
export Export issues to JSONL format
|
|
federation Manage peer-to-peer federation with other workspaces
|
|
import Import issues from a JSONL file or stdin into the database
|
|
restore Restore the pre-compaction content of a compacted issue
|
|
sync Pull, check for conflicts, repair is_blocked, and push (the federation loop)
|
|
vc Version control operations
|
|
|
|
Setup & Configuration:
|
|
bootstrap Non-destructive database setup for fresh clones and recovery
|
|
config Manage configuration settings
|
|
connect Attach this workspace to a remote bd serve over HTTP
|
|
context Show effective backend identity and repository context
|
|
dolt Configure Dolt database settings
|
|
forget Remove a persistent memory
|
|
hooks Manage git hooks for beads integration
|
|
human Show essential commands for human users
|
|
info Show database information
|
|
init Initialize bd in the current directory
|
|
kv Key-value store commands
|
|
memories List or search persistent memories
|
|
migrate-personal Move personal planning issues from the project database to your planning repo
|
|
onboard Display minimal snippet for agent instructions file
|
|
prime Output AI-optimized workflow context
|
|
quickstart Quick start guide for bd
|
|
recall Retrieve a specific memory
|
|
remember Store a persistent memory
|
|
setup Setup integration with AI editors
|
|
where Show active beads location
|
|
|
|
Maintenance:
|
|
batch Run multiple write operations in a single database transaction
|
|
compact Squash old Dolt commits to reduce history size
|
|
doctor Check and fix beads installation health (start here)
|
|
events Read and manage the durable events journal
|
|
flatten Squash all Dolt history into a single commit
|
|
gc Garbage collect: decay old issues, compact Dolt commits, run Dolt GC
|
|
migrate Database migration commands
|
|
ping Check database connectivity
|
|
preflight Show PR readiness checklist
|
|
prune Delete old closed beads to reclaim space and shrink exports
|
|
purge Delete closed ephemeral beads to reclaim space
|
|
recompute-blocked Recompute is_blocked for all issues (repairs stale flags after a pull)
|
|
rename-prefix Rename the issue prefix for all issues in the database
|
|
rules Audit and compact Claude rules
|
|
sql Execute raw SQL against the beads database
|
|
upgrade Check and manage bd version upgrades
|
|
worktree Manage git worktrees for parallel development
|
|
|
|
Integrations & Advanced:
|
|
admin Administrative commands for database maintenance
|
|
jira Jira integration commands
|
|
linear Linear integration commands
|
|
repo Manage multiple repository configuration
|
|
|
|
Additional Commands:
|
|
ado Azure DevOps integration commands
|
|
audit Record and label agent interactions (append-only JSONL)
|
|
blocked Show blocked issues
|
|
completion Generate the autocompletion script for the specified shell
|
|
cook Compile a formula into a proto (ephemeral by default)
|
|
defer Defer one or more issues for later
|
|
formula Manage workflow formulas
|
|
github GitHub integration commands
|
|
gitlab GitLab integration commands
|
|
help Help about any command
|
|
init-safety Explain bd init flag semantics and the destroy-token format
|
|
mail Delegate to mail provider (e.g., gt mail)
|
|
metrics Show or change anonymous usage-metrics settings
|
|
mol Molecule commands (work templates)
|
|
notion Notion integration commands
|
|
orphans Identify orphaned issues (referenced in commits but still open)
|
|
ready Show ready work (open, no active blockers)
|
|
rename Rename an issue ID
|
|
schema Print the JSON Schema for bd's --json / export output
|
|
serve Serve the beads HTTP API over loopback
|
|
ship Publish a capability for cross-project dependencies
|
|
undefer Undefer one or more issues (restore to open)
|
|
version Print version information
|
|
|
|
Flags:
|
|
--actor string Actor name for audit trail (default: $BEADS_ACTOR, git user.name, $USER)
|
|
--cpu-profile Generate CPU profile for performance analysis
|
|
--database string Run against a different server database for this invocation, without changing the project's configured database (proxied-server mode only)
|
|
--db string Database path (default: auto-discover .beads/*.db). In proxied-server mode, a value that isn't an existing path is treated as a database name override (see --database)
|
|
-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 (a live batch-mode bd process also flushes on SIGTERM/SIGHUP, except in proxied-server mode, where bd dolt commit is the only flush point). In proxied-server mode the deferral covers the writes the CLI makes on that route, including config and version metadata; explicit commit points (bd batch, bd mol bond/pour/squash, bd mol wisp create, and the wisp half of bd mol burn) still commit, and a bd serve process on the same database is unaffected. Default: on. Override via config key dolt.auto-commit
|
|
--global Use the global shared-server database (beads_global)
|
|
-h, --help help for bd
|
|
--ignore-schema-skew Proceed despite forward schema drift (some queries may fail)
|
|
--json Output in JSON format
|
|
--mem-profile string Write heap profile to FILE on exit (also respects BEADS_MEM_PROFILE)
|
|
--no-color Disable color output (also: NO_COLOR=1 or CLICOLOR=0)
|
|
-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
|
|
-V, --version Print version information
|
|
|
|
Use "bd [command] --help" for more information about a command.
|