# Dolt Backend for Beads Source: https://beads.gascity.com/architecture/dolt How beads uses Dolt for versioned issue storage: embedded vs server mode, remotes, sync, and backups Beads uses Dolt as its storage backend. Dolt provides a version-controlled SQL database with cell-level merge, native branching, and two deployment modes. ## Why Dolt? * **Native version control** — cell-level diffs and merges, not line-based * **Multi-writer support** — server mode enables concurrent agents * **Built-in history** — every write creates a Dolt commit * **Native branching** — Dolt branches independent of git branches * **Single-binary option** — embedded mode for solo users (no server needed) ## Getting Started ### Install Dolt (Server Mode Only) Embedded mode includes everything in the `bd` binary; no separate Dolt install is needed. Install the standalone `dolt` CLI only when you want to run server mode or work directly with the database via `dolt sql`. Install a specific version. Do not install `releases/latest` — see [Which Dolt version to install](#which-dolt-version-to-install) for the version to use and why the pin exists. ```bash theme={null} DOLT_VERSION=2.2.0 # see "Which Dolt version to install" below os=$(uname -s | tr '[:upper:]' '[:lower:]') arch=$(uname -m | sed -e 's/^x86_64$/amd64/' -e 's/^aarch64$/arm64/') curl -fsSL "https://github.com/dolthub/dolt/releases/download/v${DOLT_VERSION}/dolt-${os}-${arch}.tar.gz" \ | tar -xz -C /tmp sudo install -m 0755 "/tmp/dolt-${os}-${arch}/bin/dolt" /usr/local/bin/dolt # Verify you got the version you asked for dolt version ``` `brew install dolt` installs whatever version the Homebrew formula currently points at, which is not pinned. If you install that way, check `dolt version` against the pin below. ### Which Dolt version to install Beads pins Dolt to **2.2.0**. CI installs that same pin with `scripts/ci/install-dolt.sh`, which records the per-version measurements and the criterion for raising it; raise the pin here and in that script together. This pin is about the standalone `dolt` CLI, which only server and proxied-server mode use. Embedded mode is unaffected either way: it links the Dolt engine into `bd` at the version in `go.mod`, currently the commit tagged v2.2.0 upstream, no matter which `dolt` CLI is on your PATH. Dolt 2.3.0 (released 2026-08-13) regressed `CALL DOLT_RESET('--hard')`. A few percent of freshly created databases come up with that procedure unusable — every call answers `Error 1105 (HY000): context canceled`, from any session and any new connection, for the life of that server process. Nothing else about the database looks wrong: `SELECT 1`, `CALL DOLT_CLEAN()`, `CALL DOLT_CHECKOUT('.')`, `CALL DOLT_COMMIT()` and soft resets all work normally, so the damage is invisible until something needs a hard reset. Measured by creating fresh databases and immediately calling the procedure: | Dolt version | Fresh databases with `DOLT_RESET('--hard')` broken | | - | - | | 2.1.8 | 0 / 40 | | 2.2.0 | 0 / 60 | | 2.3.0 | 3 / 60 | | 2.3.1 | 3 / 100 | Versions after 2.3.1 have not been measured. Raise the pin only once a newer release is confirmed clean by that same measurement — not because it is newer. Pin rather than track `latest` for a second, independent reason: the upstream `releases/latest` URL resolves to the most recently *created* release, not the highest version, so it can move backwards — v1.88.2 was created on 2026-08-17, after both v2.2.4 and v2.3.0. #### If you are already running 2.3.x Whether a database is affected is decided per database, when it is created — two databases on the same server can differ — so check each one you care about, against the server that is actually serving it: ```bash theme={null} # 1. The working set must be clean first: on a dirty working set a hard # reset discards uncommitted changes. If this returns any rows, commit # or clean up before step 3. dolt sql -q "SELECT * FROM dolt_status" # 2. Control — this must succeed. If it does not, you have a different # problem and step 3 proves nothing. dolt sql -q "SELECT 1" # 3. On a clean working set this is a no-op on a healthy database. dolt sql -q "CALL DOLT_RESET('--hard')" ``` Step 2 succeeding while step 3 answers `Error 1105 (HY000): context canceled` is the discriminating result — that database is affected. Both succeeding means it is not. The breakage lives in the running server process, not on disk, so restarting `dolt sql-server` clears it — verified by re-running the check on an affected database after a restart, with a healthy database on the same server as the control. A restart re-rolls the dice for every database, though, so the durable fix is to move to the pinned version. This matters because `bd flatten` and the Dolt-history compaction in `bd admin compact` both finish by hard-resetting `main` onto a temporary branch, and the merge-settle path behind `bd dolt pull` / `bd sync` falls back to a hard reset when it has to abandon a merge. See [Maintenance](#maintenance--bd-prune-and-bd-purge). ### New Project ```bash theme={null} # Embedded mode (single writer, no server — default for standalone) bd init # Server mode (multi-writer, e.g. orchestrator) gt dolt start # Start the Dolt server bd init --server # Initialize with server mode ``` ### Migrate from SQLite (Legacy) If upgrading from an older version that used SQLite: > **Note:** The `bd migrate --to-dolt` command was removed in v0.58.0. > For pre-0.50 installations with JSONL data, use the migration script: > > ```bash theme={null} > scripts/migrate-jsonl-to-dolt.sh > ``` > > See [Troubleshooting](/reference/troubleshooting#circuit-breaker-server-appears-down-failing-fast) if you encounter connection errors after migration. Migration creates backups automatically. Your original SQLite database is preserved as `beads.backup-pre-dolt-*.db`. ## Modes of Operation ```mermaid theme={null} flowchart LR subgraph embedded["Embedded mode (default) — bd init"] bd1["bd process
Dolt runs in-process"] --> d1[(".beads/embeddeddolt/
single writer, file-locked")] end subgraph server["Server mode — bd init --server"] bd2["bd (agent 1)"] --> srv["dolt sql-server"] bd3["bd (agent 2)"] --> srv srv --> d2[(".beads/dolt/
concurrent writers")] end ``` ### Embedded Mode (Solo / Standalone) In-process Dolt engine — no separate server needed. This is the default for standalone Beads users. The `bd` binary includes everything; just `bd init` and go. * Single-writer (one process at a time) * Data lives in `.beads/embeddeddolt/` alongside your code * Push to GitHub with `bd dolt push` — code and issues in one repo * Zero ops: no server, no ports, no PID files ### Server Mode (Multi-Writer / Orchestrator) Connects to a running `dolt sql-server` for multi-client access. ```bash theme={null} # Start the server (orchestrator) gt dolt start # Or manually cd ~/.dolt-data/beads && dolt sql-server --port 3307 ``` ```bash theme={null} # Initialize in server mode bd init --server # Or switch via environment variable export BEADS_DOLT_SERVER_MODE=1 ``` ```yaml theme={null} # .beads/config.yaml (server mode settings) dolt: mode: server host: 127.0.0.1 port: 3307 user: root ``` Configure the connection with flags or environment variables: | Flag | Env Var | Default | | - | - | - | | `--server-host` | `BEADS_DOLT_SERVER_HOST` | `127.0.0.1` | | `--server-port` | `BEADS_DOLT_SERVER_PORT` | `3307` | | `--server-socket` | `BEADS_DOLT_SERVER_SOCKET` | (none; uses TCP) | | `--server-user` | `BEADS_DOLT_SERVER_USER` | `root` | | | `BEADS_DOLT_PASSWORD` | (none) | **`BEADS_DOLT_SERVER_PORT` also declares the server externally managed.** Setting it — or the legacy `BEADS_DOLT_PORT` — makes `ResolveServerMode` classify the workspace as an externally-managed server, so bd will not auto-start a server for it: if nothing is listening on that port you get `auto-start is suppressed because the server is externally managed` rather than a server started on it. Use these vars to point bd at a server you already run; they are not a way to choose the port of a bd-owned server. A `dolt_mode: proxied-server` workspace is exempt — it reaches its server through the proxy, so an ambient port does not describe its lifecycle — and a shared-server workspace is already classified external on its own. **Unix domain sockets:** Use `--server-socket` to connect via a Unix socket instead of TCP. This avoids port conflicts between concurrent projects and is useful in sandboxed environments (e.g., Claude Code) where file-level access control is simpler than network allowlists. The Dolt server must be started with `dolt sql-server --socket `. Auto-start is not supported in socket mode. Switch to server mode when you need: * Multiple agents writing simultaneously * Orchestrator multi-rig setups * Federation with remote peers ## Maintenance — `bd prune` and `bd purge` `bd prune` permanently deletes closed non-ephemeral beads to reclaim storage and shrink auto-exports. `bd purge` does the same for ephemeral beads (wisps, transient molecules). Both require `--force` to execute. ```bash theme={null} bd prune --older-than 30d # Preview closed beads >30d old bd prune --older-than 30d --force # Delete them bd prune --older-than 90d --dry-run # Detailed preview with stats bd purge --force # Delete all closed ephemeral beads ``` **Reference-aware protection:** `bd prune` automatically skips closed beads whose ID appears in the description, notes, or comments of any open or in-progress bead. This prevents accidental deletion of ADR, decision, and verification beads that downstream work still cites. Use `--ignore-references` to override when cleaning up known-stale references: ```bash theme={null} bd prune --older-than 90d --ignore-references --force ``` `bd purge` is unaffected — ephemeral beads' references are themselves transient. For full Dolt storage reclaim after deleting many rows, follow with `bd flatten`. **On Dolt 2.3.x, storage-reclaim operations can fail partway.** `bd flatten` and the Dolt-history compaction in `bd admin compact` both build a temporary branch and then hard-reset `main` onto it, and the merge-settle path behind `bd dolt pull` / `bd sync` falls back to a hard reset when it abandons a merge. On an affected database that hard reset returns `Error 1105 (HY000): context canceled`: `bd flatten` and `bd admin compact` stop at that step, and an abandoned merge is left without its rollback. See [Which Dolt version to install](#which-dolt-version-to-install) for the check and the fix. ### Why a garbage collection can reclaim nothing Dolt's garbage collector is **generational**. Every pass moves the data reachable at that moment into an *old generation*, and a default pass only examines the *new generation* — data written since the last collection. So the second collection on a store never revisits what the first one kept, however much of it has since become unreachable. Squashing history and then running a default `dolt gc` is the case where this bites: the orphaned commit chain usually sits in the old generation, and the pass frees almost nothing. `dolt gc --full` collects both generations. It frees everything a default pass frees, plus the old generation, so it is never worth running a default pass first to save time. If a full collection frees nothing, the remaining bytes are still referenced — by a branch, a tag, or a cached remote-tracking ref — and the fix is to remove the reference, not to collect again. The [History Bloat runbook](/recovery/history-squash) walks through that diagnosis; [`bd flatten`](/cli-reference/flatten), [`bd compact`](/cli-reference/compact), and [`bd gc`](/cli-reference/gc) document the collection each one runs. ## Migrating Between Backends You can migrate data between embedded mode and server mode using `bd backup`. Both directions preserve full Dolt commit history. `bd export` is not a substitute for this flow. JSONL exports contain issue records from the issues table for migration and interoperability; they do not capture Dolt branches, full commit history, working-set state, or non-issue tables. Use `bd backup` or a manual Dolt backup when you need a restorable database backup. ### Server → Embedded 1. **Create a backup from the server-mode project:** ```bash theme={null} # In the server-mode project directory bd backup init /path/to/backup-dir bd backup sync ``` 2. **Create a new embedded-mode project and restore:** ```bash theme={null} mkdir new-project && cd new-project bd init # creates an embedded-mode project by default bd backup restore --force /path/to/backup-dir ``` `--force` overwrites the freshly-initialized database with the backup contents. The restore automatically: * Updates `metadata.json` to match the restored project identity * Registers the backup directory for future `bd backup sync` * Backfills the embedded migration tracker (`schema_migrations`) 3. **Verify:** ```bash theme={null} bd list bd backup status ``` ### Embedded → Server 1. **Create a backup from the embedded-mode project:** ```bash theme={null} # In the embedded-mode project directory bd backup init /path/to/backup-dir bd backup sync ``` 2. **Create a new server-mode project and restore:** ```bash theme={null} mkdir new-project && cd new-project bd init --server # creates a server-mode project bd backup restore --force /path/to/backup-dir ``` 3. **Verify:** ```bash theme={null} bd list bd backup status ``` ### Backup Commands Reference | Command | Description | | - | - | | `bd backup init ` | Register a backup destination (filesystem or DoltHub URL) | | `bd backup sync` | Push database to the configured backup destination | | `bd backup restore [path]` | Restore from a backup directory (`--force` to overwrite) | | `bd backup remove` | Unregister the backup destination | | `bd backup status` | Show backup configuration and last sync time | ### Notes * Data locations differ between modes: `.beads/embeddeddolt/` (embedded) vs `.beads/dolt/` (server) * The backup directory is a full Dolt backup, not an `issues.jsonl` export — it can be on a local drive, NAS, or DoltHub * You can also migrate via Dolt remotes (`bd dolt push` / `bd dolt pull`) if both projects share a remote The sections below are the canonical backend migration reference. ## Federation (Peer-to-Peer Sync) Federation lets independent Dolt-backed workspaces ("towns") sync issues directly with each other via `bd federation add-peer`/`sync`/`status`, without a central hub. Credentials are AES-256 encrypted and stored locally. See [Federation Setup Guide](/multi-agent/federation) for the full setup guide, including peer configuration, sovereignty tiers, sync/status/topology details, and troubleshooting. ## Dolt Remotes Use `bd dolt remote add` to configure remotes. This ensures the running Dolt SQL server sees the remote immediately. Remotes added directly with the `dolt` CLI are written to filesystem config and may not be visible to the server until restart. ```bash theme={null} # DoltHub (public or private) bd dolt remote add origin https://doltremoteapi.dolthub.com/org/beads # S3 bd dolt remote add origin aws://[bucket]/path/to/repo # GCS bd dolt remote add origin gs://[bucket]/path/to/repo # Git SSH (GitHub, GitLab, etc.) bd dolt remote add origin git+ssh://git@github.com/org/repo.git # Local file system bd dolt remote add origin file:///path/to/remote ``` ### Push/Pull ```bash theme={null} bd dolt push bd dolt pull ``` `bd dolt remote add` registers the remote through the Dolt store API. SQL remotes are the source of truth for `bd dolt remote list`, `bd dolt push`, and `bd dolt pull`. For git-protocol remotes, credentialed external-server remotes, and cloud remotes whose credentials are only present in the current shell, `bd dolt push` and `bd dolt pull` automatically materialize a matching local CLI remote before using the `dolt` CLI transport. The CLI remote is a local transport mirror, not a separate configuration source. If you are upgrading from an older beads version and previously added remotes with raw `dolt remote add`, re-register them with `bd dolt remote add ` so they are visible through SQL. `bd doctor` reports legacy CLI-only or mismatched CLI remotes under `Dolt Remote Migration`. > **Sharing a Git repo**: Dolt stores data under `refs/dolt/data`, separate > from standard Git refs (`refs/heads/`, `refs/tags/`). You can safely point a > `git+ssh://` remote at the same repository as your project source code. See > [Dolt Git Remotes](https://docs.dolthub.com/concepts/dolt/git/remotes). ### List/Remove Remotes ```bash theme={null} bd dolt remote list # Shows SQL-configured remotes bd dolt remote remove origin # Removes the remote ``` ## Contributor Onboarding (Clone Bootstrap) When someone clones a repository that uses Dolt backend: 1. Run `bd bootstrap` in the clone 2. If the git remote has `refs/dolt/data` (pushed via `bd dolt push`), `bd bootstrap` auto-detects it and clones the database from the remote 3. Work continues normally — all existing issues are available **No manual steps required** beyond `bd bootstrap`. The auto-detect: * Probes `origin` for `refs/dolt/data` * Clones the Dolt database from the remote (instead of creating a fresh one) * Configures the Dolt remote for future `bd dolt push`/`pull` If `sync.remote` is set in `.beads/config.yaml`, that takes precedence over auto-detection. Any Dolt-compatible remote URL is supported (DoltHub, S3, GCS, file, or git). On brand-new projects, `bd init` auto-detects `git origin` and persists it as `sync.remote`, so the first `bd dolt push` publishes Dolt history to `refs/dolt/data` on the same git remote. ### Verifying Bootstrap Worked ```bash theme={null} bd list # Should show issues bd vc status # Should show the current branch, no uncommitted changes ``` ## Troubleshooting ### Server Not Running **Symptom:** Connection refused errors when using server mode. ``` failed to create database: dial tcp 127.0.0.1:3307: connect: connection refused ``` **Fix:** ```bash theme={null} gt dolt start # Orchestrator command # Or gt dolt status # Check if running ``` ### Bootstrap Not Running **Symptom:** `bd list` shows nothing on fresh clone. **Check:** ```bash theme={null} ls .beads/dolt/ # Should NOT exist (pre-bootstrap) BD_DEBUG=1 bd list # See bootstrap output ``` **Force bootstrap:** ```bash theme={null} rm -rf .beads/dolt # Remove broken state bd list # Re-triggers bootstrap ``` ### Database Corruption **Symptom:** Queries fail, inconsistent data. **Diagnosis:** ```bash theme={null} bd doctor # Basic checks bd doctor --deep # Full validation bd doctor --server # Server mode checks (if applicable) ``` **Recovery options:** 1. **Repair what's fixable:** ```bash theme={null} bd doctor --fix ``` 2. **Rebuild from remote:** ```bash theme={null} rm -rf .beads/dolt bd list # Re-triggers bootstrap ``` ### Already Committed `.beads/dolt/` to Git If you accidentally committed a Dolt data directory: 1. Update gitignore: `bd doctor --fix` 2. Remove it from git tracking: `git rm --cached -r .beads/dolt/` (or `.beads/embeddeddolt/`) 3. Commit the removal: `git commit -m "fix: remove accidentally committed dolt data"` 4. To purge from history, use [BFG Repo-Cleaner](https://rtyley.github.io/bfg-repo-cleaner/) or `git filter-repo` ### Lock Contention (Embedded Mode) **Symptom:** "database is locked" errors. Embedded mode is single-writer (enforced via file lock). If you need concurrent access, switch to server mode. See [Migrating Between Backends](#migrating-between-backends). ## Configuration Reference ```yaml theme={null} # .beads/config.yaml # Dolt settings dolt: # Auto-commit Dolt history after writes (default: on for embedded, off for server) auto-commit: on # on | off # Storage mode (default: embedded) mode: embedded # embedded | server # Server mode settings (only used when mode: server) host: 127.0.0.1 port: 3307 user: root # Password: env var or credentials file (see below) # Shared server mode (GH#2377): all projects share a single Dolt server # at ~/.beads/shared-server/. Each project uses its own database (prefix-based). # Eliminates port conflicts and reduces resource usage on multi-project machines. shared-server: false # true | false ``` ### Environment Variables | Variable | Purpose | | - | - | | `BEADS_DOLT_PASSWORD` | Server mode password (highest priority) | | `BEADS_CREDENTIALS_FILE` | Path to credentials file (overrides default location) | | `BEADS_DOLT_SERVER_MODE` | Enable server mode (set to "1") | | `BEADS_DOLT_SERVER_HOST` | Server host (default: 127.0.0.1) | | `BEADS_DOLT_SERVER_PORT` | Server port (default: 3307, or 3308 in shared mode) | | `BEADS_DOLT_SERVER_TLS` | Enable TLS (set to "1" or "true") | | `BEADS_DOLT_SERVER_USER` | MySQL connection user | | `BEADS_DOLT_SHARED_SERVER` | Enable shared server mode (set to "1" or "true") | | `DOLT_REMOTE_USER` | Clone/push/pull auth user | | `DOLT_REMOTE_PASSWORD` | Clone/push/pull auth password | | `BD_DOLT_AUTO_COMMIT` | Override auto-commit setting | **Note:** `BEADS_DOLT_SERVER_PORT` (and the legacy `BEADS_DOLT_PORT`) do more than name a port — setting either also marks the workspace as an externally-managed server and suppresses auto-start. See **Server Mode** above. ### Credentials File For multi-server setups, you can store passwords in an INI-style credentials file instead of juggling environment variables per project. Passwords are looked up by `[host:port]` section, so each project automatically gets the right password based on its configured server. **Password resolution order:** 1. `BEADS_DOLT_PASSWORD` env var (highest priority, existing behavior) 2. Credentials file lookup by `[host:port]` (using the resolved runtime port) 3. Empty string (no password) **Port resolution note:** The `[host:port]` used for credential lookup matches the resolved runtime port (from the port file, env var, or config — in that priority order), not necessarily the port stored in `metadata.json`. This matters when using IAP tunnels: if your tunnel maps remote:3307 to localhost:3308, store your password under `[127.0.0.1:3308]` and the credentials file will match the actual connection. **Default location:** `~/.config/beads/credentials` (Linux/macOS), `%APPDATA%\beads\credentials` (Windows) **Override location:** Set `BEADS_CREDENTIALS_FILE` env var. **File format:** ```ini theme={null} # ~/.config/beads/credentials [127.0.0.1:3307] password=localDevPassword [beads.company.com:3307] password=teamServerPassword [10.0.1.50:3308] password=officePassword ``` **Permissions:** On Linux/macOS, a warning is printed to stderr if the file is readable by group or others (mirrors ssh behavior). Set permissions with: ```bash theme={null} chmod 600 ~/.config/beads/credentials ``` ## Dolt Version Control Dolt maintains its own version history, separate from Git: ```bash theme={null} # View an issue's version history across Dolt commits bd history bd-42 # Show current branch and uncommitted changes bd vc status # Create manual checkpoint bd vc commit -m "Checkpoint before refactor" ``` ### Auto-Commit Behavior In **embedded mode** (standalone default), each `bd` write command creates a Dolt commit: ```bash theme={null} bd create "New issue" # Creates issue + Dolt commit ``` In **server mode** (orchestrator), auto-commit defaults to OFF because the server manages its own transaction lifecycle. Firing `DOLT_COMMIT` after every write under concurrent load causes 'database is read only' errors. Override for batch operations (embedded) or explicit commits (server): ```bash theme={null} bd --dolt-auto-commit off create "Issue 1" bd --dolt-auto-commit off create "Issue 2" bd vc commit -m "Batch: created issues" ``` ## Server Management (Orchestrator) The orchestrator provides integrated Dolt server management: ```bash theme={null} gt dolt start # Start server (background) gt dolt stop # Stop server gt dolt status # Show server status gt dolt logs # View server logs gt dolt sql # Open SQL shell ``` Server runs on port 3307 (avoids MySQL conflict on 3306). ### Standalone-to-managed-city handoff When an existing standalone project is later added to a managed city or orchestrator, avoid letting two Dolt servers become sources of truth for the same beads database name. A common split-brain symptom is that `.beads/dolt-server.port` points at the old standalone server while the shell environment points `bd` at the managed server with `BEADS_DOLT_PORT` or `BEADS_DOLT_SERVER_PORT`. Check before migrating: ```bash theme={null} bd doctor bd dolt status ``` `bd doctor` warns when the runtime managed port differs from the local port file. The warning is intentionally diagnostic only; do not delete the local port file until the standalone store has been exported and imported into the managed server. Safe manual handoff: ```bash theme={null} # From the standalone project, without managed-city port overrides: unset BEADS_DOLT_PORT BEADS_DOLT_SERVER_PORT bd backup bd export > /tmp/beads-standalone.jsonl bd dolt stop # Then enter the managed-city environment and import into its Dolt server: bd import /tmp/beads-standalone.jsonl bd doctor ``` After `bd doctor` shows one healthy store and the imported issue count is correct, archive the old local Dolt data directory instead of deleting it immediately. Keep the backup until the managed city has been pushed or otherwise snapshotted. ### Shared Server Mode On machines with multiple beads projects, each project normally starts its own Dolt server. Shared server mode runs a single Dolt server at `~/.beads/shared-server/` that serves all projects: ```bash theme={null} # Enable for this project (config.yaml key) bd config set dolt.shared-server true # Or enable machine-wide via environment variable export BEADS_DOLT_SHARED_SERVER=1 # Or enable during init bd init --prefix myproject --shared-server ``` **Benefits:** * No port conflicts between projects (single server on port 3308, avoids orchestrator on 3307) * Reduced resource usage (one process instead of many) * Automatic database isolation (each project uses its own database name) **How it works:** * Server state files (PID, port, lock, log) live in `~/.beads/shared-server/` * Dolt data directory: `~/.beads/shared-server/dolt/` * Each project's database is stored as a subdirectory (e.g., `~/.beads/shared-server/dolt/myproject/`) * The file lock mechanism ensures safe concurrent access from multiple projects * Default port is 3308 (not 3307) to avoid conflict with the orchestrator. Override with `BEADS_DOLT_SERVER_PORT` or `dolt.port` in config.yaml **Important:** Each project on a shared server **must have a unique prefix** (database name). Two projects with the same prefix share the same database — if this happens accidentally, the project identity check will detect the mismatch and refuse to connect, preventing silent data corruption. Always use distinct prefixes when running `bd init --shared-server`. ```bash theme={null} # Check shared server status from any project bd dolt status # Show full configuration including shared mode bd dolt show ``` ### Data Location (Orchestrator) ``` /.dolt-data/ ├── hq/ # Town beads (hq-*) ├── my-project/ # Project rig (mp-*) ├── beads/ # Beads rig (bd-*) └── other-project/ # Other rig (op-*) ``` ### Central Dolt Server (macOS LaunchAgent) If you do not use the orchestrator but still want a single persistent Dolt server for multiple projects on macOS, run a custom `LaunchAgent` instead of spawning per-project embedded instances. #### Why Not `brew services start dolt`? After installing Dolt with `brew install dolt`, the natural next step is `brew services start dolt`. However, the Homebrew formula runs `dolt sql-server` without the `--config` flag, and Dolt does not auto-discover `config.yaml` from its working directory. The config file must be passed explicitly with `--config `. #### Setup with a Custom LaunchAgent Install Dolt and initialize its data directory. Check the installed version against [the pin](#which-dolt-version-to-install) — Homebrew's formula is not pinned: ```bash theme={null} brew install dolt dolt version cd /opt/homebrew/var/dolt && dolt init ``` Configure Dolt for port 3307: ```yaml theme={null} # /opt/homebrew/var/dolt/config.yaml log_level: info listener: host: 127.0.0.1 port: 3307 max_connections: 100 behavior: autocommit: true ``` Create the LaunchAgent plist: ```bash theme={null} cat > ~/Library/LaunchAgents/com.local.dolt-server.plist << 'EOF' Label com.local.dolt-server ProgramArguments /opt/homebrew/bin/dolt sql-server --config /opt/homebrew/var/dolt/config.yaml WorkingDirectory /opt/homebrew/var/dolt RunAtLoad KeepAlive StandardOutPath /opt/homebrew/var/log/dolt.log StandardErrorPath /opt/homebrew/var/log/dolt-error.log EOF ``` Load and verify the service: ```bash theme={null} launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist mysql -h 127.0.0.1 -P 3307 -u root -e "SELECT 1" ``` Point beads at the central server: ```bash theme={null} export BEADS_DOLT_SERVER_MODE=1 export BEADS_DOLT_SERVER_PORT=3307 ``` Manage the service: ```bash theme={null} # Stop launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist # Restart launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist # Check logs tail -f /opt/homebrew/var/log/dolt.log ``` ## Advanced Dolt Usage The `dolt` CLI lets you operate directly on the database for power-user workflows. The data directory depends on your mode: `.beads/embeddeddolt/` (embedded) or `.beads/dolt/` (server). ### Branching ```bash theme={null} cd .beads/dolt # or .beads/embeddeddolt for embedded mode dolt branch feature-x dolt checkout feature-x ``` ### Time Travel ```bash theme={null} dolt log dolt checkout dolt sql -q "SELECT * FROM issues" ``` ### Diff and Blame ```bash theme={null} dolt diff main feature-x dolt blame issues ``` ## Migration Cleanup After successful migration from SQLite, you may have backup files: ``` .beads/beads.backup-pre-dolt-20260122-213600.db .beads/sqlite.backup-pre-dolt-20260123-192812.db ``` These are safe to delete once you've verified Dolt is working: ```bash theme={null} # Verify Dolt works bd list bd doctor # Then clean up (after appropriate waiting period) rm .beads/*.backup-*.db ``` **Recommendation:** Keep backups for at least a week before deleting. ## See Also * [Sync Concepts](/core-concepts/sync-concepts) - The conceptual model behind cross-machine sync (Dolt source of truth, wire format, anti-patterns) * [Sync Setup Guide](/getting-started/sync-setup) - Setting up sync across multiple computers * [Federation Setup Guide](/multi-agent/federation) - Peer-to-peer federation setup * [Configuration](/reference/configuration) - Full configuration reference * [Dependencies and Gates](/core-concepts/dependencies) - Dependencies and gates * [Git Integration](/reference/git-integration) - Git worktrees and protected branches * [Troubleshooting](/reference/troubleshooting) - General troubleshooting # Architecture Overview Source: https://beads.gascity.com/architecture/index How Beads stores, queries, and syncs issue data with Dolt This document explains how Beads' architecture works with Dolt as its storage backend: the storage layout, the data model, and the sync paths. For the concept model — beads, dependencies, ready work, molecules — see [How Beads Works](/core-concepts/index). ## Architecture Beads uses **Dolt** as its sole storage backend -- a version-controlled SQL database that provides git-like semantics (branch, merge, diff, push, pull) natively at the database level. By default, Dolt runs in **embedded mode** (in-process, no separate server). For multi-writer setups (multiple agents, orchestrator), switch to **server mode** which connects to a running `dolt sql-server`. See the [Dolt Server Mode](#dolt-server-mode) section below for details. ```mermaid theme={null} flowchart TD subgraph DOLT["🗄️ Dolt Database"] D[("embedded default: .beads/embeddeddolt/
server mode: .beads/dolt/
Version-Controlled SQL")] end subgraph REMOTE["🌐 Dolt Remotes"] R[("DoltHub / S3 / GCS
Sync & Backup")] end D <-->|"bd dolt push/pull"| R U((User)) -->|"bd create
bd update"| D D -->|"bd list
bd show"| U style DOLT fill:#2d5a27,stroke:#4a9c3e,color:#fff style REMOTE fill:#1a4a6e,stroke:#3a8ac4,color:#fff ``` **Source of Truth** **Dolt** is the source of truth. Every write auto-commits to Dolt history, providing full version control, branching, and merge capabilities at the database level. Recovery is straightforward: pull from a Dolt remote with `bd dolt pull`, or restore from a Dolt-native backup with `bd backup restore`. ### Why Dolt? * **Version-controlled SQL**: Full SQL queries with native version control * **Cell-level merge**: Concurrent changes merge automatically at the field level * **Multi-writer**: Server mode supports concurrent agents * **Native branching**: Dolt branches independent of git branches * **Works offline**: All queries run against local database * **Portable**: `bd export` produces JSONL for migration and interoperability ## Data Model The database stores five kinds of records: issues (the beads themselves), dependencies (typed edges such as `blocks`, `parent-child`, `related`, and `discovered-from`), labels, comments, and events (the audit trail). What each means — and how `bd ready` computes the claimable frontier from them — is covered in [How Beads Works](/core-concepts/index). Issue IDs are content-derived hashes (`bd-a1b2`) so that concurrent writers never collide and no central ID coordination is needed. See [Hash-based IDs](/core-concepts/hash-ids) for the design and [COLLISION\_MATH](https://github.com/gastownhall/beads/blob/main/engdocs/COLLISION_MATH.md) for the birthday-paradox analysis of hash length vs collision probability. ### Issue Schema Core fields on every issue, as stored in Dolt and emitted in `bd export` JSONL. Optional fields are omitted when empty. | Field | Type | Description | | - | - | - | | `id` | string | Unique hash ID (e.g., `bd-a1b2`) | | `title` | string | Issue title (required) | | `description` | string | Detailed description (optional) | | `design` | string | Design notes (optional) | | `acceptance_criteria` | string | Acceptance criteria (optional) | | `notes` | string | Additional notes (optional) | | `status` | string | `open`, `in_progress`, `blocked`, `deferred`, `closed`, `pinned`, `hooked` (defaults to `open`; extendable via the `status.custom` config key) | | `priority` | int | 0–4, where 0 = critical and 4 = backlog | | `issue_type` | string | `bug`, `feature`, `task`, `epic`, `chore`, `decision`, `message`, `molecule`, `gate`, `spike`, `story`, `milestone` (defaults to `task`) | | `assignee` | string | Assigned user/agent (optional) | | `estimated_minutes` | int | Time estimate in minutes (optional) | | `created_at` / `updated_at` | RFC3339 | Creation and last-modification times | | `created_by` | string | Who created the issue (optional) | | `closed_at` / `close_reason` | RFC3339 / string | Set when the issue is closed (optional) | | `external_ref` | string | External reference such as `gh-9` or `jira-ABC` (optional) | | `metadata` | JSON | Arbitrary extension data — see [Issue Metadata](/core-concepts/metadata) | | `labels` | \[]string | Tags attached to the issue (optional) | | `dependencies` | \[]Dependency | Typed edges to other issues (optional) | | `comments` | \[]Comment | Discussion thread (optional) | Issues also carry workflow-layer field groups, among others: scheduling (`due_at`, `defer_until`), claim leasing (`lease_expires_at`, `heartbeat_at`), gates (`await_type`, `await_id`, `timeout`), and molecule/wisp fields (`ephemeral`, `mol_type`, `bonded_from`). Internal fields — `content_hash` (a SHA-256 of the issue's canonical content, used for change detection), `source_repo`, and `id_prefix` — never appear in exports. The schema is stable by default: prefer the `metadata` field for integration-, orchestrator-, or team-specific data before proposing new first-class fields. See the [Project Charter's schema boundary](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md#schema-boundary). ## Data Flow ### Write Path ```text theme={null} User runs bd create → Dolt database updated → Auto-committed to Dolt history ``` ### Read Path ```text theme={null} User runs bd list → Dolt SQL query → Results returned immediately ``` ### Sync Path ```text theme={null} User runs bd dolt push → Commits pushed to Dolt remote User runs bd dolt pull → Remote commits fetched and merged ``` Dolt remotes can live on DoltHub, S3, GCS, a filesystem path, or your existing git remote — issue history rides under `refs/dolt/data`, separate from code branches. See [Sync Concepts](/core-concepts/sync-concepts) for the wire format and setup. Cross-repo setups can also exchange beads peer-to-peer via [federation](/multi-agent/federation). Ephemeral [wisps](/workflows/wisps) are excluded from federation push by default, so execution traces never enter shared history. ### Multi-Machine Sync Considerations When working across multiple machines or clones: 1. **Always sync before switching machines** ```bash theme={null} bd dolt push # Push changes before leaving ``` 2. **Pull before creating new issues** ```bash theme={null} bd dolt pull # Pull changes first on new machine bd create "New issue" ``` 3. **Avoid parallel edits** - If two machines create issues simultaneously without syncing, Dolt's cell-level merge handles most conflicts automatically See [Sync Failures Recovery](/recovery/sync-failures) for data loss prevention in multi-machine workflows (Pattern A5/C3). ## Dolt Server Mode The Dolt server handles background synchronization and database operations: * Manages the Dolt database backend * Handles auto-commit for change tracking * Provides concurrent access for multiple agents * Runtime files live directly in `.beads/`: `dolt-server.pid`, `dolt-server.log`, and `dolt-server.port` An opt-in *shared server* mode runs a single Dolt server at `~/.beads/shared-server/` for all projects, enabled with `dolt.shared-server: true` in `config.yaml` or `BEADS_DOLT_SHARED_SERVER=1` — see [Dolt Backend](/architecture/dolt#shared-server-mode). Start the Dolt server with `bd dolt start`. Check health with `bd doctor`. ### Embedded Mode (No Server) Embedded mode is the default (`bd init` with no flags): Dolt runs in-process, single-writer, with data at `.beads/embeddeddolt/` — no server process and no separate Dolt install. Server mode is opt-in via `bd init --server`; the choice is persisted in `.beads/metadata.json`. ```bash theme={null} bd create "CI-generated issue" bd dolt push ``` **Beyond solo use, embedded mode is a natural fit for:** * CI/CD pipelines (Jenkins, GitHub Actions) * Docker containers * Ephemeral environments * Scripts that should not leave background processes ### Multi-Clone Scenarios **Race Conditions in Multi-Clone Workflows** When multiple git clones of the same repository run sync operations simultaneously, race conditions can occur during push/pull operations. This is particularly common in: * Multi-agent AI workflows (multiple Claude/GPT instances) * Developer workstations with multiple checkouts * Worktree-based development workflows **Prevention:** 1. Stop the Dolt server (`bd dolt stop`) before switching between clones 2. Dolt handles worktrees natively in server mode 3. Use embedded mode for automated workflows See [Sync Failures Recovery](/recovery/sync-failures) for sync race condition troubleshooting (Pattern B2). ## Directory Layout ```text theme={null} .beads/ ├── embeddeddolt/ # Dolt database (embedded mode, default) — gitignored ├── dolt/ # Dolt database (server mode) — gitignored ├── dolt-server.pid # Server-mode runtime files (.pid, .log, .port) — gitignored ├── issues.jsonl # Passive JSONL export for viewers and interchange ├── metadata.json # Backend config — tracked in git └── config.yaml # Project config (optional) — tracked in git ``` The database directory for your mode is the only thing holding issue data; everything else is configuration, runtime state, or a derived export. `bd init` writes a `.beads/.gitignore` that keeps the database and runtime files out of git. ## Recovery Model Dolt's version control makes recovery straightforward: 1. **Lost database?** → Pull from Dolt remote: `bd dolt pull` 2. **Have a backup?** → Restore it: `bd backup restore [path] --force` 3. **Merge conflicts?** → Dolt handles cell-level merge natively Create backups with `bd backup init` (a filesystem path or DoltHub destination) and push them with `bd backup sync`. Dolt-native backups preserve full commit history; a JSONL export does not. ### Universal Recovery Sequence The following sequence resolves the majority of reported issues. For detailed procedures, see [Recovery Runbooks](/recovery/index). ```bash theme={null} bd dolt stop # Stop Dolt server (prevents race conditions) git worktree prune # Clean orphaned worktrees bd dolt pull # Pull from Dolt remote bd dolt start # Restart server ``` **Use `bd doctor --fix` With Care** Always back up and preview before running `bd doctor --fix`: 1. **Back up first:** `cp -r .beads .beads.backup` 2. **Preview changes:** `bd doctor --dry-run` — shows what would be fixed without making changes 3. **Review diagnostics:** `bd doctor` (no flags) — diagnostic only, no changes made 4. **Then fix:** `bd doctor --fix` — or `bd doctor --fix -i` to confirm each fix individually **Why caution?** The `--fix` flag may remove dependencies it flags as circular, including valid parent-child relationships. Use `--fix-child-parent` only if you're certain the flagged deps are invalid. **Other diagnostic tools:** * `bd blocked` — check which issues are blocked and why * `bd show ` — inspect a specific issue's state See [Recovery](/recovery/index) for specific procedures and [Database Corruption Recovery](/recovery/database-corruption) for Dolt recovery steps. ## Design Decisions ### Why Dolt? Dolt is a version-controlled SQL database that provides git-like semantics natively. Unlike plain SQLite (binary merge conflicts) or JSONL (slow queries), Dolt gives you both fast SQL queries and proper merge semantics. ### Why not a cloud server? Beads is designed for offline-first, local-first development. The Dolt server runs locally -- no cloud dependency, no downtime, no vendor lock-in, and full functionality on airplanes or in restricted networks. ### Trade-offs | Benefit | Trade-off | | - | - | | Works offline | No real-time collaboration | | Version-controlled database | Server mode needed for concurrent writers | | Cell-level merge | Requires initial setup | | Local-first speed | Manual sync to remotes | | SQL queries | Dolt storage engine dependency | ### When NOT to use Beads Beads is not suitable for: * **Large teams (10+)** — Git-based sync doesn't scale well for high-frequency concurrent edits * **Non-developers** — Requires Git and command-line familiarity * **Real-time collaboration** — No live updates; requires explicit sync * **Rich media attachments** — Designed for text-based issue tracking For these use cases, consider GitHub Issues, Linear, or Jira. ## Related Documentation * [How Beads Works](/core-concepts/index) — The concept model: beads, dependencies, ready work, molecules * [Sync Concepts](/core-concepts/sync-concepts) — Cross-machine sync, wire format, and anti-patterns * [Dolt Backend](/architecture/dolt) — Embedded vs server mode in depth, shared server, migration * [Recovery Runbooks](/recovery/index) — Step-by-step procedures for common issues * [CLI Reference](/cli-reference/index) — Complete command documentation * [Getting Started](/index) — Installation and first steps * [Project Charter](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md) — Product scope and boundaries (contributor doc) * [Internals](https://github.com/gastownhall/beads/blob/main/engdocs/INTERNALS.md) — Implementation details (contributor doc) # bd admin Source: https://beads.gascity.com/cli-reference/admin Administrative commands for beads database maintenance. Generated from `bd help --doc admin`. Administrative commands for beads database maintenance. These commands are for advanced users and should be used carefully: cleanup Delete closed issues (issue lifecycle) compact Compact old closed issues to save space (storage optimization) reset Remove all beads data and configuration (full reset) For routine maintenance, prefer 'bd doctor --fix' which handles common repairs automatically. Use these admin commands for targeted database operations. ``` bd admin [flags] ``` ## bd admin cleanup Delete closed issues to reduce database size. This command permanently removes closed issues from the database. NOTE: This command only manages issue lifecycle (closed -> deleted). For general health checks and automatic repairs, use 'bd doctor --fix' instead. By default, deletes ALL closed issues. Use --older-than to only delete issues closed before a certain date. EXAMPLES: bd admin cleanup --force # Delete all closed issues bd admin cleanup --older-than 30 --force # Only issues closed 30+ days ago bd admin cleanup --ephemeral --force # Only closed wisps (transient molecules) bd admin cleanup --dry-run # Preview what would be deleted SAFETY: * Requires --force flag to actually delete (unless --dry-run) * Supports --cascade to delete dependents * Shows preview of what will be deleted * Use --json for programmatic output SEE ALSO: bd doctor --fix Automatic health checks and repairs (recommended for routine maintenance) bd admin compact Compact old closed issues to save space ``` bd admin cleanup [flags] ``` **Flags:** ``` --cascade Recursively delete all dependent issues --dry-run Preview what would be deleted without making changes --ephemeral Only delete closed wisps (transient molecules) -f, --force Actually delete (without this flag, shows error) --older-than int Only delete issues closed more than N days ago (0 = all closed issues) ``` ## bd admin compact Compact old closed issues using semantic summarization. Compaction reduces database size by summarizing closed issues that are no longer actively referenced. This is permanent graceful decay - original content is discarded. Modes: * Analyze: Export candidates for agent review (no API key needed) * Apply: Accept agent-provided summary (no API key needed) * Auto: AI-powered compaction (requires ANTHROPIC\_API\_KEY or ai.api\_key, legacy) * Dolt: Run Dolt garbage collection (for Dolt-backend repositories) Tiers: * Tier 1: Semantic compression (30 days closed, 70% reduction) * Tier 2: Ultra compression (90 days closed) - planned, not yet implemented Dolt Garbage Collection: With auto-commit per mutation, Dolt commit history grows over time. Use \--dolt to run Dolt garbage collection and reclaim disk space. \--dolt: Run Dolt GC on .beads/dolt directory to free disk space. This removes unreachable commits and compacts storage. Examples: # Dolt garbage collection bd compact --dolt # Run Dolt GC bd compact --dolt --dry-run # Preview without running GC # Agent-driven workflow (recommended) bd compact --analyze --json # Get candidates with full content bd compact --apply --id bd-42 --summary summary.txt bd compact --apply --id bd-42 --summary - \< summary.txt # Legacy AI-powered workflow bd compact --auto --dry-run # Preview candidates bd compact --auto --all # Compact all eligible issues bd compact --auto --id bd-42 # Compact specific issue # Statistics bd compact --stats # Show statistics ``` bd admin compact [flags] ``` **Flags:** ``` --actor string Actor name for audit trail (default "agent") --all Process all candidates --analyze Analyze mode: export candidates for agent review --apply Apply mode: accept agent-provided summary --auto Auto mode: AI-powered compaction (legacy) --batch-size int Issues per batch (default 10) --dolt Dolt mode: run Dolt garbage collection on .beads/dolt --dry-run Preview without compacting --force Force compact (bypass checks, requires --id) --id string Compact specific issue --json Output JSON format --limit int Limit number of candidates (0 = no limit) --stats Show compaction statistics --summary string Path to summary file (use '-' for stdin) --tier int Compaction tier (only tier 1 is implemented) (default 1) --workers int Parallel workers (default 5) ``` ## bd admin reset Reset beads to an uninitialized state, removing all local data. This command removes: * The .beads directory (database, JSONL, config) * Git hooks installed by bd * Sync branch worktrees By default, shows what would be deleted (dry-run mode). Use --force to actually perform the reset. Examples: bd reset # Show what would be deleted bd reset --force # Actually delete everything ``` bd admin reset [flags] ``` **Flags:** ``` --force Actually perform the reset (required) ``` # bd ado Source: https://beads.gascity.com/cli-reference/ado Commands for syncing issues between beads and Azure DevOps. Generated from `bd help --doc ado`. Commands for syncing issues between beads and Azure DevOps. Configuration can be set via 'bd config' or environment variables: ado.org / AZURE\_DEVOPS\_ORG - Organization name ado.project / AZURE\_DEVOPS\_PROJECT - Project name (single) ado.projects / AZURE\_DEVOPS\_PROJECTS - Project names (comma-separated) ado.pat / AZURE\_DEVOPS\_PAT - Personal access token ado.url / AZURE\_DEVOPS\_URL - Custom base URL (on-prem) ``` bd ado [flags] ``` ## bd ado projects List Azure DevOps projects that the configured token has access to. ``` bd ado projects [flags] ``` ## bd ado pull Pull one or more items from Azure DevOps. Accepts bead IDs or external references as positional arguments. Equivalent to: bd ado sync --pull-only --issues \ ``` bd ado pull [refs...] [flags] ``` **Flags:** ``` --dry-run Preview pull without making changes ``` ## bd ado push Push one or more beads issues to Azure DevOps. Accepts bead IDs as positional arguments. Equivalent to: bd ado sync --push-only --issues \ ``` bd ado push [bead-ids...] [flags] ``` **Flags:** ``` --dry-run Preview push without making changes ``` ## bd ado status Display current Azure DevOps configuration and sync status. ``` bd ado status [flags] ``` ## bd ado sync Synchronize issues between beads and Azure DevOps. By default, performs bidirectional sync: * Pulls new/updated work items from Azure DevOps to beads * Pushes local beads issues to Azure DevOps Use --pull-only or --push-only to limit direction. Filters (--area-path, --iteration-path, --types, --states) restrict which work items are synced. On pull, they limit the WIQL query. On push, \--types and --states filter local beads before pushing to ADO. Use \--no-create with push to skip creating new ADO work items (only update existing linked items). Filters can also be persisted via config: ado.filter.area\_path, ado.filter.iteration\_path, ado.filter.types, ado.filter.states CLI flags override config values when both are set. ``` bd ado sync [flags] ``` **Flags:** ``` --area-path string Filter to ADO area path (e.g., "Project\Team") --bootstrap-match Enable heuristic matching for first sync --dry-run Show what would be synced without making changes --issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent. --iteration-path string Filter to ADO iteration path (e.g., "Project\Sprint 1") --no-create Never create new items in either direction (pull or push) --parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues. --prefer-ado On conflict, use Azure DevOps version --prefer-local On conflict, keep local beads version --prefer-newer On conflict, use most recent version (default) --project strings Project name(s) to sync (overrides configured project/projects) --pull-only Only pull issues from Azure DevOps --push-only Only push issues to Azure DevOps --reconcile Force reconciliation scan for deleted items --states string Filter to ADO states, comma-separated (e.g., "New,Active,Resolved") --types string Filter to work item types, comma-separated (e.g., "Bug,Task,User Story") ``` # bd assign Source: https://beads.gascity.com/cli-reference/assign Assign an issue to someone. Generated from `bd help --doc assign`. Assign an issue to someone. Shorthand for 'bd update \ --assignee \'. Examples: bd assign bd-123 alice bd assign bd-123 "" # unassign ``` bd assign [flags] ``` # bd audit Source: https://beads.gascity.com/cli-reference/audit Audit log entries are appended to .beads/interactions.jsonl. Generated from `bd help --doc audit`. Audit log entries are appended to .beads/interactions.jsonl. Each line is one event. This file is intended to be versioned in git and used for: * auditing ("why did the agent do that?") * dataset generation (SFT/RL fine-tuning) Entries are append-only. Labeling creates a new "label" entry that references a parent entry. ``` bd audit [flags] ``` ## bd audit label Append a label entry referencing an existing interaction ``` bd audit label [flags] ``` **Flags:** ``` --label string Label value (e.g. "good" or "bad") --reason string Reason for label ``` ## bd audit record Append an audit interaction entry ``` bd audit record [flags] ``` **Flags:** ``` --error string Error string (llm_call/tool_call) --exit-code int Exit code (tool_call) (default -1) --issue-id string Related issue id (bd-...) --kind string Entry kind (e.g. llm_call, tool_call, label) --model string Model name (llm_call) --prompt string Prompt text (llm_call) --response string Response text (llm_call) --stdin Read a JSON object from stdin (must match audit.Entry schema) --tool-name string Tool name (tool_call) ``` # bd backup Source: https://beads.gascity.com/cli-reference/backup Back up your beads database for off-machine recovery. Generated from `bd help --doc backup`. Back up your beads database for off-machine recovery. This is a Dolt-native database backup. It preserves the database state, including tables, branches, commit history, and working-set data. This is different from 'bd export', which writes issue records to JSONL for migration and interoperability. Commands: bd backup init \ Set up a backup destination (filesystem or DoltHub) bd backup sync Push to configured backup destination bd backup restore \[path] Restore from a backup directory bd backup remove Remove backup destination bd backup status Show backup status DoltHub is recommended for cloud backup: bd backup init [https://doltremoteapi.dolthub.com/\<user\>/\<repo](https://doltremoteapi.dolthub.com/\<user\>/\<repo)> Set DOLT\_REMOTE\_USER and DOLT\_REMOTE\_PASSWORD for authentication. ``` bd backup [flags] ``` ## bd backup init Configure a filesystem path or URL as a backup destination. The path can be a local directory (external drive, NAS, Dropbox folder) or a DoltHub remote URL. If the destination was previously configured, it is updated to the new path. Filesystem examples: bd backup add /mnt/usb/beads-backup bd backup add \~/Dropbox/beads-backup DoltHub (recommended for cloud backup): bd backup add [https://doltremoteapi.dolthub.com/myuser/beads-backup](https://doltremoteapi.dolthub.com/myuser/beads-backup) After adding, run 'bd backup sync' to push your data. ``` bd backup init [flags] ``` **Aliases:** add ## bd backup remove Remove the configured backup destination. This unregisters the backup remote from Dolt and removes the local backup configuration. The backup data at the destination is not deleted. ``` bd backup remove [flags] ``` **Aliases:** rm ## bd backup restore Restore the beads database from a Dolt-native backup. By default, reads from .beads/backup/ (or the configured backup directory). Optionally specify a path to a directory containing a Dolt backup. This restores a full database backup created by 'bd backup sync' or an equivalent Dolt backup. JSONL files produced by 'bd export' are issue exports, not restore targets for this command. Use --force to overwrite an existing database with the backup contents. The database must already be initialized (run 'bd init' first if needed). To initialize and restore in one step, use: bd init && bd backup restore ``` bd backup restore [path] [flags] ``` **Flags:** ``` --force Overwrite existing database with backup contents ``` ## bd backup status Show last backup status ``` bd backup status [flags] ``` ## bd backup sync Sync the current beads database to the configured Dolt backup destination. This pushes the entire database state (all branches, full history) to the backup location configured with 'bd backup init'. The backup is atomic — if the sync fails, the previous backup state is preserved. Run 'bd backup init \' first to configure a destination. ``` bd backup sync [flags] ``` # bd batch Source: https://beads.gascity.com/cli-reference/batch Run multiple write operations in a single database transaction. Generated from `bd help --doc batch`. Run multiple write operations in a single database transaction. Commands are read from stdin (one per line) or from a file via -f/--file. All operations execute inside a single dolt transaction: on any error the whole batch is rolled back, otherwise it is committed with one DOLT\_COMMIT. This is intended for shell scripts that currently invoke 'bd' many times in a loop, which causes severe write amplification on a dolt sql-server backed by btrfs+compression. Batching collapses N invocations into one transaction and one dolt commit. Grammar (one command per line): close \ \[reason...] update \ \=\ \[\=\ ...] create \ \ \ dep add \ \ \[type] dep remove \ \ \#comment (blank lines and '# ...' comments are ignored) Supported 'update' keys: status, priority, title, assignee Supported dependency types: see 'bd dep add --help' (default: blocks) Tokens are whitespace-separated. Double-quoted strings ("like this") may contain spaces; use " to embed a quote and \ for a backslash. Examples: # From a pipe bd list --status stale -q | awk '\{print "close",\$1," stale"}' | bd batch # From a file bd batch -f operations.txt # Inline printf 'close bd-1 done\nupdate bd-2 status=in\_progress\n' | bd batch On success, exits 0 and prints a summary (or JSON with --json). On any error, rolls back the entire transaction and exits non-zero with the failing line. NOTE: This is a narrow subset. Commands like 'show', 'list', 'ready', 'sync', complex create flows, or any flag not listed above are NOT accepted. Use normal 'bd' subcommands for interactive/read operations. ``` bd batch [flags] ``` **Flags:** ``` --dry-run Parse input and echo commands without executing -f, --file string Read commands from file instead of stdin -m, --message string DOLT_COMMIT message (default: 'bd: batch N ops by ') ``` # bd blocked Source: https://beads.gascity.com/cli-reference/blocked Show blocked issues Generated from `bd help --doc blocked`. Show blocked issues ``` bd blocked [flags] ``` **Flags:** ``` --parent string Filter to descendants of this bead/epic ``` # bd bootstrap Source: https://beads.gascity.com/cli-reference/bootstrap Bootstrap sets up the beads database without destroying existing data. Generated from `bd help --doc bootstrap`. Bootstrap sets up the beads database without destroying existing data. Unlike 'bd init --force', bootstrap will never delete existing issues. Bootstrap auto-detects the right action: • If sync.remote is configured: clones from the remote • If git origin has Dolt data (refs/dolt/data): clones from git and wires origin for future push/pull • If .beads/backup/\*.jsonl exists: restores from backup • If .beads/issues.jsonl exists: imports from git-tracked JSONL • If no database exists: creates a fresh one • If database already exists: validates and reports status This is the recommended command for: • Setting up beads on a fresh clone • Recovering after moving to a new machine • Repairing a broken database configuration Non-interactive mode (--non-interactive, --yes/-y, or BD\_NON\_INTERACTIVE=1): Skips the confirmation prompt before executing the bootstrap plan. Also auto-detected when stdin is not a terminal or CI=true is set. Examples: bd bootstrap # Auto-detect and set up bd bootstrap --dry-run # Show what would be done bd bootstrap --json # Output plan as JSON bd bootstrap --yes # Skip confirmation prompt ``` bd bootstrap [flags] ``` **Flags:** ``` --dry-run Show what would be done without doing it --non-interactive Alias for --yes -y, --yes Skip confirmation prompts (for CI/automation) ``` # bd branch Source: https://beads.gascity.com/cli-reference/branch List all branches or create a new branch. Generated from `bd help --doc branch`. List all branches or create a new branch. This command requires the Dolt storage backend. Without arguments, it lists all branches. With an argument, it creates a new branch. Examples: bd branch # List all branches bd branch feature-xyz # Create a new branch named feature-xyz ``` bd branch [name] [flags] ``` # bd children Source: https://beads.gascity.com/cli-reference/children List all beads that are children of the specified parent bead. Generated from `bd help --doc children`. List all beads that are children of the specified parent bead. This is a convenience alias for 'bd list --parent \ --status all'. Unlike plain 'bd list', children includes closed issues by default, since the primary use case is inspecting all work under a parent. Examples: bd children hq-abc123 # List all children of hq-abc123 bd children hq-abc123 --json # List children in JSON format bd children hq-abc123 --pretty # Show children in tree format ``` bd children [flags] ``` **Flags:** ``` --pretty Show children in tree format ``` # bd close Source: https://beads.gascity.com/cli-reference/close Close one or more issues. Generated from `bd help --doc close`. Close one or more issues. If no issue ID is provided, closes the last touched issue (from most recent create, update, show, or close operation). When closing multiple issues, provide one --reason for all IDs or repeat \--reason once per ID. Reasons map positionally: the first --reason applies to the first ID, the second --reason to the second ID, regardless of where the flags appear in the command line. ``` bd close [id...] [flags] ``` **Aliases:** done **Flags:** ``` --claim-next Automatically claim the next highest priority available issue --continue Auto-advance to next step in molecule -f, --force Force close pinned issues or unsatisfied gates --no-auto With --continue, show next step but don't claim it -r, --reason string Reason for closing --reason-file string Read close reason from file (use - for stdin) --session string Claude Code session ID (or set CLAUDE_SESSION_ID env var) --suggest-next Show newly unblocked issues after closing ``` # bd comment Source: https://beads.gascity.com/cli-reference/comment Add a comment to an issue. Generated from `bd help --doc comment`. Add a comment to an issue. Shorthand for 'bd comments add \ "text"'. Examples: bd comment bd-123 "Working on this now" bd comment bd-123 Working on this now echo "comment from pipe" | bd comment bd-123 --stdin bd comment bd-123 --file notes.txt ``` bd comment [text...] [flags] ``` **Flags:** ``` --file string Read comment text from file --stdin Read comment text from stdin ``` # bd comments Source: https://beads.gascity.com/cli-reference/comments View or manage comments on an issue. Generated from `bd help --doc comments`. View or manage comments on an issue. Examples: # List all comments on an issue (issue id is required — there is no "comments list") bd comments bd-123 # List comments in JSON format bd comments bd-123 --json # Add a comment bd comments add bd-123 "This is a comment" # Add a comment from a file bd comments add bd-123 -f notes.txt ``` bd comments [issue-id] [flags] ``` **Flags:** ``` --local-time Show timestamps in local time instead of UTC ``` ## bd comments add Add a comment to an issue. Examples: # Add a comment bd comments add bd-123 "Working on this now" # Add a comment from a file bd comments add bd-123 -f notes.txt ``` bd comments add [issue-id] [text] [flags] ``` **Flags:** ``` -a, --author string Add author to comment -f, --file string Read comment text from file ``` ## bd comments list Invalid — use bd comments \ to list comments ``` bd comments list [flags] ``` # bd compact Source: https://beads.gascity.com/cli-reference/compact Squash Dolt commits older than N days into a single commit. Generated from `bd help --doc compact`. Squash Dolt commits older than N days into a single commit. Recent commits (within the retention window) are preserved via cherry-pick. This reduces Dolt storage overhead from auto-commit history while keeping recent change tracking intact. For semantic issue compaction (summarizing closed issues), use 'bd admin compact'. For full history squash, use 'bd flatten'. How it works: 1. Identifies commits older than --days threshold 2. Creates a squashed base commit from all old history 3. Cherry-picks recent commits on top 4. Swaps main branch to the compacted version 5. Runs Dolt GC to reclaim space Examples: bd compact --dry-run # Preview: show commit breakdown bd compact --force # Squash commits older than 30 days bd compact --days 7 --force # Keep only last 7 days of history bd compact --days 90 --force # Conservative: squash 90+ day old commits ``` bd compact [flags] ``` **Flags:** ``` --days int Keep commits newer than N days (default 30) --dry-run Preview without making changes -f, --force Confirm commit squash ``` # bd completion Source: https://beads.gascity.com/cli-reference/completion Generate the autocompletion script for bd for the specified shell. Generated from `bd help --doc completion`. Generate the autocompletion script for bd for the specified shell. See each sub-command's help for details on how to use the generated script. ``` bd completion [flags] ``` ## bd completion bash Generate the autocompletion script for the bash shell. This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager. To load completions in your current shell session: source \<(bd completion bash) To load completions for every new session, execute once: ### Linux: bd completion bash > /etc/bash\_completion.d/bd ### macOS: bd completion bash > \$(brew --prefix)/etc/bash\_completion.d/bd You will need to start a new shell for this setup to take effect. ``` bd completion bash ``` **Flags:** ``` --no-descriptions disable completion descriptions ``` ## bd completion fish Generate the autocompletion script for the fish shell. To load completions in your current shell session: bd completion fish | source To load completions for every new session, execute once: bd completion fish > \~/.config/fish/completions/bd.fish You will need to start a new shell for this setup to take effect. ``` bd completion fish [flags] ``` **Flags:** ``` --no-descriptions disable completion descriptions ``` ## bd completion powershell Generate the autocompletion script for powershell. To load completions in your current shell session: bd completion powershell | Out-String | Invoke-Expression To load completions for every new session, add the output of the above command to your powershell profile. ``` bd completion powershell [flags] ``` **Flags:** ``` --no-descriptions disable completion descriptions ``` ## bd completion zsh Generate the autocompletion script for the zsh shell. If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once: echo "autoload -U compinit; compinit" >> \~/.zshrc To load completions in your current shell session: source \<(bd completion zsh) To load completions for every new session, execute once: ### Linux: bd completion zsh > "\$\{fpath\[1]}/\_bd" ### macOS: bd completion zsh > \$(brew --prefix)/share/zsh/site-functions/\_bd You will need to start a new shell for this setup to take effect. ``` bd completion zsh [flags] ``` **Flags:** ``` --no-descriptions disable completion descriptions ``` # bd config Source: https://beads.gascity.com/cli-reference/config Manage configuration settings for external integrations and preferences. Generated from `bd help --doc config`. Manage configuration settings for external integrations and preferences. Configuration is stored per-project in the beads database and is version-control-friendly. Common namespaces: * export.\* Auto-export settings (stored in config.yaml) * import.\* JSONL import settings (stored in config.yaml) * jira.\* Jira integration settings * linear.\* Linear integration settings * github.\* GitHub integration settings * custom.\* Custom integration settings * status.\* Issue status configuration * doctor.suppress.\* Suppress specific bd doctor warnings (GH#1095) Auto-Export (config.yaml): Optional JSONL export to .beads/issues.jsonl after write commands (throttled). Useful for viewers (bv), interchange, and issue-level migration; not a backup. It is not cross-machine sync; use bd dolt push/pull with a Dolt remote. Disabled by default. Enable only for integrations that need fresh JSONL. Auto-staging is separate and disabled by default. Keys: export.auto Enable/disable auto-export (default: false) export.path Output filename relative to .beads/ (default: issues.jsonl) export.interval Minimum time between exports (default: 60s) export.git-add Auto-stage the export file (default: false) Auto-Import (config.yaml): Reads .beads/issues.jsonl by default when a JSONL import path is implied. Use a relative filename/path so the import stays within the project .beads/ directory and remains portable across machines. Keys: import.path Input filename relative to .beads/ (default: issues.jsonl) Custom Status States: You can define custom status states for multi-step pipelines using the status.custom config key. Statuses should be comma-separated. Example: bd config set status.custom "awaiting\_review,awaiting\_testing,awaiting\_docs" This enables issues to use statuses like 'awaiting\_review' in addition to the built-in statuses (open, in\_progress, blocked, deferred, closed). Suppressing Doctor Warnings: Suppress specific bd doctor warnings by check name slug: bd config set doctor.suppress.pending-migrations true bd config set doctor.suppress.git-hooks true Check names are converted to slugs: "Git Hooks" → "git-hooks". Only warnings are suppressed (errors and passing checks always show). To unsuppress: bd config unset doctor.suppress.\ Examples: bd config set export.auto true # Enable auto-export for viewer integrations bd config set export.path "beads.jsonl" # Custom export filename bd config set import.path "beads.jsonl" # Custom import filename bd config set export.git-add true # Also stage the export file bd config set jira.url "[https://company.atlassian.net](https://company.atlassian.net)" bd config set jira.project "PROJ" bd config set status.custom "awaiting\_review,awaiting\_testing" bd config set doctor.suppress.pending-migrations true bd config set dolt.debug true # Enable Dolt sql-server debug mode (loglevel=debug, --prof cpu) bd config set dolt.local-only true # Skip wiring a Dolt sync remote during bd init bd config get export.auto bd config list bd config unset jira.url ``` bd config [flags] ``` ## bd config apply Reconcile actual system state to match declared configuration. Runs drift detection and then fixes any mismatches it finds: * hooks Reinstall git hooks if missing or outdated * remote Add/update Dolt origin remote to match federation.remote * server Start Dolt server if dolt.shared-server is enabled This command is idempotent — safe to run multiple times. Use --dry-run to preview what would change without making modifications. Examples: bd config apply bd config apply --dry-run bd config apply --json ``` bd config apply [flags] ``` **Flags:** ``` --dry-run Show what would change without making modifications ``` ## bd config drift Detect drift between declared configuration and actual system state. This is a read-only diagnostic that answers "is my environment consistent with my config?" — no mutations are performed. Checks: * hooks Git hooks installed and up-to-date * remote Dolt remote matches federation.remote config * server Server state matches dolt.shared-server config Exit codes: 0 No drift detected (all checks ok/info/skipped) 1 Drift detected (at least one check has status "drift") Examples: bd config drift bd config drift --json ``` bd config drift [flags] ``` ## bd config get Get a configuration value ``` bd config get [flags] ``` ## bd config list List all configuration ``` bd config list [flags] ``` ## bd config set Set a configuration value ``` bd config set [flags] ``` **Flags:** ``` --force-git-tracked Allow writing secret keys to git-tracked config files (use with caution) ``` ## bd config set-many Set multiple configuration values at once with a single auto-commit and auto-push. Each argument must be in key=value format. All values are validated before any writes occur. This is faster and less noisy than separate 'bd config set' calls, especially in CI. Examples: bd config set-many ado.state\_map.open=New ado.state\_map.closed=Closed bd config set-many jira.url=[https://example.atlassian.net](https://example.atlassian.net) jira.project=PROJ ``` bd config set-many ... [flags] ``` **Flags:** ``` --force-git-tracked Allow writing secret keys to git-tracked config files (use with caution) ``` ## bd config show Display a unified view of all effective configuration across all sources with annotations showing where each value comes from. Sources (by precedence for Viper-managed keys): * env Environment variable (BD\_\* or BEADS\_\*) * config.yaml Project config file (.beads/config.yaml) * default Built-in default value Additional sources: * metadata Connection settings from .beads/metadata.json * database Integration config stored in the Dolt database * git Git config (e.g., beads.role) Examples: bd config show bd config show --json bd config show --source config.yaml ``` bd config show [flags] ``` **Flags:** ``` --source string Filter by source (e.g., config.yaml, env, default, metadata, database, git) ``` ## bd config unset Delete a configuration value ``` bd config unset [flags] ``` ## bd config validate Validate sync-related configuration settings. Checks: * federation.sovereignty is valid (T1, T2, T3, T4, or empty) * federation.remote is set for Dolt sync * Remote URL format is valid (dolthub://, gs\://, s3://, az://, file://) * routing.mode is valid (auto, maintainer, contributor, explicit) Examples: bd config validate bd config validate --json ``` bd config validate [flags] ``` # bd context Source: https://beads.gascity.com/cli-reference/context Show the effective backend identity information including repository paths, Generated from `bd help --doc context`. Show the effective backend identity information including repository paths, backend configuration, and sync settings. This command reads directly from config files and does not require the database to be open, making it useful for diagnostics in degraded states. Examples: bd context # Show context information bd context --json # Output in JSON format ``` bd context [flags] ``` # bd cook Source: https://beads.gascity.com/cli-reference/cook Cook transforms a .formula.json file into a proto. Generated from `bd help --doc cook`. Cook transforms a .formula.json file into a proto. By default, cook outputs the resolved formula as JSON to stdout for ephemeral use. The output can be inspected, piped, or saved to a file. Two cooking modes are available: COMPILE-TIME (default, --mode=compile): Produces a proto with \{\{variable}} placeholders intact. Use for: modeling, estimation, contractor handoff, planning. Variables are NOT substituted - the output shows the template structure. RUNTIME (--mode=runtime or when --var flags provided): Produces a fully-resolved proto with variables substituted. Use for: final validation before pour, seeing exact output. Requires all variables to have values (via --var or defaults). Formulas are high-level workflow templates that support: * Variable definitions with defaults and validation * Step definitions that become issue hierarchies * Composition rules for bonding formulas together * Inheritance via extends The --persist flag enables the legacy behavior of writing the proto to the database. This is useful when you want to reuse the same proto multiple times without re-cooking. For most workflows, prefer ephemeral protos: pour and wisp commands accept formula names directly and cook inline. Examples: bd cook mol-feature.formula.json # Compile-time: keep \{\{vars}} bd cook mol-feature --var name=auth # Runtime: substitute vars bd cook mol-feature --mode=runtime --var name=auth # Explicit runtime mode bd cook mol-feature --dry-run # Preview steps bd cook mol-release.formula.json --persist # Write to database bd cook mol-release.formula.json --persist --force # Replace existing Output (default): JSON representation of the resolved formula with all steps. Output (--persist): Creates a proto bead in the database with: * ID matching the formula name (e.g., mol-feature) * The "template" label for proto identification * Child issues for each step * Dependencies matching depends\_on relationships ``` bd cook [flags] ``` **Flags:** ``` --dry-run Preview what would be created --force Replace existing proto if it exists (requires --persist) --mode string Cooking mode: compile (keep placeholders) or runtime (substitute vars) --persist Persist proto to database (legacy behavior) --prefix string Prefix to prepend to proto ID (e.g., 'gt-' creates 'gt-mol-feature') --search-path strings Additional paths to search for formula inheritance --var stringArray Variable substitution (key=value), enables runtime mode ``` # bd count Source: https://beads.gascity.com/cli-reference/count Count issues matching the specified filters. Generated from `bd help --doc count`. Count issues matching the specified filters. By default, returns the total count of issues matching the filters. Use --by-\* flags to group counts by different attributes. Examples: bd count # Count all issues bd count --status open # Count open issues bd count --by-status # Group count by status bd count --by-priority # Group count by priority bd count --by-type # Group count by issue type bd count --by-assignee # Group count by assignee bd count --by-label # Group count by label bd count --assignee alice --by-status # Count alice's issues by status bd count --include-infra # Count issues + wisps tier (matches 'bd list --include-infra --all' cardinality) ``` bd count [flags] ``` **Flags:** ``` -a, --assignee string Filter by assignee --by-assignee Group count by assignee --by-label Group count by label --by-priority Group count by priority --by-status Group count by status --by-type Group count by issue type --closed-after string Filter issues closed after date (YYYY-MM-DD or RFC3339) --closed-before string Filter issues closed before date (YYYY-MM-DD or RFC3339) --created-after string Filter issues created after date (YYYY-MM-DD or RFC3339) --created-before string Filter issues created before date (YYYY-MM-DD or RFC3339) --desc-contains string Filter by description substring --empty-description Filter issues with empty description --id string Filter by specific issue IDs (comma-separated) --include-infra Include infrastructure beads and the wisps tier (matches 'bd list --include-infra --all' cardinality) -l, --label strings Filter by labels (AND: must have ALL) --label-any strings Filter by labels (OR: must have AT LEAST ONE) --no-assignee Filter issues with no assignee --no-labels Filter issues with no labels --notes-contains string Filter by notes substring -p, --priority int Filter by priority (0-4: 0=critical, 1=high, 2=medium, 3=low, 4=backlog) --priority-max int Filter by maximum priority (inclusive) --priority-min int Filter by minimum priority (inclusive) -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Note: dependency-blocked issues use 'bd blocked' --title string Filter by title text (case-insensitive substring match) --title-contains string Filter by title substring -t, --type string Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate) --updated-after string Filter issues updated after date (YYYY-MM-DD or RFC3339) --updated-before string Filter issues updated before date (YYYY-MM-DD or RFC3339) ``` # bd create Source: https://beads.gascity.com/cli-reference/create Create a new issue (or batch from markdown/graph JSON) Generated from `bd help --doc create`. Create a new issue (or batch from markdown/graph JSON) ``` bd create [title] [flags] ``` **Aliases:** new **Flags:** ``` --acceptance string Acceptance criteria --append-notes string Append to existing notes (with newline separator) -a, --assignee string Assignee --body-file string Read description from file (use - for stdin) --context string Additional context for the issue --defer string Defer until date (issue hidden from bd ready until then). Same formats as --due --deps strings Dependencies in format 'type:id' or 'id' (e.g., 'discovered-from:bd-20,blocks:bd-15' or 'bd-20') -d, --description string Issue description --design string Design notes --design-file string Read design from file (use - for stdin) --dry-run Preview what would be created without actually creating --due string Due date/time. Formats: +6h, +1d, +2w, tomorrow, next monday, 2025-01-15 --ephemeral Create as ephemeral (short-lived, subject to TTL compaction) -e, --estimate int Time estimate in minutes (e.g., 60 for 1 hour) --event-actor string Entity URI who caused this event (requires --type=event) --event-category string Event category (e.g., patrol.muted, agent.started) (requires --type=event) --event-payload string Event-specific JSON data (requires --type=event) --event-target string Entity URI or bead ID affected (requires --type=event) --external-ref string External reference (e.g., 'gh-9', 'jira-ABC', Linear URL) -f, --file string Create multiple issues from markdown file --force Force creation even if prefix doesn't match database prefix --graph string Create a graph of issues with dependencies from JSON plan file --id string Explicit issue ID (e.g., 'bd-42' for partitioning) -l, --labels strings Labels (comma-separated) --metadata string Set custom metadata (JSON string or @file.json to read from file) --mol-type string Molecule type: swarm (multi-agent), patrol (recurring ops), work (default) --no-history Skip Dolt commit history without making GC-eligible (for permanent agent beads) --no-inherit-labels Don't inherit labels from parent issue --notes string Additional notes --parent string Parent issue ID for hierarchical child (e.g., 'bd-a3f8e9') -p, --priority string Priority (0-4 or P0-P4, 0=highest) (default "2") --repo string Target repository for issue (overrides auto-routing) --silent Output only the issue ID (for scripting) --skills string Required skills for this issue --spec-id string Link to specification document --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); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision (default "task") --validate Validate description contains required sections for issue type --waits-for string Spawner issue ID to wait for (creates waits-for dependency for fanout gate) --waits-for-gate string Gate type: all-children (wait for all) or any-children (wait for first) (default "all-children") --wisp-type string Wisp type for TTL-based compaction: heartbeat, ping, patrol, gc_report, recovery, error, escalation ``` # bd create-form Source: https://beads.gascity.com/cli-reference/create-form Create a new issue using an interactive terminal form. Generated from `bd help --doc create-form`. Create a new issue using an interactive terminal form. This command provides a user-friendly form interface for creating issues, with fields for title, description, type, priority, labels, and more. Use --parent to create a sub-issue under an existing parent issue. The child will get an auto-generated hierarchical ID (e.g., parent-id.1). The form uses keyboard navigation: * Tab/Shift+Tab: Move between fields * Enter: Submit the form (on the last field or submit button) * Ctrl+C: Cancel and exit * Arrow keys: Navigate within select fields ``` bd create-form [flags] ``` **Flags:** ``` --parent string Parent issue ID for creating a hierarchical child (e.g., 'bd-a3f8e9') ``` # bd defer Source: https://beads.gascity.com/cli-reference/defer Defer issues to put them on ice for later. Generated from `bd help --doc defer`. Defer issues to put them on ice for later. Deferred issues are deliberately set aside - not blocked by anything specific, just postponed for future consideration. Unlike blocked issues, there's no dependency keeping them from being worked. Unlike closed issues, they will be revisited. Deferred issues don't show in 'bd ready' but remain visible in 'bd list'. Examples: bd defer bd-abc # Defer a single issue (status-based) bd defer bd-abc --until=tomorrow # Defer until specific time bd defer bd-abc --reason="waiting on API access" bd defer bd-abc bd-def # Defer multiple issues ``` bd defer [id...] [flags] ``` **Flags:** ``` --reason string Record why this issue is being deferred (appended to notes) --until string Defer until specific time (e.g., +1h, tomorrow, next monday) ``` # bd delete Source: https://beads.gascity.com/cli-reference/delete Delete one or more issues and clean up all references to them. Generated from `bd help --doc delete`. Delete one or more issues and clean up all references to them. This command will: 1. Remove all dependency links (any type, both directions) involving the issues 2. Update text references to "\[deleted:ID]" in directly connected issues 3. Permanently delete the issues from the database This is a destructive operation that cannot be undone. Use with caution. BATCH DELETION: Delete multiple issues at once: bd delete bd-1 bd-2 bd-3 --force Delete from file (one ID per line): bd delete --from-file deletions.txt --force Preview before deleting: bd delete --from-file deletions.txt --dry-run DEPENDENCY HANDLING: Default: Fails if any issue has dependents not in deletion set bd delete bd-1 bd-2 Cascade: Recursively delete all dependents bd delete bd-1 --cascade --force Force: Delete and orphan dependents bd delete bd-1 --force ``` bd delete [issue-id...] [flags] ``` **Flags:** ``` --cascade Recursively delete all dependent issues --dry-run Preview what would be deleted without making changes -f, --force Actually delete (without this flag, shows preview) --from-file string Read issue IDs from file (one per line) ``` # bd dep Source: https://beads.gascity.com/cli-reference/dep Manage dependencies between issues. Generated from `bd help --doc dep`. Manage dependencies between issues. When called with an issue ID and --blocks flag, creates a blocking dependency: bd dep \ --blocks \ This is equivalent to: bd dep add \ \ Examples: bd dep bd-xyz --blocks bd-abc # bd-xyz blocks bd-abc bd dep add bd-abc bd-xyz # Same as above (bd-abc depends on bd-xyz) ``` bd dep [issue-id] [flags] ``` **Flags:** ``` -b, --blocks string Issue ID that this issue blocks (shorthand for: bd dep add ) --no-cycle-check Skip per-edge cycle checks for speed (bulk wiring); bulk --file adds still run one final whole-graph check before commit ``` ## bd dep add Add a dependency between two issues. The depends-on-id can be provided as: * A positional argument: bd dep add issue-123 issue-456 * A flag: bd dep add issue-123 --blocked-by issue-456 * A flag: bd dep add issue-123 --depends-on issue-456 The --blocked-by and --depends-on flags are aliases and both mean "issue-123 depends on (is blocked by) the specified issue." The depends-on-id can be: * A local issue ID (e.g., bd-xyz) * An external reference: external:\:\ For bulk wiring, pass newline-delimited JSON with --file. Each line must be an object with "from" and "to" fields, and may include "type". The aliases "issue\_id" and "depends\_on\_id" are also accepted. Use --file - to read stdin. External references are stored as-is and resolved at query time using the external\_projects config. They block the issue until the capability is "shipped" in the target project. Examples: bd dep add bd-42 bd-41 # Positional args bd dep add bd-42 --blocked-by bd-41 # Flag syntax (same effect) bd dep add bd-42 --depends-on bd-41 # Alias (same effect) bd dep add gt-xyz external:beads:mol-run-assignee # Cross-project dependency bd dep add bd-42 bd-41 --no-cycle-check # Skip cycle check (bulk wiring) bd dep add --file deps.jsonl # Bulk JSONL: \{"from":"bd-42","to":"bd-41"} ``` bd dep add [issue-id] [depends-on-id] [flags] ``` **Flags:** ``` --blocked-by string Issue ID that blocks the first issue (alternative to positional arg) --depends-on string Issue ID that the first issue depends on (alias for --blocked-by) --file string Read dependency edges from JSONL file, or '-' for stdin --no-cycle-check Skip per-edge cycle checks for speed (bulk wiring); bulk --file adds still run one final whole-graph check before commit -t, --type string Dependency type (blocks|tracks|related|parent-child|discovered-from|until|caused-by|validates|relates-to|supersedes) (default "blocks") ``` ## bd dep cycles Detect dependency cycles ``` bd dep cycles [flags] ``` ## bd dep list List dependencies or dependents of one or more issues with optional type filtering. By default shows dependencies (what issues depend on). Use --direction to control: * down: Show dependencies (what this issue depends on) - default * up: Show dependents (what depends on this issue) Multiple IDs can be provided for batch dep listing. With --json, the output is a flat array of dependency records across all requested issues. Use --type to filter by dependency type (e.g., tracks, blocks, parent-child). Examples: bd dep list gt-abc # Show what gt-abc depends on bd dep list gt-abc gt-def # Batch: deps for both issues bd dep list gt-abc --direction=up # Show what depends on gt-abc bd dep list gt-abc --direction=up -t tracks # Show what tracks gt-abc (convoy tracking) ``` bd dep list [issue-id...] [flags] ``` **Flags:** ``` --direction string Direction: 'down' (dependencies), 'up' (dependents) (default "down") -t, --type string Filter by dependency type (e.g., tracks, blocks, parent-child) ``` ## bd dep relate Create a loose 'see also' relationship between two issues. The relates\_to link is bidirectional - both issues will reference each other. This enables knowledge graph connections without blocking or hierarchy. Examples: bd relate bd-abc bd-xyz # Link two related issues bd relate bd-123 bd-456 # Create see-also connection ``` bd dep relate [flags] ``` ## bd dep remove Remove a dependency ``` bd dep remove [issue-id] [depends-on-id] [flags] ``` **Aliases:** rm ## bd dep tree Show dependency tree rooted at the given issue. By default, shows dependencies (what blocks this issue). Use --direction to control: * down: Show dependencies (what blocks this issue) - default * up: Show dependents (what this issue blocks) * both: Show full graph in both directions Examples: bd dep tree gt-0iqq # Show what blocks gt-0iqq bd dep tree gt-0iqq --direction=up # Show what gt-0iqq blocks bd dep tree gt-0iqq --status=open # Only show open issues bd dep tree gt-0iqq --depth=3 # Limit to 3 levels deep ``` bd dep tree [issue-id] [flags] ``` **Flags:** ``` --direction string Tree direction: 'down' (dependencies), 'up' (dependents), or 'both' --format string Output format: 'mermaid' for Mermaid.js flowchart -d, --max-depth int Maximum tree depth to display (safety limit) (default 50) --reverse Show dependent tree (deprecated: use --direction=up) --show-all-paths Show all paths to nodes (no deduplication for diamond dependencies) --status string Filter to only show issues with this status (open, in_progress, blocked, deferred, closed) ``` ## bd dep unrelate Remove a relates\_to relationship between two issues. Removes the link in both directions. Example: bd unrelate bd-abc bd-xyz ``` bd dep unrelate [flags] ``` # bd diff Source: https://beads.gascity.com/cli-reference/diff Show the differences in issues between two commits or branches. Generated from `bd help --doc diff`. Show the differences in issues between two commits or branches. The refs can be: * Commit hashes (e.g., abc123def) * Branch names (e.g., main, feature-branch) * Special refs like HEAD, HEAD\~1 Examples: bd diff main feature-branch # Compare main to feature branch bd diff HEAD\~5 HEAD # Show changes in last 5 commits bd diff abc123 def456 # Compare two specific commits ``` bd diff [flags] ``` # bd doctor Source: https://beads.gascity.com/cli-reference/doctor Sanity check the beads installation for the current directory or specified path. Generated from `bd help --doc doctor`. Sanity check the beads installation for the current directory or specified path. This command checks: * If .beads/ directory exists * Database version and migration status * Schema compatibility (all required tables and columns present) * Whether using hash-based vs sequential IDs * If CLI version is current (checks GitHub releases) * If Claude plugin is current (when running in Claude Code) * File permissions * Circular dependencies * Git hooks (pre-commit, post-merge, pre-push) * .beads/.gitignore up to date * Metadata.json version tracking (LastBdVersion field) Performance Mode (--perf): Run performance diagnostics on your database: * Times key operations (bd ready, bd list, bd show, etc.) * Collects system info (OS, arch, SQLite version, database stats) * Generates CPU profile for analysis * Outputs shareable report for bug reports Export Mode (--output): Save diagnostics to a JSON file for historical analysis and bug reporting. Includes timestamp and platform info for tracking intermittent issues. Specific Check Mode (--check): Run a specific check in detail. Available checks: * artifacts: Detect and optionally clean beads classic artifacts (stale JSONL, SQLite files, cruft .beads dirs). Use with --clean. * conventions: Check for convention drift (lint warnings, stale issues, orphaned issues). Advisory only - warns, never blocks. * pollution: Detect and optionally clean test issues from database * validate: Run focused data-integrity checks (duplicates, orphaned deps, test pollution, git conflicts). Use with --fix to auto-repair. Deep Validation Mode (--deep): Validate full graph integrity. May be slow on large databases. Additional checks: * Parent consistency: All parent-child deps point to existing issues * Dependency integrity: All deps reference valid issues * Epic completeness: Find epics ready to close (all children closed) * Agent bead integrity: Agent beads have valid state values * Mail thread integrity: Thread IDs reference existing issues * Molecule integrity: Molecules have valid parent-child structures Server Mode (--server): Run health checks for Dolt server mode connections (bd-dolt.2.3): * Server reachable: Can connect to configured host:port? * Dolt version: Is it a Dolt server (not vanilla MySQL)? * Database exists: Does the 'beads' database exist? * Schema compatible: Can query beads tables? * Connection pool: Pool health metrics Migration Validation Mode (--migration): Run Dolt migration validation checks with machine-parseable output. Use --migration=pre before migration to verify readiness: * JSONL file exists and is valid (parseable, no corruption) * All JSONL issues are present in SQLite (or explains discrepancies) * No blocking issues prevent migration Use --migration=post after migration to verify completion: * Dolt database exists and is healthy * All issues from JSONL are present in Dolt * No data was lost during migration * Dolt database has no locks or uncommitted changes Combine with --json for machine-parseable output for automation. Agent Mode (--agent): Output diagnostics designed for AI agent consumption. Instead of terse pass/fail messages, each issue includes: * Observed state: what the system actually looks like * Expected state: what it should look like * Explanation: full prose context about the issue and why it matters * Commands: exact remediation commands to run * Source files: where in the codebase to investigate further * Severity: blocking (prevents operation), degraded (partial function), or advisory (informational only) ZFC-compliant: Go observes and reports, the agent decides and acts. Combine with --json for structured agent-facing output. Suppressing Warnings: Suppress specific warnings by setting doctor.suppress.\ config: bd config set doctor.suppress.pending-migrations true bd config set doctor.suppress.git-hooks true Check names are converted to slugs: "Git Hooks" → "git-hooks". Only warnings are suppressed; errors and passing checks always show. To unsuppress: bd config unset doctor.suppress.\ Examples: bd doctor # Check current directory bd doctor /path/to/repo # Check specific repository bd doctor --json # Machine-readable output bd doctor --agent # Agent-facing diagnostic output bd doctor --agent --json # Structured agent diagnostics (JSON) bd doctor --fix # Automatically fix issues (with confirmation) bd doctor --fix --yes # Automatically fix issues (no confirmation) bd doctor --fix -i # Confirm each fix individually bd doctor --fix --fix-child-parent # Also fix child→parent deps (opt-in) bd doctor --fix --force # Force repair even when database can't be opened bd doctor --fix --source=jsonl # Rebuild database from a JSONL export bd doctor --dry-run # Preview what --fix would do without making changes bd doctor --perf # Performance diagnostics bd doctor --output diagnostics.json # Export diagnostics to file bd doctor --check=artifacts # Show classic artifacts (JSONL, SQLite, cruft dirs) bd doctor --check=artifacts --clean # Delete safe-to-delete artifacts (with confirmation) bd doctor --check=conventions # Convention drift check (lint, stale, orphans) bd doctor --check=pollution # Show potential test issues bd doctor --check=pollution --clean # Delete test issues (with confirmation) bd doctor --check=validate # Data-integrity checks only bd doctor --check=validate --fix # Auto-fix data-integrity issues bd doctor --deep # Full graph integrity validation bd doctor --server # Dolt server mode health checks bd doctor --migration=pre # Validate readiness for Dolt migration bd doctor --migration=post # Validate Dolt migration completed bd doctor --migration=pre --json # Machine-parseable migration validation ``` bd doctor [path] [flags] ``` **Flags:** ``` --agent Agent-facing diagnostic mode: rich context for AI agents (ZFC-compliant) --check string Run specific check in detail (e.g., 'pollution') --check-health Quick health check for git hooks (silent on success) --clean For pollution check: delete detected test issues --deep Validate full graph integrity --dry-run Preview fixes without making changes --fix Automatically fix issues where possible --fix-child-parent Remove child→parent dependencies (opt-in) -i, --interactive Confirm each fix individually --migration string Run Dolt migration validation: 'pre' (before migration) or 'post' (after migration) --orchestrator Running in orchestrator multi-workspace mode (routes.jsonl is expected, higher duplicate tolerance) --orchestrator-duplicates-threshold int Duplicate tolerance threshold for orchestrator mode (wisps are ephemeral) (default 1000) -o, --output string Export diagnostics to JSON file --perf Run performance diagnostics and generate CPU profile --server Run Dolt server mode health checks (connectivity, version, schema) -v, --verbose Show all checks (default shows only warnings/errors) -y, --yes Skip confirmation prompt (for non-interactive use) ``` # bd dolt Source: https://beads.gascity.com/cli-reference/dolt Configure and manage Dolt database settings and server lifecycle. Generated from `bd help --doc dolt`. Configure and manage Dolt database settings and server lifecycle. Beads uses a dolt sql-server for all database operations. The server is auto-started transparently when needed. Use these commands for explicit control or diagnostics. Server lifecycle: bd dolt start Start the Dolt server for this project bd dolt stop Stop the Dolt server for this project bd dolt status Show Dolt server status Configuration: bd dolt show Show current Dolt configuration with connection test bd dolt set \ \ Set a configuration value bd dolt test Test server connection Version control: bd dolt commit Commit pending changes bd dolt push Push commits to Dolt remote bd dolt pull Pull commits from Dolt remote Remote management: bd dolt remote add \ \ Add a Dolt remote bd dolt remote list List configured remotes bd dolt remote remove \ Remove a Dolt remote Configuration keys for 'bd dolt set': database Database name (default: issue prefix or "beads") host Server host (default: 127.0.0.1) port Server port (auto-detected; override with bd dolt set port \) user MySQL user (default: root) data-dir Custom dolt data directory (absolute path; default: .beads/dolt) Flags for 'bd dolt set': \--update-config Also write to config.yaml for team-wide defaults Examples: bd dolt set database myproject bd dolt set host 192.168.1.100 --update-config bd dolt set data-dir /home/user/.beads-dolt/myproject bd dolt test ``` bd dolt [flags] ``` ## bd dolt clean-databases Identify and drop leftover test and agent databases that accumulate on the shared Dolt server from interrupted test runs and terminated agents. Stale database prefixes: testdb\_*, 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. ``` bd dolt clean-databases [flags] ``` **Flags:** ``` --dry-run Show what would be dropped without dropping ``` ## bd dolt commit Create a Dolt commit from any uncommitted changes in the working set. This is the primary commit point for batch mode. When auto-commit is set to "batch", changes accumulate in the working set across multiple bd commands and are committed together here with a descriptive summary message. Also useful before push operations that require a clean working set, or when auto-commit was off or changes were made externally. For more options (--stdin, custom messages), see: bd vc commit ``` bd dolt commit [flags] ``` **Flags:** ``` -m, --message string Commit message (default: auto-generated) ``` ## bd dolt killall Find and kill orphan dolt sql-server processes not tracked by the canonical PID file for the current repo's Dolt data directory. Under an orchestrator, the canonical server lives at \$GT\_ROOT/.beads/. Any other dolt sql-server processes using that shared data directory are considered orphans and will be killed. In standalone mode, only dolt sql-server processes using the current project's Dolt data directory are eligible for cleanup. Other projects' servers are preserved. ``` bd dolt killall [flags] ``` ## bd dolt pull Pull commits from the configured Dolt remote into the local database. Requires a Dolt remote to be configured in the database directory. For Hosted Dolt, set DOLT\_REMOTE\_USER and DOLT\_REMOTE\_PASSWORD environment variables for authentication. Use --remote to pull from a specific named remote instead of the default. The remote must already exist (see 'bd dolt remote add'). ``` bd dolt pull [flags] ``` **Flags:** ``` --remote string Pull from a specific named remote instead of the default ``` ## bd dolt push Push local Dolt commits to the configured remote. Requires a Dolt remote to be configured in the database directory. For Hosted Dolt, set DOLT\_REMOTE\_USER and DOLT\_REMOTE\_PASSWORD environment variables for authentication. Use --force to overwrite remote changes (e.g., when the remote has uncommitted changes in its working set). Use --remote to push to a specific named remote instead of the default. The remote must already exist (see 'bd dolt remote add'). ``` bd dolt push [flags] ``` **Flags:** ``` --force Force push (overwrite remote changes) --remote string Push to a specific named remote instead of the default ``` ## bd dolt remote Manage Dolt remotes for push/pull replication. Subcommands: add \ \ Add a new remote list List all configured remotes remove \ Remove a remote ``` bd dolt remote [flags] ``` ### bd dolt remote add Add a Dolt remote ``` bd dolt remote add [flags] ``` ### bd dolt remote list List configured Dolt remotes ``` bd dolt remote list [flags] ``` ### bd dolt remote remove Remove a Dolt remote ``` bd dolt remote remove [flags] ``` ## bd dolt set Set a Dolt configuration value in metadata.json. Keys: database Database name (default: issue prefix or "beads") host Server host (default: 127.0.0.1) port Server port (auto-detected; override with bd dolt set port \) user MySQL user (default: root) data-dir Custom dolt data directory (absolute path; default: .beads/dolt) Use --update-config to also write to config.yaml for team-wide defaults. Examples: bd dolt set database myproject bd dolt set host 192.168.1.100 bd dolt set port 3307 --update-config bd dolt set data-dir /home/user/.beads-dolt/myproject ``` bd dolt set [flags] ``` **Flags:** ``` --update-config Also write to config.yaml for team-wide defaults ``` ## bd dolt show Show current Dolt configuration with connection status ``` bd dolt show [flags] ``` ## bd dolt start Start a dolt sql-server for the current beads project. The server runs in the background on a per-project port derived from the project path. PID and logs are stored in .beads/. The server auto-starts transparently when needed, so manual start is rarely required. Use this command for explicit control or diagnostics. ``` bd dolt start [flags] ``` ## bd dolt status Show the status of the Dolt engine for the current project. In embedded mode, reports that the Dolt engine runs in-process and shows the on-disk data directory. For beads-managed (local) servers, displays PID, port, and data directory from the local PID file. For externally- managed servers — 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] ``` ## bd dolt stop Stop the dolt sql-server managed by beads for the current project. This sends a graceful shutdown signal. The server will restart automatically on the next bd command unless auto-start is disabled. ``` bd dolt stop [flags] ``` **Flags:** ``` --force Force stop the server ``` ## bd dolt test Test the connection to the configured Dolt server. This verifies that: 1. The server is reachable at the configured host:port 2. The connection can be established Use this before switching to server mode to ensure the server is running. ``` bd dolt test [flags] ``` # bd duplicate Source: https://beads.gascity.com/cli-reference/duplicate Mark an issue as a duplicate of a canonical issue. Generated from `bd help --doc duplicate`. Mark an issue as a duplicate of a canonical issue. The duplicate issue is automatically closed with a reference to the canonical. This is essential for large issue databases with many similar reports. Examples: bd duplicate bd-abc --of bd-xyz # Mark bd-abc as duplicate of bd-xyz ``` bd duplicate --of [flags] ``` **Flags:** ``` --of string Canonical issue ID (required) ``` # bd duplicates Source: https://beads.gascity.com/cli-reference/duplicates Find issues with identical content (title, description, design, acceptance criteria). Generated from `bd help --doc duplicates`. Find issues with identical content (title, description, design, acceptance criteria). Groups issues by content hash and reports duplicates with suggested merge targets. The merge target is chosen by: 1. Reference count (most referenced issue wins) 2. Lexicographically smallest ID if reference counts are equal Only groups issues with matching status (open with open, closed with closed). Example: bd duplicates # Show all duplicate groups bd duplicates --auto-merge # Automatically merge all duplicates bd duplicates --dry-run # Show what would be merged ``` bd duplicates [flags] ``` **Flags:** ``` --auto-merge Automatically merge all duplicates --dry-run Show what would be merged without making changes ``` # bd edit Source: https://beads.gascity.com/cli-reference/edit Edit an issue field using your configured $EDITOR. Generated from `bd help --doc edit`. Edit an issue field using your configured \$EDITOR. By default, edits the description. Use flags to edit other fields. Examples: bd edit bd-42 # Edit description bd edit bd-42 --title # Edit title bd edit bd-42 --design # Edit design notes bd edit bd-42 --notes # Edit notes bd edit bd-42 --acceptance # Edit acceptance criteria ``` bd edit [id] [flags] ``` **Flags:** ``` --acceptance Edit the acceptance criteria --description Edit the description (default) --design Edit the design notes --notes Edit the notes --title Edit the title ``` # bd epic Source: https://beads.gascity.com/cli-reference/epic Epic management commands Generated from `bd help --doc epic`. Epic management commands ``` bd epic [flags] ``` ## bd epic close-eligible Close epics where all children are complete ``` bd epic close-eligible [flags] ``` **Flags:** ``` --dry-run Preview what would be closed without making changes ``` ## bd epic status Show epic completion status ``` bd epic status [flags] ``` **Flags:** ``` --eligible-only Show only epics eligible for closure ``` # bd export Source: https://beads.gascity.com/cli-reference/export Export all issues to JSONL (newline-delimited JSON) format. Generated from `bd help --doc export`. Export all issues to JSONL (newline-delimited JSON) format. Each line is a complete JSON object representing one issue, including its labels, dependencies, and comments. This command is for issue export, migration, and interoperability. It exports records from the issues table; it is not a full database backup and does not capture Dolt branches, commit history, working-set state, or non-issue tables. For supported full backup/restore flows, use 'bd backup init', 'bd backup sync', and 'bd backup restore'. By default, exports only regular issues (excluding infrastructure beads like agents, roles, and messages). Use --all to include everything. Memories (from 'bd remember') are excluded by default because they may contain sensitive agent context. Use --include-memories or --all to include them. EXAMPLES: bd export # Export issues to stdout bd export -o issues.jsonl # Export issues to file bd export --include-memories # Export issues + memories bd export --all -o full.jsonl # Include infra + templates + gates + memories bd export --scrub -o clean.jsonl # Exclude test/pollution records ``` bd export [flags] ``` **Flags:** ``` --all Include all records (infra, templates, gates, memories) --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 ``` # bd federation Source: https://beads.gascity.com/cli-reference/federation Federation commands require CGO and the Dolt storage backend. Generated from `bd help --doc federation`. Federation commands require CGO and the Dolt storage backend. This binary was built without CGO support. To use federation features: 1. Use pre-built binaries from GitHub releases, or 2. Build from source with CGO enabled Federation enables synchronized issue tracking across multiple workspaces, each maintaining their own Dolt database while sharing updates via remotes. ``` bd federation [flags] ``` # bd find-duplicates Source: https://beads.gascity.com/cli-reference/find-duplicates Find issues that are semantically similar but not exact duplicates. Generated from `bd help --doc find-duplicates`. Find issues that are semantically similar but not exact duplicates. Unlike 'bd duplicates' which finds exact content matches, find-duplicates uses text similarity or AI to find issues that discuss the same topic with different wording. Approaches: mechanical Token-based text similarity (default, no API key needed) ai LLM-based semantic comparison (requires ANTHROPIC\_API\_KEY or ai.api\_key) The mechanical approach tokenizes titles and descriptions, then computes Jaccard similarity between all issue pairs. It's fast and free but may miss semantically similar issues with very different wording. The AI approach sends candidate pairs to Claude for semantic comparison. It first uses mechanical pre-filtering to reduce the number of API calls, then asks the LLM to judge whether the remaining pairs are true duplicates. Examples: bd find-duplicates # Mechanical similarity (default) bd find-duplicates --threshold 0.4 # Lower threshold = more results bd find-duplicates --method ai # Use AI for semantic comparison bd find-duplicates --status open # Only check open issues bd find-duplicates --limit 20 # Show top 20 pairs bd find-duplicates --json # JSON output ``` bd find-duplicates [flags] ``` **Aliases:** find-dups **Flags:** ``` -n, --limit int Maximum number of pairs to show (default 50) --method string Detection method: mechanical, ai (default "mechanical") --model string AI model to use (only with --method ai; default from config ai.model) -s, --status string Filter by status (default: non-closed) --threshold float Similarity threshold (0.0-1.0, lower = more results) (default 0.5) ``` # bd flatten Source: https://beads.gascity.com/cli-reference/flatten Nuclear option: squash ALL Dolt commit history into a single commit. Generated from `bd help --doc flatten`. Nuclear option: squash ALL Dolt commit history into a single commit. This uses the Tim Sehn recipe: 1. Create a new branch from the current state 2. Soft-reset to the initial commit (preserving all data) 3. Commit everything as a single snapshot 4. Swap main branch to the new flattened branch 5. Run Dolt GC to reclaim space from old history This is irreversible — all commit history is lost. The resulting database has exactly one commit containing all current data. Use this when: * Your .beads/dolt directory has grown very large * You don't need commit-level history (time travel) * You want to start fresh with minimal storage Examples: bd flatten --dry-run # Preview: show commit count and disk usage bd flatten --force # Actually squash all history bd flatten --force --json # JSON output ``` bd flatten [flags] ``` **Flags:** ``` --dry-run Preview without making changes -f, --force Confirm irreversible history squash ``` # bd forget Source: https://beads.gascity.com/cli-reference/forget Remove a memory by its key. Generated from `bd help --doc forget`. Remove a memory by its key. Use 'bd memories' to see available keys. Examples: bd forget dolt-phantoms bd forget auth-jwt ``` bd forget [flags] ``` # bd formula Source: https://beads.gascity.com/cli-reference/formula Manage workflow formulas - the source layer for molecule templates. Generated from `bd help --doc formula`. Manage workflow formulas - the source layer for molecule templates. Formulas are TOML/JSON files that define workflows with composition rules. Define formulas, cook them into protos, then pour or wisp them into work. Search paths (in order): 1. \/formulas/ (active project) 2. \/.beads/formulas/ (repo-local formulas) 3. \~/.beads/formulas/ (user) 4. \$GT\_ROOT/.beads/formulas/ (shared workspace root, if GT\_ROOT set) Commands: list List available formulas from all search paths show Show formula details, steps, and composition rules ``` bd formula [flags] ``` ## bd formula convert Convert formula files from JSON to TOML format. TOML format provides better ergonomics: * Multi-line strings without \n escaping * Human-readable diffs * Comments allowed The convert command reads a .formula.json file and outputs .formula.toml. The original JSON file is preserved (use --delete to remove it). Examples: bd formula convert shiny # Convert shiny.formula.json to .toml bd formula convert ./my.formula.json # Convert specific file bd formula convert --all # Convert all JSON formulas bd formula convert shiny --delete # Convert and remove JSON file bd formula convert shiny --stdout # Print TOML to stdout ``` bd formula convert [--all] [flags] ``` **Flags:** ``` --all Convert all JSON formulas --delete Delete JSON file after conversion --stdout Print TOML to stdout instead of file ``` ## bd formula list List all formulas from search paths. Search paths (in order of priority): 1. \/formulas/ (active project - highest priority) 2. \/.beads/formulas/ (repo-local formulas) 3. \~/.beads/formulas/ (user) 4. \$GT\_ROOT/.beads/formulas/ (shared workspace root, if GT\_ROOT set) Formulas in earlier paths shadow those with the same name in later paths. Examples: bd formula list bd formula list --json bd formula list --type workflow bd formula list --type convoy ``` bd formula list [flags] ``` **Flags:** ``` --type string Filter by type (workflow, expansion, aspect, convoy) ``` ## bd formula show Show detailed information about a formula. Displays: * Formula metadata (name, type, description) * Variables with defaults and constraints * Steps with dependencies * Composition rules (extends, aspects, expansions) * Bond points for external composition Examples: bd formula show shiny bd formula show rule-of-five bd formula show security-audit --json ``` bd formula show [flags] ``` # bd gate Source: https://beads.gascity.com/cli-reference/gate Gates are async wait conditions that block workflow steps. Generated from `bd help --doc gate`. Gates are async wait conditions that block workflow steps. Gates are created automatically when a formula step has a gate field. They must be closed (manually or via watchers) for the blocked step to proceed. Gate types: human - Requires manual bd close (Phase 1) timer - Expires after timeout (Phase 2) gh:run - Waits for GitHub workflow (Phase 3) gh:pr - Waits for PR merge (Phase 3) bead - Waits for cross-rig bead to close (Phase 4) For bead gates, await\_id format is \:\ (e.g., "other-project:op-abc123"). Examples: bd gate list # Show all open gates bd gate list --all # Show all gates including closed bd gate check # Evaluate all open gates bd gate check --type=bead # Evaluate only bead gates bd gate resolve \ # Close a gate manually ``` bd gate [flags] ``` ## bd gate add-waiter Register an agent as a waiter on a gate bead. When the gate closes, the waiter will receive a wake notification via 'bd gate wake'. The waiter is typically the worker's address (e.g., "my-project/workers/agent-1"). This is used by 'bd done --phase-complete' to register for gate wake notifications. ``` bd gate add-waiter [flags] ``` ## bd gate check Evaluate gate conditions and automatically close resolved gates. By default, checks all open gates. Use --type to filter by gate type. Gate types: gh - Check all GitHub gates (gh:run and gh:pr) gh:run - Check GitHub Actions workflow runs gh:pr - Check pull request merge status timer - Check timer gates (auto-expire based on timeout) bead - Check cross-rig bead gates all - Check all gate types GitHub gates use the 'gh' CLI to query status: * gh:run checks 'gh run view \ --json status,conclusion' * gh:pr checks 'gh pr view \ --json state,title' A gate is resolved when: * gh:run: status=completed AND conclusion=success * gh:pr: state=MERGED * timer: current time > created\_at + timeout * bead: target bead status=closed A gate is escalated when: * gh:run: status=completed AND conclusion in (failure, canceled) * gh:pr: state=CLOSED Examples: bd gate check # Check all gates bd gate check --type=gh # Check only GitHub gates bd gate check --type=gh:run # Check only workflow run gates bd gate check --type=timer # Check only timer gates bd gate check --type=bead # Check only cross-rig bead gates bd gate check --dry-run # Show what would happen without changes bd gate check --escalate # Escalate expired/failed gates ``` bd gate check [flags] ``` **Flags:** ``` --dry-run Show what would happen without making changes -e, --escalate Escalate failed/expired gates -l, --limit int Limit results (default 100) (default 100) -t, --type string Gate type to check (gh, gh:run, gh:pr, timer, bead, all) ``` ## bd gate create Create an ad-hoc gate issue that blocks another issue until resolved. The blocked issue will not appear in 'bd ready' until the gate is resolved via 'bd gate resolve'. Gate types: human - Requires manual 'bd gate resolve' (default) timer - Auto-resolves after --timeout duration gh:run - Waits for GitHub Actions workflow gh:pr - Waits for PR merge Examples: bd gate create --blocks bd-abc bd gate create --type=human --blocks bd-abc --reason="Need design review" bd gate create --type=timer --blocks bd-abc --timeout=2h bd gate create --type=gh:pr --blocks bd-abc --await-id=42 ``` bd gate create [flags] ``` **Flags:** ``` --await-id string Condition identifier (run ID, PR number, etc.) --blocks string Issue ID to block (required) -r, --reason string Reason for the gate --timeout string Timeout duration (e.g., 2h, 30m) -t, --type string Gate type (human, timer, gh:run, gh:pr) (default "human") ``` ## bd gate discover Discovers GitHub workflow run IDs for gates awaiting CI/CD completion. This command finds open gates with await\_type="gh:run" that don't have an await\_id, queries recent GitHub workflow runs, and matches them using heuristics: * Branch name matching * Commit SHA matching * Time proximity (runs within 5 minutes of gate creation) Once matched, the gate's await\_id is updated with the GitHub run ID, enabling subsequent polling to check the run's status. Examples: bd gate discover # Auto-discover run IDs for all matching gates bd gate discover --dry-run # Preview what would be matched (no updates) bd gate discover --branch main --limit 10 # Only match runs on 'main' branch ``` bd gate discover [flags] ``` **Flags:** ``` -b, --branch string Filter runs by branch (default: current branch) -n, --dry-run Preview mode: show matches without updating -l, --limit int Max runs to query from GitHub (default 10) -a, --max-age duration Max age for gate/run matching (default 30m0s) ``` ## bd gate list List all gate issues in the current beads database. By default, shows only open gates. Use --all to include closed gates. ``` bd gate list [flags] ``` **Flags:** ``` -a, --all Show all gates including closed -n, --limit int Limit results (default 50) (default 50) ``` ## bd gate resolve Close a gate issue to unblock the step waiting on it. This is equivalent to 'bd close \' but with a more explicit name. Use --reason to provide context for why the gate was resolved. ``` bd gate resolve [flags] ``` **Flags:** ``` -r, --reason string Reason for resolving the gate ``` ## bd gate show Display details of a gate issue including its waiters. This is similar to 'bd show' but validates that the issue is a gate. ``` bd gate show [flags] ``` # bd gc Source: https://beads.gascity.com/cli-reference/gc Full lifecycle garbage collection for standalone Beads databases. Generated from `bd help --doc gc`. Full lifecycle garbage collection for standalone Beads databases. Runs three phases in sequence: 1. DECAY — Delete closed issues older than N days (default 90) 2. COMPACT — Squash old Dolt commits into fewer commits (bd compact) 3. GC — Run Dolt garbage collection to reclaim disk space Each phase can be skipped individually. Use --dry-run to preview all phases without making changes. Examples: bd gc # Full GC with defaults (90 day decay) bd gc --dry-run # Preview what would happen bd gc --older-than 30 # Decay issues closed 30+ days ago bd gc --skip-decay # Skip issue deletion, just compact+GC bd gc --skip-dolt # Skip Dolt GC, just decay+compact bd gc --force # Skip confirmation prompt ``` bd gc [flags] ``` **Flags:** ``` --dry-run Preview without making changes -f, --force Skip confirmation prompts --older-than int Delete closed issues older than N days (default 90) --skip-decay Skip issue deletion phase --skip-dolt Skip Dolt garbage collection phase ``` # bd github Source: https://beads.gascity.com/cli-reference/github Commands for syncing issues between beads and GitHub. Generated from `bd help --doc github`. Commands for syncing issues between beads and GitHub. Configuration can be set via 'bd config' or environment variables: github.token / GITHUB\_TOKEN - Personal access token github.owner / GITHUB\_OWNER - Repository owner github.repo / GITHUB\_REPO - Repository name github.repository / GITHUB\_REPOSITORY - Combined "owner/repo" format github.url / GITHUB\_API\_URL - Custom API URL (GitHub Enterprise) ``` bd github [flags] ``` ## bd github pull Pull one or more items from GitHub. Accepts bead IDs or external references as positional arguments. Equivalent to: bd github sync --pull-only --issues \ ``` bd github pull [refs...] [flags] ``` **Flags:** ``` --dry-run Preview pull without making changes ``` ## bd github push Push one or more beads issues to GitHub. Accepts bead IDs as positional arguments. Equivalent to: bd github sync --push-only --issues \ ``` bd github push [bead-ids...] [flags] ``` **Flags:** ``` --dry-run Preview push without making changes ``` ## bd github repos List GitHub repositories that the configured token has access to. ``` bd github repos [flags] ``` ## bd github status Display current GitHub configuration and sync status. ``` bd github status [flags] ``` ## bd github sync Synchronize issues between beads and GitHub. By default, performs bidirectional sync: * Pulls new/updated issues from GitHub to beads * Pushes local beads issues to GitHub Use --pull-only or --push-only to limit direction. ``` bd github sync [flags] ``` **Flags:** ``` --dry-run Show what would be synced without making changes --issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent. --parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues. --prefer-github On conflict, use GitHub version --prefer-local On conflict, keep local beads version --prefer-newer On conflict, use most recent version (default) --pull-only Only pull issues from GitHub --push-only Only push issues to GitHub ``` # bd gitlab Source: https://beads.gascity.com/cli-reference/gitlab Commands for syncing issues between beads and GitLab. Generated from `bd help --doc gitlab`. Commands for syncing issues between beads and GitLab. Configuration can be set via 'bd config' or environment variables: gitlab.url / GITLAB\_URL - GitLab instance URL gitlab.token / GITLAB\_TOKEN - Personal access token gitlab.project\_id / GITLAB\_PROJECT\_ID - Project ID or path gitlab.group\_id / GITLAB\_GROUP\_ID - Group ID for group-level sync gitlab.default\_project\_id / GITLAB\_DEFAULT\_PROJECT\_ID - Project for creating issues in group mode ``` bd gitlab [flags] ``` ## bd gitlab projects List GitLab projects that the configured token has access to. ``` bd gitlab projects [flags] ``` ## bd gitlab pull Pull one or more items from GitLab. Accepts bead IDs or external references as positional arguments. Equivalent to: bd gitlab sync --pull-only --issues \ ``` bd gitlab pull [refs...] [flags] ``` **Flags:** ``` --dry-run Preview pull without making changes ``` ## bd gitlab push Push one or more beads issues to GitLab. Accepts bead IDs as positional arguments. Equivalent to: bd gitlab sync --push-only --issues \ ``` bd gitlab push [bead-ids...] [flags] ``` **Flags:** ``` --dry-run Preview push without making changes ``` ## bd gitlab status Display current GitLab configuration and sync status. ``` bd gitlab status [flags] ``` ## bd gitlab sync Synchronize issues between beads and GitLab. By default, performs bidirectional sync: * Pulls new/updated issues from GitLab to beads * Pushes local beads issues to GitLab Use --pull-only or --push-only to limit direction. ``` bd gitlab sync [flags] ``` **Flags:** ``` --assignee string Filter by assignee username --dry-run Show what would be synced without making changes --exclude-type string Exclude these issue types from sync (comma-separated) --issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent. --label string Filter by labels (comma-separated, AND logic) --milestone string Filter by milestone title --no-ephemeral Exclude ephemeral/wisp issues from push (default: true) (default true) --parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues. --prefer-gitlab On conflict, use GitLab version --prefer-local On conflict, keep local beads version --prefer-newer On conflict, use most recent version (default) --project string Filter to issues from this project ID (group mode) --pull-only Only pull issues from GitLab --push-only Only push issues to GitLab --type string Only sync these issue types (comma-separated, e.g. 'epic,feature,task') ``` # bd graph Source: https://beads.gascity.com/cli-reference/graph Display a visualization of an issue's dependency graph. Generated from `bd help --doc graph`. Display a visualization of an issue's dependency graph. For epics, shows all children and their dependencies. For regular issues, shows the issue and its direct dependencies. With --all, shows all open issues grouped by connected component. Display formats: (default) DAG with columns and box-drawing edges (terminal-native) \--box ASCII boxes showing layers, more detailed \--compact Tree format, one line per issue, more scannable \--dot Graphviz DOT format (pipe to dot -Tsvg > graph.svg) \--html Self-contained interactive HTML with D3.js visualization The graph shows execution order: * Layer 0 / leftmost = no dependencies (can start immediately) * Higher layers depend on lower layers * Nodes in the same layer can run in parallel Status icons: ○ open ◐ in\_progress ● blocked ✓ closed ❄ deferred Examples: bd graph issue-id # Terminal DAG visualization (default) bd graph --box issue-id # ASCII boxes with layer grouping bd graph --dot issue-id | dot -Tsvg > graph.svg # SVG via Graphviz bd graph --dot issue-id | dot -Tpng > graph.png # PNG via Graphviz bd graph --html issue-id > graph.html # Interactive browser view bd graph --all --html > all.html # All issues, interactive ``` bd graph [issue-id] [flags] ``` **Flags:** ``` --all Show graph for all open issues --box ASCII boxes showing layers --compact Tree format, one line per issue, more scannable --dot Output Graphviz DOT format (pipe to: dot -Tsvg > graph.svg) --html Output self-contained interactive HTML (redirect to file) ``` ## bd graph check Check the dependency graph for cycles, orphans, and other integrity issues. Returns exit code 0 if the graph is clean, 1 if issues are found. ``` bd graph check [flags] ``` # bd history Source: https://beads.gascity.com/cli-reference/history Show the complete version history of an issue, including all commits Generated from `bd help --doc history`. Show the complete version history of an issue, including all commits where the issue was modified. Examples: bd history bd-123 # Show all history for issue bd-123 bd history bd-123 --limit 5 # Show last 5 changes ``` bd history [flags] ``` **Flags:** ``` --limit int Limit number of history entries (0 = all) ``` # bd hooks Source: https://beads.gascity.com/cli-reference/hooks Install, uninstall, or list git hooks for beads integration. Generated from `bd help --doc hooks`. Install, uninstall, or list git hooks for beads integration. The hooks provide: * pre-commit: Run chained hooks before commit * post-merge: Run chained hooks after pull/merge * pre-push: Run chained hooks before push * post-checkout: Run chained hooks after branch checkout * prepare-commit-msg: Add agent identity trailers for forensics ``` bd hooks [flags] ``` ## bd hooks install Install git hooks for beads integration. By default, hooks are installed to .git/hooks/ in the current repository. Use --beads to install to .beads/hooks/ (recommended for Dolt backend). Use --shared to install to a versioned directory (.beads-hooks/) that can be committed to git and shared with team members. Hooks use section markers to coexist with existing hooks — any user content outside the markers is preserved across installs and upgrades. Installed hooks: * pre-commit: Run chained hooks before commit * post-merge: Run chained hooks after pull/merge * pre-push: Run chained hooks before push * post-checkout: Run chained hooks after branch checkout * prepare-commit-msg: Add agent identity trailers (for orchestrator agents) ``` bd hooks install [flags] ``` **Flags:** ``` --beads Install hooks to .beads/hooks/ (recommended for Dolt backend) --chain Chain with existing hooks (run them before bd hooks) --force Overwrite existing hooks without backup --shared Install hooks to .beads-hooks/ (versioned) instead of .git/hooks/ ``` ## bd hooks list Show the status of bd git hooks (installed, outdated, missing). ``` bd hooks list [flags] ``` ## bd hooks run Execute the logic for a git hook. This command is typically called by thin shim scripts installed in .git/hooks/. Supported hooks: * pre-commit: Run chained hooks before commit * post-merge: Run chained hooks after pull/merge * pre-push: Run chained hooks before push * post-checkout: Run chained hooks after branch checkout * prepare-commit-msg: Add agent identity trailers for forensics The thin shim pattern ensures hook logic is always in sync with the installed bd version - upgrading bd automatically updates hook behavior. ``` bd hooks run [args...] [flags] ``` ## bd hooks uninstall Remove bd git hooks from .git/hooks/ directory. ``` bd hooks uninstall [flags] ``` # bd human Source: https://beads.gascity.com/cli-reference/human Display a focused help menu showing only the most common commands. Generated from `bd help --doc human`. Display a focused help menu showing only the most common commands. bd has 70+ commands - many for AI agents, integrations, and advanced workflows. This command shows the \~15 essential commands that human users need most often. For the full command list, run: bd --help SUBCOMMANDS: human list List all human-needed beads (issues with 'human' label) human respond \ Respond to a human-needed bead (adds comment and closes) human dismiss \ Dismiss a human-needed bead permanently human stats Show summary statistics for human-needed beads ``` bd human [flags] ``` ## bd human dismiss Dismiss a human-needed bead permanently without responding. The issue is closed with a "Dismissed" reason and optional note. Examples: bd human dismiss bd-123 bd human dismiss bd-123 --reason "No longer applicable" ``` bd human dismiss [flags] ``` **Flags:** ``` --reason string Reason for dismissal (optional) ``` ## bd human list List all issues labeled with 'human' tag. These are issues that require human intervention or input. Examples: bd human list bd human list --status=open bd human list --json ``` bd human list [flags] ``` **Flags:** ``` -s, --status string Filter by status (open, closed, etc.) ``` ## bd human respond Respond to a human-needed bead by adding a comment and closing it. The response is added as a comment and the issue is closed with reason "Responded". Examples: bd human respond bd-123 --response "Use OAuth2 for authentication" bd human respond bd-123 -r "Approved, proceed with implementation" ``` bd human respond [flags] ``` **Flags:** ``` -r, --response string Response text (required) ``` ## bd human stats Display summary statistics for human-needed beads. Shows counts for total, pending (open), responded (closed without dismiss), and dismissed beads. Example: bd human stats ``` bd human stats [flags] ``` # bd import Source: https://beads.gascity.com/cli-reference/import Import issues from a JSONL file (newline-delimited JSON) into the database. Generated from `bd help --doc import`. Import issues from a JSONL file (newline-delimited JSON) into the database. If no file is specified, imports from the configured import.path under .beads/ (default: issues.jsonl). Use "-" to read from stdin. This is the incremental counterpart to 'bd export': new issues are created and existing issues are updated (upsert semantics). Memory records (lines with "\_type":"memory") are automatically detected and imported as persistent memories (equivalent to 'bd remember'). This makes 'bd export | bd import' a full round-trip for both issues and memories. Each JSONL line should map to an issue. The importer accepts every field 'bd export' emits — see 'bd export' output for the canonical schema. Only "title" is required; everything else is optional. Common fields: title Required. Short summary. description Long-form body. design, notes, Additional content sections. acceptance\_criteria issue\_type bug | feature | task | epic | chore | ... priority 0-4 (0 = critical). 0 is preserved (no omitempty). status open | in\_progress | blocked | closed | ... (rows with status "tombstone" are skipped) assignee, owner, Ownership metadata. created\_by labels Array of strings. dependencies Array of \{issue\_id, depends\_on\_id, type, ...}. comments Array of comment objects. external\_ref, Cross-system identifiers (e.g. "gh-9"). source\_system due\_at, defer\_until RFC3339 timestamps for scheduling. metadata Arbitrary JSON object preserved verbatim. Timestamps (created\_at, updated\_at, started\_at, closed\_at) are preserved when present in the JSONL and otherwise filled in by the importer. The legacy "wisp" boolean is accepted as an alias for "ephemeral". By default a row only rewrites an existing local issue when its updated\_at is strictly newer. Older rows are skipped (reported as stale\_skipped\_ids) and rows with the same updated\_at keep every local column — updated\_at has second granularity, so a timestamp tie can be two distinct same-second updates, and the local row wins the tie (reported as tie\_kept\_local\_ids; the row's labels/comments/dependencies still merge). The guard is also enforced inside the upsert itself, so a local update that lands while the import is running is preserved rather than overwritten. Existing issues that the import did rewrite are listed with a field-level summary (updated\_issues), so local state changed by an import is visible. To deliberately restore an older snapshot, pass \--allow-stale, which imports every row even when it overwrites newer local state. EXAMPLES: bd import # Import from configured import.path bd import backup.jsonl # Import from a specific file bd import -i backup.jsonl # Legacy alias for a specific file bd import - # Read JSONL from stdin cat issues.jsonl | bd import - # Pipe JSONL from another tool bd import --dry-run # Show what would be imported bd import --dedup # Skip issues with duplicate titles bd import --allow-stale old.jsonl # Restore an older snapshot (overwrites newer local rows) bd import --json # Structured output with created and skipped IDs ``` bd import [file|-] [flags] ``` **Flags:** ``` --allow-stale Import rows even when older than the local issue (required to restore an older snapshot) --dedup Skip lines whose title matches an existing open issue --dry-run Show what would be imported without importing -i, --input string Read JSONL from a specific file ``` # CLI Reference Source: https://beads.gascity.com/cli-reference/index Generated reference for every bd command Generated from `bd help --docs-root`. This reference covers all 108 live top-level `bd` commands. Regenerate it with: ```bash theme={null} ./scripts/generate-cli-docs.sh ``` ## Commands * [`bd admin`](/cli-reference/admin) * [`bd ado`](/cli-reference/ado) * [`bd assign`](/cli-reference/assign) * [`bd audit`](/cli-reference/audit) * [`bd backup`](/cli-reference/backup) * [`bd batch`](/cli-reference/batch) * [`bd blocked`](/cli-reference/blocked) * [`bd bootstrap`](/cli-reference/bootstrap) * [`bd branch`](/cli-reference/branch) * [`bd children`](/cli-reference/children) * [`bd close`](/cli-reference/close) * [`bd comment`](/cli-reference/comment) * [`bd comments`](/cli-reference/comments) * [`bd compact`](/cli-reference/compact) * [`bd completion`](/cli-reference/completion) * [`bd config`](/cli-reference/config) * [`bd context`](/cli-reference/context) * [`bd cook`](/cli-reference/cook) * [`bd count`](/cli-reference/count) * [`bd create`](/cli-reference/create) * [`bd create-form`](/cli-reference/create-form) * [`bd defer`](/cli-reference/defer) * [`bd delete`](/cli-reference/delete) * [`bd dep`](/cli-reference/dep) * [`bd diff`](/cli-reference/diff) * [`bd doctor`](/cli-reference/doctor) * [`bd dolt`](/cli-reference/dolt) * [`bd duplicate`](/cli-reference/duplicate) * [`bd duplicates`](/cli-reference/duplicates) * [`bd edit`](/cli-reference/edit) * [`bd epic`](/cli-reference/epic) * [`bd export`](/cli-reference/export) * [`bd federation`](/cli-reference/federation) * [`bd find-duplicates`](/cli-reference/find-duplicates) * [`bd flatten`](/cli-reference/flatten) * [`bd forget`](/cli-reference/forget) * [`bd formula`](/cli-reference/formula) * [`bd gate`](/cli-reference/gate) * [`bd gc`](/cli-reference/gc) * [`bd github`](/cli-reference/github) * [`bd gitlab`](/cli-reference/gitlab) * [`bd graph`](/cli-reference/graph) * [`bd history`](/cli-reference/history) * [`bd hooks`](/cli-reference/hooks) * [`bd human`](/cli-reference/human) * [`bd import`](/cli-reference/import) * [`bd info`](/cli-reference/info) * [`bd init`](/cli-reference/init) * [`bd init-safety`](/cli-reference/init-safety) * [`bd jira`](/cli-reference/jira) * [`bd kv`](/cli-reference/kv) * [`bd label`](/cli-reference/label) * [`bd linear`](/cli-reference/linear) * [`bd link`](/cli-reference/link) * [`bd lint`](/cli-reference/lint) * [`bd list`](/cli-reference/list) * [`bd mail`](/cli-reference/mail) * [`bd memories`](/cli-reference/memories) * [`bd merge-slot`](/cli-reference/merge-slot) * [`bd metrics`](/cli-reference/metrics) * [`bd migrate`](/cli-reference/migrate) * [`bd mol`](/cli-reference/mol) * [`bd note`](/cli-reference/note) * [`bd notion`](/cli-reference/notion) * [`bd onboard`](/cli-reference/onboard) * [`bd orphans`](/cli-reference/orphans) * [`bd ping`](/cli-reference/ping) * [`bd preflight`](/cli-reference/preflight) * [`bd prime`](/cli-reference/prime) * [`bd priority`](/cli-reference/priority) * [`bd promote`](/cli-reference/promote) * [`bd prune`](/cli-reference/prune) * [`bd purge`](/cli-reference/purge) * [`bd q`](/cli-reference/q) * [`bd query`](/cli-reference/query) * [`bd quickstart`](/cli-reference/quickstart) * [`bd ready`](/cli-reference/ready) * [`bd recall`](/cli-reference/recall) * [`bd recompute-blocked`](/cli-reference/recompute-blocked) * [`bd remember`](/cli-reference/remember) * [`bd rename`](/cli-reference/rename) * [`bd rename-prefix`](/cli-reference/rename-prefix) * [`bd reopen`](/cli-reference/reopen) * [`bd repo`](/cli-reference/repo) * [`bd restore`](/cli-reference/restore) * [`bd rules`](/cli-reference/rules) * [`bd search`](/cli-reference/search) * [`bd set-state`](/cli-reference/set-state) * [`bd setup`](/cli-reference/setup) * [`bd ship`](/cli-reference/ship) * [`bd show`](/cli-reference/show) * [`bd sql`](/cli-reference/sql) * [`bd stale`](/cli-reference/stale) * [`bd state`](/cli-reference/state) * [`bd status`](/cli-reference/status) * [`bd statuses`](/cli-reference/statuses) * [`bd supersede`](/cli-reference/supersede) * [`bd swarm`](/cli-reference/swarm) * [`bd tag`](/cli-reference/tag) * [`bd todo`](/cli-reference/todo) * [`bd types`](/cli-reference/types) * [`bd undefer`](/cli-reference/undefer) * [`bd update`](/cli-reference/update) * [`bd upgrade`](/cli-reference/upgrade) * [`bd vc`](/cli-reference/vc) * [`bd version`](/cli-reference/version) * [`bd where`](/cli-reference/where) * [`bd worktree`](/cli-reference/worktree) # bd info Source: https://beads.gascity.com/cli-reference/info Display information about the current database. Generated from `bd help --doc info`. Display information about the current database. This command helps debug issues where bd is using an unexpected database. It shows: * The absolute path to the database file * Database statistics (issue count) * Schema information (with --schema flag) * What's new in recent versions (with --whats-new flag) Examples: bd info bd info --json bd info --schema --json bd info --whats-new bd info --whats-new --json bd info --thanks ``` bd info [flags] ``` **Flags:** ``` --json Output in JSON format --schema Include schema information in output --thanks Show thank you page for contributors --whats-new Show agent-relevant changes from recent versions ``` # bd init Source: https://beads.gascity.com/cli-reference/init Initialize bd in the current directory by creating a .beads/ directory Generated from `bd help --doc init`. Initialize bd in the current directory by creating a .beads/ directory and Dolt database. Optionally specify a custom issue prefix. 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) has already created the database. With --stealth: configures per-repository git settings for invisible beads usage: • .git/info/exclude to prevent beads files from being committed Perfect for personal use without affecting repo collaborators. To set up a specific AI tool, run: bd setup \ --stealth By default, beads uses an embedded Dolt engine (no external server needed). Pass --server to use an external dolt sql-server instead. In server mode, set connection details with --server-host, --server-port, and --server-user. Password should be set via BEADS\_DOLT\_PASSWORD environment variable. Auto-export is optional. When enabled, bd exports issues to .beads/issues.jsonl after write commands (throttled to once per 60s). This is for viewers (bv), interchange, and issue-level migration; not backup. Cross-machine sync and backups use Dolt remotes/backups, not JSONL import/export. To enable: bd config set export.auto true Non-interactive mode (--non-interactive or BD\_NON\_INTERACTIVE=1): Skips all interactive prompts, using sensible defaults: • Role defaults to "maintainer" (override with --role) • Fork exclude auto-configured when fork detected • Auto-export left at default (disabled) • --contributor and --team flags are rejected (wizards require interaction) Also auto-detected when stdin is not a terminal or CI=true is set. ``` bd init [flags] ``` **Flags:** ``` --agents-file string Custom filename for agent instructions (default: AGENTS.md) --agents-profile string AGENTS.md profile: 'minimal' (default, pointer to bd prime) or 'full' (complete command reference) --agents-template string Path to custom AGENTS.md template (overrides embedded default) --backend string Storage backend (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-') --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: /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: /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 ``` # bd init-safety Source: https://beads.gascity.com/cli-reference/init-safety bd init flag safety contract. Generated from `bd help --doc init-safety`. bd init flag safety contract. Every bd init invocation resolves project\_id from exactly one explicitly named source (local reinit, remote adoption, or a fresh mint). When the source is ambiguous, bd init refuses. FLAG SURFACE bd init Mint a new identity. Bootstraps from origin if it has refs/dolt/data. bd init --reinit-local Re-initialize local .beads/ over existing local data. Does NOT authorize discarding remote history. If origin has Dolt data this will refuse — pair with \--discard-remote to override. bd init --reinit-local \ Discard the remote's Dolt history and \--discard-remote replace it with the local reinit. First bd dolt push after this will be a history-replacing force-push. bd init --force Deprecated alias for --reinit-local. Kept working for ≥2 releases. bd init --from-jsonl Import from configured import.path. If origin has Dolt data, this refuses unless \--discard-remote authorizes replacing that remote history. ADOPTING A REMOTE If you want to use the remote's existing history, use: bd bootstrap bd init will automatically suggest this when a remote is detected. DESTROY-TOKEN (non-interactive only) When running with no TTY (CI, agents, piped input), --discard-remote requires an explicit --destroy-token value. The token format is: DESTROY-\ For example, if your issue prefix is "bd", the token is "DESTROY-bd": bd init --reinit-local --discard-remote --destroy-token=DESTROY-bd In interactive (TTY) mode you confirm via a typed prompt instead. The token is not echoed by bd's runtime error messages — this is a deliberate guard against pattern-matched one-liners (see docs/adr/0002-init-safety-invariants.md). EXIT CODES 10 refused: remote has Dolt history and you selected local history without --discard-remote 11 refused: existing local data and you declined the destroy confirm 12 refused: --discard-remote passed without a valid --destroy-token (non-interactive mode) RECOVERY If you hit a refusal, see docs/RECOVERY.md for step-by-step recovery playbooks for each exit code. ``` bd init-safety [flags] ``` # bd jira Source: https://beads.gascity.com/cli-reference/jira Synchronize issues between beads and Jira. Generated from `bd help --doc jira`. Synchronize issues between beads and Jira. Configuration: bd config set jira.url "[https://company.atlassian.net](https://company.atlassian.net)" bd config set jira.project "PROJ" bd config set jira.projects "PROJ1,PROJ2" # Multiple projects bd config set jira.api\_token "YOUR\_TOKEN" bd config set jira.username "[your\_email@company.com](mailto:your_email@company.com)" # For Jira Cloud bd config set jira.push\_prefix "hippo" # Only push hippo-\* issues to Jira bd config set jira.push\_prefix "proj1,proj2" # Multiple prefixes (comma-separated) Environment variables (alternative to config): JIRA\_API\_TOKEN - Jira API token JIRA\_USERNAME - Jira username/email JIRA\_PROJECTS - Comma-separated project keys Examples: bd jira sync --pull # Import issues from Jira bd jira sync --push # Export issues to Jira bd jira sync # Bidirectional sync (pull then push) bd jira sync --dry-run # Preview sync without changes bd jira status # Show sync status ``` bd jira [flags] ``` ## bd jira pull Pull one or more items from Jira. Accepts bead IDs or external references as positional arguments. Equivalent to: bd jira sync --pull --issues \ ``` bd jira pull [refs...] [flags] ``` **Flags:** ``` --dry-run Preview pull without making changes ``` ## bd jira push Push one or more beads issues to Jira. Accepts bead IDs as positional arguments. Equivalent to: bd jira sync --push --issues \ ``` bd jira push [bead-ids...] [flags] ``` **Flags:** ``` --dry-run Preview push without making changes ``` ## bd jira status Show the current Jira sync status, including: * Last sync timestamp * Configuration status * Number of issues with Jira links * Issues pending push (no external\_ref) ``` bd jira status [flags] ``` ## bd jira sync Synchronize issues between beads and Jira. Modes: \--pull Import issues from Jira into beads \--push Export issues from beads to Jira (no flags) Bidirectional sync: pull then push, with conflict resolution Conflict Resolution: By default, newer timestamp wins. Override with: \--prefer-local Always prefer local beads version \--prefer-jira Always prefer Jira version Examples: bd jira sync --pull # Import from Jira bd jira sync --push --create-only # Push new issues only bd jira sync --dry-run # Preview without changes bd jira sync --prefer-local # Bidirectional, local wins ``` bd jira sync [flags] ``` **Flags:** ``` --create-only Only create new issues, don't update existing --dry-run Preview sync without making changes --issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent. --parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues. --prefer-jira Prefer Jira version on conflicts --prefer-local Prefer local version on conflicts --project strings Project key(s) to sync (overrides configured project/projects) --pull Pull issues from Jira --push Push issues to Jira --state string Issue state to sync: open, closed, all (default "all") ``` # bd kv Source: https://beads.gascity.com/cli-reference/kv Commands for working with the beads key-value store. Generated from `bd help --doc kv`. Commands for working with the beads key-value store. The key-value store is useful for storing flags, environment variables, or other user-defined data that persists across sessions. Examples: bd kv set mykey myvalue # Set a value bd kv get mykey # Get a value bd kv clear mykey # Delete a key bd kv list # List all key-value pairs ``` bd kv [flags] ``` ## bd kv clear Delete a key from the beads key-value store. Examples: bd kv clear feature\_flag bd kv clear api\_endpoint ``` bd kv clear [flags] ``` ## bd kv get Get a value from the beads key-value store. Examples: bd kv get feature\_flag bd kv get api\_endpoint ``` bd kv get [flags] ``` ## bd kv list List all key-value pairs in the beads key-value store. Examples: bd kv list bd kv list --json ``` bd kv list [flags] ``` ## bd kv set Set a key-value pair in the beads key-value store. This is useful for storing flags, environment variables, or other user-defined data that persists across sessions. Examples: bd kv set feature\_flag true bd kv set api\_endpoint [https://api.example.com](https://api.example.com) bd kv set max\_retries 3 ``` bd kv set [flags] ``` # bd label Source: https://beads.gascity.com/cli-reference/label Manage issue labels Generated from `bd help --doc label`. Manage issue labels ``` bd label [flags] ``` ## bd label add Add a label to one or more issues ``` bd label add [issue-id...] [label] [flags] ``` ## bd label list List labels for an issue ``` bd label list [issue-id] [flags] ``` ## bd label list-all List all unique labels in the database ``` bd label list-all [flags] ``` ## bd label propagate Push a label from a parent down to all direct children that don't already have it. Useful for applying branch: labels across an epic's subtasks. ``` bd label propagate [parent-id] [label] [flags] ``` ## bd label remove Remove a label from one or more issues ``` bd label remove [issue-id...] [label] [flags] ``` # bd linear Source: https://beads.gascity.com/cli-reference/linear Synchronize issues between beads and Linear. Generated from `bd help --doc linear`. Synchronize issues between beads and Linear. Configuration: bd config set linear.api\_key "YOUR\_API\_KEY" bd config set linear.team\_id "TEAM\_ID" bd config set linear.team\_ids "TEAM\_ID1,TEAM\_ID2" # Multiple teams (comma-separated) bd config set linear.project\_id "PROJECT\_ID" # Optional: sync only this project Environment variables (alternative to config): LINEAR\_API\_KEY - Linear API key (for individual developers) LINEAR\_TEAM\_ID - Linear team ID (UUID, singular) LINEAR\_TEAM\_IDS - Linear team IDs (comma-separated UUIDs) OAuth (for CI workers / automated sync): LINEAR\_OAUTH\_CLIENT\_ID - OAuth app client ID LINEAR\_OAUTH\_CLIENT\_SECRET - OAuth app client secret When both OAuth env vars are set, OAuth client\_credentials flow is used instead of the API key. This allows CI workers to authenticate as an application (actor=application) rather than impersonating a user. Precedence: OAuth > LINEAR\_API\_KEY > config file. Data Mapping (optional, sensible defaults provided): Priority mapping (Linear 0-4 to Beads 0-4): bd config set linear.priority\_map.0 4 # No priority -> Backlog bd config set linear.priority\_map.1 0 # Urgent -> Critical bd config set linear.priority\_map.2 1 # High -> High bd config set linear.priority\_map.3 2 # Medium -> Medium bd config set linear.priority\_map.4 3 # Low -> Low State mapping (Linear state type to Beads status): bd config set linear.state\_map.backlog open bd config set linear.state\_map.unstarted open bd config set linear.state\_map.started in\_progress bd config set linear.state\_map.completed closed bd config set linear.state\_map.canceled closed bd config set linear.state\_map.my\_custom\_state in\_progress # Custom state names Label to issue type mapping: bd config set linear.label\_type\_map.bug bug bd config set linear.label\_type\_map.feature feature bd config set linear.label\_type\_map.epic epic Relation type mapping (Linear relations to Beads dependencies): bd config set linear.relation\_map.blocks blocks bd config set linear.relation\_map.blockedBy blocks bd config set linear.relation\_map.duplicate duplicates bd config set linear.relation\_map.related related ID generation (optional, hash IDs to match bd/Jira hash mode): bd config set linear.id\_mode "hash" # hash (default) bd config set linear.hash\_length "6" # hash length 3-8 (default: 6) Examples: bd linear sync --pull # Import issues from Linear bd linear sync --push # Export issues to Linear bd linear sync # Bidirectional sync (pull then push) bd linear sync --dry-run # Preview sync without changes bd create "Fix login" --external-ref [https://linear.app/team/issue/TEAM-123](https://linear.app/team/issue/TEAM-123) # Link a local issue to an existing Linear issue bd linear status # Show sync status ``` bd linear [flags] ``` ## bd linear pull Pull one or more items from Linear. Accepts bead IDs or external references as positional arguments. Equivalent to: bd linear sync --pull --issues \ ``` bd linear pull [refs...] [flags] ``` **Flags:** ``` --dry-run Preview pull without making changes --relations Import Linear relations as bd dependencies when pulling ``` ## bd linear push Push one or more beads issues to Linear. Accepts bead IDs as positional arguments. Equivalent to: bd linear sync --push --issues \ ``` bd linear push [bead-ids...] [flags] ``` **Flags:** ``` --dry-run Preview push without making changes ``` ## bd linear status Show the current Linear sync status, including: * Last sync timestamp * Configuration status * Number of issues with Linear links * Issues pending push (no external\_ref) ``` bd linear status [flags] ``` ## bd linear sync Synchronize issues between beads and Linear. Modes: \--pull Import issues from Linear into beads \--push Export issues from beads to Linear \--pull-if-stale Pull only if data is stale (skip if fresh) (no flags) Bidirectional sync: pull then push, with conflict resolution Staleness (--pull-if-stale): \--threshold 20m How old data must be before pulling (default 20m) A 5-minute debounce prevents agent loops: if a pull completed within 5 minutes, data is always treated as fresh regardless of the threshold. Team Selection: \--team ID1,ID2 Override configured team IDs for this sync Multiple teams can be configured via linear.team\_ids (comma-separated). Falls back to linear.team\_id for backward compatibility. Push requires explicit --team when multiple teams are configured. Pull Options: \--milestones Reconstruct Linear project milestones as local epic parents Type Filtering (--push only): \--type task,feature Only sync issues of these types \--exclude-type wisp Exclude issues of these types \--include-ephemeral Include ephemeral issues (wisps, etc.); default is to exclude \--parent TICKET Only push this ticket and its descendants \--relations Import Linear relations as bd dependencies on pull Conflict Resolution: By default, newer timestamp wins. Override with: \--prefer-local Always prefer local beads version \--prefer-linear Always prefer Linear version Examples: bd linear sync --pull # Import from Linear bd linear sync --pull-if-stale # Pull only if data is stale bd linear sync --pull-if-stale --threshold 5m # Pull if older than 5 minutes bd linear sync --pull --relations # Import Linear blocking relations as bd deps bd linear sync --push --create-only # Push new issues only bd linear sync --push --type=task,feature # Push only tasks and features bd linear sync --push --exclude-type=wisp # Push all except wisps bd linear sync --push --parent=bd-abc123 # Push one ticket tree bd linear sync --dry-run # Preview without changes bd linear sync --prefer-local # Bidirectional, local wins ``` bd linear sync [flags] ``` **Flags:** ``` --create-only Only create new issues, don't update existing --dry-run Preview sync without making changes --exclude-type strings Exclude issues of these types (can be repeated) --include-ephemeral Include ephemeral issues (wisps, etc.) when pushing to Linear --issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent. --milestones Reconstruct Linear project milestones as local epic parents when pulling --no-wait Fail immediately if another sync is running instead of waiting --parent string Limit push to this beads ticket and its descendants --prefer-linear Prefer Linear version on conflicts --prefer-local Prefer local version on conflicts --pull Pull issues from Linear --pull-if-stale Pull only if Linear data is stale (skip if fresh) --push Push issues to Linear --relations Import Linear relations as bd dependencies when pulling --state string Issue state to sync: open, closed, all (default "all") --team strings Team ID(s) to sync (overrides configured team_id/team_ids) --threshold duration Staleness threshold for --pull-if-stale (default 20m) (default 20m0s) --type strings Only sync issues of these types (can be repeated) --update-refs Update external_ref after creating Linear issues (default true) ``` ## bd linear teams List all teams accessible with your Linear API key. Use this to find the team ID (UUID) needed for configuration. Example: bd linear teams bd config set linear.team\_id "12345678-1234-1234-1234-123456789abc" ``` bd linear teams [flags] ``` # bd link Source: https://beads.gascity.com/cli-reference/link Link two issues with a dependency. Generated from `bd help --doc link`. Link two issues with a dependency. Shorthand for 'bd dep add \ \'. By default creates a "blocks" dependency (id2 blocks id1). Use --type to specify a different relationship. Examples: bd link bd-123 bd-456 # bd-456 blocks bd-123 bd link bd-123 bd-456 --type related # bd-123 related to bd-456 bd link bd-123 bd-456 --type parent-child ``` bd link [flags] ``` **Flags:** ``` -t, --type string Dependency type (blocks|tracks|related|parent-child|discovered-from) (default "blocks") ``` # bd lint Source: https://beads.gascity.com/cli-reference/lint Check issues for missing recommended sections based on issue type. Generated from `bd help --doc lint`. Check issues for missing recommended sections based on issue type. By default, lints all open issues. Specify issue IDs to lint specific issues. Section requirements by type: bug: Steps to Reproduce, Acceptance Criteria task: Acceptance Criteria feature: Acceptance Criteria epic: Success Criteria chore: (none) Examples: bd lint # Lint all open issues bd lint bd-abc # Lint specific issue bd lint bd-abc bd-def # Lint multiple issues bd lint --type bug # Lint only bugs bd lint --status all # Lint all issues (including closed) ``` bd lint [issue-id...] [flags] ``` **Flags:** ``` -s, --status string Filter by status (default: open, use 'all' for all) -t, --type string Filter by issue type (bug, task, feature, epic) ``` # bd list Source: https://beads.gascity.com/cli-reference/list List issues Generated from `bd help --doc list`. List issues ``` bd list [flags] ``` **Flags:** ``` --all Show all issues including closed (overrides default filter) -a, --assignee string Filter by assignee --closed-after string Filter issues closed after date (YYYY-MM-DD or RFC3339) --closed-before string Filter issues closed before date (YYYY-MM-DD or RFC3339) --created-after string Filter issues created after date (YYYY-MM-DD or RFC3339) --created-before string Filter issues created before date (YYYY-MM-DD or RFC3339) --defer-after string Filter issues deferred after date (supports relative: +6h, tomorrow) --defer-before string Filter issues deferred before date (supports relative: +6h, tomorrow) --deferred Show only issues with defer_until set --desc-contains string Filter by description substring (case-insensitive) --due-after string Filter issues due after date (supports relative: +6h, tomorrow) --due-before string Filter issues due before date (supports relative: +6h, tomorrow) --empty-description Filter issues with empty or missing description --exclude-label strings Exclude issues that have ANY of these labels --exclude-type strings Exclude issue types from results (comma-separated or repeatable, e.g., --exclude-type=convoy,epic) --flat Disable tree format and use legacy flat list output --format string Output format: 'digraph' (for golang.org/x/tools/cmd/digraph), 'dot' (Graphviz), or Go template --has-metadata-key string Filter issues that have this metadata key set --id string Filter by specific issue IDs (comma-separated, e.g., bd-1,bd-5,bd-10) --include-gates Include gate issues in output (normally hidden) --include-infra Include infrastructure beads (agent/role/message) in output --include-templates Include template molecules in output -l, --label strings Filter by labels (AND: must have ALL). Can combine with --label-any --label-any strings Filter by labels (OR: must have AT LEAST ONE). Can combine with --label --label-pattern string Filter by label glob pattern (e.g., 'tech-*' matches tech-debt, tech-legacy) --label-regex string Filter by label regex pattern (e.g., 'tech-(debt|legacy)') -n, --limit int Limit results (default 50, use 0 for unlimited) (default 50) --long Show detailed multi-line output for each issue --metadata-field stringArray Filter by metadata field (key=value, repeatable) --mol-type string Filter by molecule type: swarm, patrol, or work --no-assignee Filter issues with no assignee --no-labels Filter issues with no labels --no-pager Disable pager output --no-parent Exclude child issues (show only top-level issues) --no-pinned Exclude pinned issues --notes-contains string Filter by notes substring (case-insensitive) --offset int Skip the first N matching results (0-based). Only supported under --proxied-server. --overdue Show only issues with due_at in the past (not closed) --parent string Filter by parent issue ID (shows children of specified issue) --pinned Show only pinned issues --pretty Display issues in a tree format with status/priority symbols -p, --priority string Priority (0-4 or P0-P4, 0=highest) --priority-max string Filter by maximum priority (inclusive, 0-4 or P0-P4) --priority-min string Filter by minimum priority (inclusive, 0-4 or P0-P4) --ready Show only ready issues (no active blockers, same semantics as bd ready) -r, --reverse Reverse sort order --skip-labels Skip label hydration. The labels field in output will be empty regardless of actual labels. Use only when the caller does not depend on label data. Cannot combine with --label, --label-any, --label-pattern, --label-regex, --exclude-label, or --no-labels. --sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee --spec string Filter by spec_id prefix -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress. Note: repeating -s/--status silently overwrites the previous value — always use the comma-separated form for multi-status filters. --title string Filter by title text (case-insensitive substring match) --title-contains string Filter by title substring (case-insensitive) --tree Hierarchical tree format (default: true; use --flat to disable) (default true) -t, --type string Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate, convoy). Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision --updated-after string Filter issues updated after date (YYYY-MM-DD or RFC3339) --updated-before string Filter issues updated before date (YYYY-MM-DD or RFC3339) -w, --watch Watch for changes and auto-update display (implies --pretty) --wisp-type string Filter by wisp type: heartbeat, ping, patrol, gc_report, recovery, error, escalation ``` # bd mail Source: https://beads.gascity.com/cli-reference/mail Delegates mail operations to an external mail provider. Generated from `bd help --doc mail`. Delegates mail operations to an external mail provider. Agents often type 'bd mail' when working with beads, but mail functionality is typically provided by the orchestrator. This command bridges that gap by delegating to the configured mail provider. Configuration (checked in order): 1. BEADS\_MAIL\_DELEGATE or BD\_MAIL\_DELEGATE environment variable 2. 'mail.delegate' config setting (bd config set mail.delegate "gt mail") Examples: # Configure delegation (one-time setup) `export BEADS_MAIL_DELEGATE="gt mail"` # or bd config set mail.delegate "gt mail" # Then use bd mail as if it were gt mail bd mail inbox # Lists inbox bd mail send mayor/ -s "Hi" # Sends mail bd mail read msg-123 # Reads a message ``` bd mail [subcommand] [args...] [flags] ``` # bd memories Source: https://beads.gascity.com/cli-reference/memories List all memories, or search by keyword. Generated from `bd help --doc memories`. List all memories, or search by keyword. Examples: bd memories # list all memories bd memories dolt # search for memories about dolt bd memories "race flag" # search for a phrase ``` bd memories [search] [flags] ``` # bd merge-slot Source: https://beads.gascity.com/cli-reference/merge-slot Merge-slot gates serialize conflict resolution in the merge queue. Generated from `bd help --doc merge-slot`. Merge-slot gates serialize conflict resolution in the merge queue. A merge slot is an exclusive access primitive: only one agent can hold it at a time. This prevents "monkey knife fights" where multiple polecats race to resolve conflicts and create cascading conflicts. Each rig has one merge slot bead: \-merge-slot (labeled gt:slot). The slot uses: * status=open: slot is available * status=in\_progress: slot is held * metadata.holder: who currently holds the slot * metadata.waiters: priority-ordered queue of waiters Examples: bd merge-slot create # Create merge slot for current rig bd merge-slot check # Check if slot is available bd merge-slot acquire # Try to acquire the slot bd merge-slot release # Release the slot ``` bd merge-slot [flags] ``` ## bd merge-slot acquire Attempt to acquire the merge slot for exclusive access. If the slot is available (status=open), it will be acquired: * status set to in\_progress * holder set to the requester If the slot is held (status=in\_progress), the command fails unless \--wait is passed, which adds the requester to the waiters queue. Use --holder to specify who is acquiring (default: BEADS\_ACTOR env var). ``` bd merge-slot acquire [flags] ``` **Flags:** ``` --holder string Who is acquiring the slot (default: BEADS_ACTOR) --wait Add to waiters list if slot is held ``` ## bd merge-slot check Check if the merge slot is available or held. Returns: * available: slot can be acquired * held by \: slot is currently held * not found: no merge slot exists for this rig ``` bd merge-slot check [flags] ``` ## bd merge-slot create Create a merge slot bead for serialized conflict resolution. The slot ID is automatically generated based on the beads prefix (e.g., gt-merge-slot). The slot is created with status=open (available). ``` bd merge-slot create [flags] ``` ## bd merge-slot release Release the merge slot after conflict resolution is complete. Sets status back to open and clears the holder field. If there are waiters, the highest-priority waiter should then acquire. ``` bd merge-slot release [flags] ``` **Flags:** ``` --holder string Who is releasing the slot (for verification) ``` # bd metrics Source: https://beads.gascity.com/cli-reference/metrics Show whether anonymous usage metrics are on, see exactly what is sent, and Generated from `bd help --doc metrics`. Show whether anonymous usage metrics are on, see exactly what is sent, and turn them on or off. bd shares anonymous usage metrics to learn how people actually use it — just which commands get run, plus the bd version and OS platform. That's how we decide what to polish next. We never collect your issues, paths, remotes, identity, or any user-supplied text. bd metrics show the current status and what is collected bd metrics on turn metrics on bd metrics off turn metrics off bd metrics example show real examples of the events bd sends ``` bd metrics [flags] ``` ## bd metrics example Show real examples of the anonymous metrics bd sends ``` bd metrics example [flags] ``` ## bd metrics off Turn anonymous usage metrics off ``` bd metrics off [flags] ``` ## bd metrics on Turn anonymous usage metrics on ``` bd metrics on [flags] ``` # bd migrate Source: https://beads.gascity.com/cli-reference/migrate Database migration and data transformation commands. Generated from `bd help --doc migrate`. Database migration and data transformation commands. Without subcommand, checks and updates database metadata to current version. Subcommands: hooks Plan git hook migration to marker-managed format issues Move issues between repositories schema Apply pending schema migrations (idempotent) sync Set up sync.branch workflow for multi-clone setups ``` bd migrate [flags] ``` **Flags:** ``` --dry-run Show what would be done without making changes --inspect Show migration plan and database state for AI agent analysis --json Output migration statistics in JSON format --update-repo-id Update repository ID (use after changing git remote) --yes Auto-confirm prompts ``` ## bd migrate hooks Analyze git hook files and sidecar artifacts for migration to marker-managed format. Modes: \--dry-run Preview migration operations without changing files \--apply Apply migration operations Examples: bd migrate hooks --dry-run bd migrate hooks --apply bd migrate hooks --apply --yes bd migrate hooks --dry-run --json ``` bd migrate hooks [path] [flags] ``` **Flags:** ``` --apply Apply planned hook migration changes --dry-run Show what would be done without making changes --json Output in JSON format --yes Skip confirmation prompt for --apply ``` ## bd migrate issues Move issues from one source repository to another with filtering and dependency preservation. This command updates the source\_repo field for selected issues, allowing you to: * Move contributor planning issues to upstream repository * Reorganize issues across multi-phase repositories * Consolidate issues from multiple repos Examples: # Preview migration from planning repo to current repo bd migrate-issues --from \~/.beads-planning --to . --dry-run # Move all open P1 bugs bd migrate-issues --from \~/repo1 --to \~/repo2 --priority 1 --type bug --status open # Move specific issues with their dependencies bd migrate-issues --from . --to \~/archive --id bd-abc --id bd-xyz --include closure # Move issues with label filter bd migrate-issues --from . --to \~/feature-work --label frontend --label urgent ``` bd migrate issues [flags] ``` **Flags:** ``` --dry-run Show plan without making changes --from string Source repository (required) --id strings Specific issue IDs to migrate (can specify multiple) --ids-file string File containing issue IDs (one per line) --include string Include dependencies: none/upstream/downstream/closure (default "none") --label strings Filter by labels (can specify multiple) --priority int Filter by priority (0-4) (default -1) --status string Filter by status (open/closed/all) --strict Fail on orphaned dependencies or missing repos --to string Destination repository (required) --type string Filter by issue type (bug/feature/task/epic/chore/decision) --within-from-only Only include dependencies from source repo (default true) --yes Skip confirmation prompt ``` ## bd migrate schema Apply pending schema migrations idempotently. Schema migrations also run automatically on store open, so this subcommand is typically a no-op. It exists to make migration explicit and observable in CI, release gates, and recovery scenarios. Example: bd migrate schema bd migrate schema --json ``` bd migrate schema [flags] ``` **Flags:** ``` --json Output in JSON format ``` ## bd migrate sync Configure separate branch workflow for multi-clone setups. This sets the sync.branch config value so that issue data is committed to a dedicated branch, keeping your main branch clean. Example: bd migrate sync beads-sync ``` bd migrate sync [flags] ``` **Flags:** ``` --dry-run Show what would be done without making changes --json Output in JSON format ``` # bd mol Source: https://beads.gascity.com/cli-reference/mol Manage molecules - work templates for agent workflows. Generated from `bd help --doc mol`. Manage molecules - work templates for agent workflows. Protos are template epics with the "template" label. They define a DAG of work that can be spawned to create real issues (molecules). The molecule metaphor: * A proto is an uninstantiated template (reusable work pattern) * Spawning creates a molecule (real issues) from the proto * Variables (\{\{key}}) are substituted during spawning * Bonding combines protos or molecules into compounds * Distilling extracts a proto from an ad-hoc epic Commands: show Show proto/molecule structure and variables pour Instantiate proto as persistent mol (liquid phase) wisp Instantiate proto as ephemeral wisp (vapor phase) bond Polymorphic combine: proto+proto, proto+mol, mol+mol squash Condense molecule to digest burn Discard wisp distill Extract proto from ad-hoc epic Use "bd formula list" to list available formulas. ``` bd mol [flags] ``` **Aliases:** protomolecule ## bd mol bond Bond two protos or molecules to create a compound. The bond command is polymorphic - it handles different operand types: formula + formula → cook both, compound proto formula + proto → cook formula, compound proto formula + mol → cook formula, spawn and attach proto + proto → compound proto (reusable template) proto + mol → spawn proto, attach to molecule mol + proto → spawn proto, attach to molecule mol + mol → join into compound molecule Formula names (e.g., mol-polecat-arm) are cooked inline as ephemeral protos. This avoids needing pre-cooked proto beads in the database. Bond types: sequential (default) - B runs after A completes parallel - B runs alongside A conditional - B runs only if A fails Phase control: By default, spawned protos follow the target's phase: * Attaching to mol (Ephemeral=false) → spawns as persistent (Ephemeral=false) * Attaching to ephemeral issue (Ephemeral=true) → spawns as ephemeral (Ephemeral=true) Override with: \--pour Force spawn as liquid (persistent, Ephemeral=false) \--ephemeral Force spawn as vapor (ephemeral, Ephemeral=true, excluded from Dolt sync via dolt\_ignore) Dynamic bonding (Christmas Ornament pattern): Use --ref to specify a custom child reference with variable substitution. This creates IDs like "parent.child-ref" instead of random hashes. Example: bd mol bond mol-worker-arm bd-patrol --ref arm-\{\{worker\_name}} --var worker\_name=ace # Creates: bd-patrol.arm-ace (and children like bd-patrol.arm-ace.capture) Use cases: * Found important bug during patrol? Use --pour to persist it * Need ephemeral diagnostic on persistent feature? Use --ephemeral * Spawning per-worker arms on a patrol? Use --ref for readable IDs Examples: bd mol bond mol-feature mol-deploy # Compound proto bd mol bond mol-feature mol-deploy --type parallel # Run in parallel bd mol bond mol-feature bd-abc123 # Attach proto to molecule bd mol bond bd-abc123 bd-def456 # Join two molecules bd mol bond mol-critical-bug wisp-patrol --pour # Persist found bug bd mol bond mol-temp-check bd-feature --ephemeral # Ephemeral diagnostic bd mol bond mol-arm bd-patrol --ref arm-\{\{name}} --var name=ace # Dynamic child ID ``` bd mol bond [flags] ``` **Aliases:** fart **Flags:** ``` --as string Custom title for compound proto (proto+proto only) --dry-run Preview what would be created --ephemeral Force spawn as vapor (ephemeral, Ephemeral=true) --pour Force spawn as liquid (persistent, Ephemeral=false) --ref string Custom child reference with {{var}} substitution (e.g., arm-{{polecat_name}}) --type string Bond type: sequential, parallel, or conditional (default "sequential") --var stringArray Variable substitution for spawned protos (key=value) ``` ## bd mol burn Burn a molecule, deleting it without creating a digest. Unlike squash (which creates a permanent digest before deletion), burn completely removes the molecule with no trace. Use this for: * Abandoned patrol cycles * Crashed or failed workflows * Test/debug molecules you don't want to preserve The burn operation differs based on molecule phase: * Wisp (ephemeral): Direct delete * Mol (persistent): Cascade delete (syncs to remotes) CAUTION: This is a destructive operation. The molecule's data will be permanently lost. If you want to preserve a summary, use 'bd mol squash'. Example: bd mol burn bd-abc123 # Delete molecule with no trace bd mol burn bd-abc123 --dry-run # Preview what would be deleted bd mol burn bd-abc123 --force # Skip confirmation bd mol burn bd-a1 bd-b2 bd-c3 # Batch delete multiple wisps ``` bd mol burn [molecule-id...] [flags] ``` **Flags:** ``` --dry-run Preview what would be deleted --force Skip confirmation prompt ``` ## bd mol current Show where you are in a molecule workflow. If molecule-id is given, show status for that molecule. If not given, infer from in\_progress issues assigned to current agent. The output shows all steps with status indicators: \[done] - Step is complete (closed) \[current] - Step is in\_progress (you are here) \[ready] - Step is ready to start (unblocked) \[blocked] - Step is blocked by dependencies \[pending] - Step is waiting For large molecules (>100 steps), a summary is shown instead. Use --limit or --range to view specific steps: bd mol current \ --limit 50 # Show first 50 steps bd mol current \ --range 100-150 # Show steps 100-150 ``` bd mol current [molecule-id] [flags] ``` **Flags:** ``` --for string Show molecules for a specific agent/assignee --limit int Maximum number of steps to display (0 = auto, use 'all' threshold) --range string Display specific step range (e.g., '1-50', '100-150') ``` ## bd mol distill Distill a molecule by extracting a reusable formula from an existing epic. This is the reverse of pour: instead of formula → molecule, it's molecule → formula. The distill command: 1. Loads the existing epic and all its children 2. Converts the structure to a .formula.json file 3. Replaces concrete values with \{\{variable}} placeholders (via --var flags) Use cases: * Team develops good workflow organically, wants to reuse it * Capture tribal knowledge as executable templates * Create starting point for similar future work Variable syntax (both work - we detect which side is the concrete value): \--var branch=feature-auth Spawn-style: variable=value (recommended) \--var feature-auth=branch Substitution-style: value=variable Output locations (first writable wins): 1. \/formulas/ (project-level, default) 2. \/.beads/formulas/ (repo-local formulas) 3. \~/.beads/formulas/ (user-level, if project not writable) Examples: bd mol distill bd-o5xe my-workflow bd mol distill bd-abc release-workflow --var feature\_name=auth-refactor ``` bd mol distill [formula-name] [flags] ``` **Flags:** ``` --dry-run Preview what would be created --output string Output directory for formula file --var stringArray Replace value with {{variable}} placeholder (variable=value) ``` ## bd mol last-activity Show the most recent activity timestamp for a molecule. Returns the timestamp of the most recent change to any step in the molecule, making it easy to detect stale or stuck molecules. Activity sources: step\_closed - A step was closed step\_updated - A step was updated (claimed, edited, etc.) molecule\_updated - The molecule root itself was updated Examples: bd mol last-activity hq-wisp-0laki bd mol last-activity hq-wisp-0laki --json ``` bd mol last-activity [flags] ``` ## bd mol pour Pour a proto into a persistent mol - like pouring molten metal into a mold. This is the chemistry-inspired command for creating PERSISTENT work from templates. The resulting mol lives in .beads/ (permanent storage) and is synced with git. Phase transition: Proto (solid) -> pour -> Mol (liquid) WHEN TO USE POUR vs WISP: pour (liquid): Persistent work that needs audit trail * Feature implementations spanning multiple sessions * Work you may need to reference later * Anything worth preserving in git history wisp (vapor): Ephemeral work that auto-cleans up * Release workflows (one-time execution) * Operational loops and recurring cycles * Health checks and diagnostics * Any operational workflow without audit value TIP: Formulas can specify phase:"vapor" to recommend wisp usage. If you pour a vapor-phase formula, you'll get a warning. Examples: bd mol pour mol-feature --var name=auth # Persistent feature work bd mol pour mol-review --var pr=123 # Persistent code review ``` bd mol pour [flags] ``` **Flags:** ``` --assignee string Assign the root issue to this agent/user --attach strings Proto to attach after spawning (repeatable) --attach-type string Bond type for attachments: sequential, parallel, or conditional (default "sequential") --dry-run Preview what would be created --var stringArray Variable substitution (key=value) ``` ## bd mol progress Show efficient progress summary for a molecule. This command uses indexed queries to count progress without loading all steps, making it suitable for very large molecules (millions of steps). If no molecule-id is given, shows progress for any molecule you're working on. Output includes: * Progress: completed / total (percentage) * Current step: the in-progress step (if any) * Rate: steps/hour based on closure times * ETA: estimated time to completion Example: bd mol progress bd-hanoi-xyz ``` bd mol progress [molecule-id] [flags] ``` ## bd mol ready Find molecules where a gate has closed and the workflow is ready to resume. This command discovers molecules waiting at a gate step where: 1. The molecule has a gate bead that blocks a step 2. The gate bead is now closed (condition satisfied) 3. The blocked step is now ready to proceed 4. No agent currently has this molecule hooked This enables discovery-based resume without explicit waiter tracking. The patrol system uses this to find and dispatch gate-ready molecules. Examples: bd mol ready --gated # Find all gate-ready molecules bd mol ready --gated --json # JSON output for automation ``` bd mol ready --gated [flags] ``` ## bd mol seed Verify that a formula is accessible and can be cooked. The seed command checks formula search paths to ensure a formula exists and can be loaded. This is useful for verifying system health before attempting to spawn work from a formula. Formula search paths (checked in order): 1. \/formulas/ (active project) 2. \/.beads/formulas/ (repo-local formulas) 3. \~/.beads/formulas/ (user level) 4. \$GT\_ROOT/.beads/formulas/ (shared workspace root, if GT\_ROOT set) Examples: bd mol seed mol-feature # Verify specific formula bd mol seed mol-review --var name=test # Verify with variable substitution ``` bd mol seed [flags] ``` **Flags:** ``` --var stringArray Variable substitution for condition filtering (key=value) ``` ## bd mol show Show molecule structure and details. The --parallel flag highlights parallelizable steps: * Steps with no blocking dependencies can run in parallel * Shows which steps are ready to start now * Identifies parallel groups (steps that can run concurrently) Example: bd mol show bd-patrol --parallel ``` bd mol show [flags] ``` **Flags:** ``` -p, --parallel Show parallel step analysis ``` ## bd mol squash Squash a molecule's ephemeral children into a single digest issue. This command collects all ephemeral child issues of a molecule (Ephemeral=true), generates a summary digest, and promotes the wisps to persistent by clearing their Wisp flag (or optionally deletes them). The squash operation: 1. Loads the molecule and all its children 2. Filters to only wisps (ephemeral issues with Ephemeral=true) 3. Generates a digest (summary of work done) 4. Creates a permanent digest issue (Ephemeral=false) 5. Clears Wisp flag on children (promotes to persistent) OR keeps them with --keep-children (default: delete) AGENT INTEGRATION: Use --summary to provide an AI-generated summary. This keeps bd as a pure tool - the calling agent (orchestrator worker, Claude Code, etc.) is responsible for generating intelligent summaries. Without --summary, a basic concatenation of child issue content is used. This is part of the wisp workflow: spawn creates wisps, execution happens, squash compresses the trace into an outcome (digest). Example: bd mol squash bd-abc123 # Squash and promote children bd mol squash bd-abc123 --dry-run # Preview what would be squashed bd mol squash bd-abc123 --keep-children # Keep wisps after digest bd mol squash bd-abc123 --summary "Agent-generated summary of work done" ``` bd mol squash [flags] ``` **Flags:** ``` --dry-run Preview what would be squashed --keep-children Don't delete ephemeral children after squash --summary string Agent-provided summary (bypasses auto-generation) ``` ## bd mol stale Detect molecules (epics with children) that are complete but still open. A molecule is considered stale if: 1. All children are closed (Completed == Total) 2. Root issue is still open 3. Not assigned to anyone (optional, use --unassigned) 4. Is blocking other work (optional, use --blocking) By default, shows all complete-but-unclosed molecules. Examples: bd mol stale # List all stale molecules bd mol stale --json # Machine-readable output bd mol stale --blocking # Only show those blocking other work bd mol stale --unassigned # Only show unassigned molecules bd mol stale --all # Include molecules with 0 children ``` bd mol stale [flags] ``` **Flags:** ``` --all Include molecules with 0 children --blocking Only show molecules blocking other work --unassigned Only show unassigned molecules ``` ## bd mol wisp Create or manage wisps - EPHEMERAL molecules for operational workflows. When called with a proto-id argument, creates a wisp from that proto. When called with a subcommand (list, gc), manages existing wisps. Wisps are issues with Ephemeral=true in the main database. They're stored locally but NOT synced via git. WHEN TO USE WISP vs POUR: wisp (vapor): Ephemeral work that auto-cleans up * Release workflows (one-time execution) * Operational loops and recurring cycles * Health checks and diagnostics * Any operational workflow without audit value pour (liquid): Persistent work that needs audit trail * Feature implementations spanning multiple sessions * Work you may need to reference later * Anything worth preserving in git history TIP: Formulas can specify phase:"vapor" to recommend wisp usage. If you use pour on a vapor-phase formula, you'll get a warning. The wisp lifecycle: 1. Create: bd mol wisp \ or bd create --ephemeral 2. Execute: Normal bd operations work on wisp issues 3. Squash: bd mol squash \ (clears Ephemeral flag, promotes to persistent) 4. Or burn: bd mol burn \ (deletes without creating digest) Examples: bd mol wisp beads-release --var version=1.0 # Release workflow bd mol wisp mol-my-workflow # Ephemeral operational cycle bd mol wisp list # List all wisps bd mol wisp gc # Garbage collect old wisps Subcommands: list List all wisps in current context gc Garbage collect orphaned wisps ``` bd mol wisp [proto-id] [flags] ``` **Flags:** ``` --dry-run Preview what would be created --root-only Create only the root issue (no child step issues) --var stringArray Variable substitution (key=value) ``` ### bd mol wisp create Create a wisp from a proto - sublimation from solid to vapor. This is the chemistry-inspired command for creating ephemeral work from templates. The resulting wisp is stored in the main database with Ephemeral=true and NOT synced via git. Phase transition: Proto (solid) -> Wisp (vapor) Use wisp for: * Operational loops and recurring cycles * Health checks and monitoring * One-shot orchestration runs * Routine operations with no audit value The wisp will: * Be stored in main database with Ephemeral=true flag * NOT be synced via git * Either evaporate (burn) or condense to digest (squash) Examples: bd mol wisp create mol-patrol # Ephemeral patrol cycle bd mol wisp create mol-health-check # One-time health check bd mol wisp create mol-diagnostics --var target=db # Diagnostic run ``` bd mol wisp create [flags] ``` **Flags:** ``` --dry-run Preview what would be created --root-only Create only the root issue (no child step issues) --var stringArray Variable substitution (key=value) ``` ### bd mol wisp gc Garbage collect old or abandoned wisps from the database. A wisp is considered abandoned if: * It hasn't been updated in --age duration and is not closed Abandoned wisps are deleted without creating a digest. Use 'bd mol squash' if you want to preserve a summary before garbage collection. Use --closed to purge ALL closed wisps (regardless of age). This is the fastest way to reclaim space from accumulated wisp bloat. Safe by default: requires --force to actually delete. Note: This uses time-based cleanup, appropriate for ephemeral wisps. For graph-pressure staleness detection (blocking other work), see 'bd mol stale'. Examples: bd mol wisp gc # Clean abandoned wisps (default: 1h threshold) bd mol wisp gc --dry-run # Preview what would be cleaned bd mol wisp gc --age 24h # Custom age threshold bd mol wisp gc --all # Also clean closed wisps older than threshold bd mol wisp gc --closed # Preview closed wisp deletion bd mol wisp gc --closed --force # Delete all closed wisps bd mol wisp gc --closed --dry-run # Explicit dry-run (same as no --force) bd mol wisp gc --exclude-type agent,rig # Protect agent and rig wisps from GC bd mol wisp gc --closed --force --exclude-type mol # Delete closed wisps except mol type ``` bd mol wisp gc [flags] ``` **Flags:** ``` --age string Age threshold for abandoned wisp detection (default "1h") --all Also clean closed wisps older than threshold --closed Delete all closed wisps (ignores --age threshold) --dry-run Preview what would be cleaned --exclude-type strings Exclude wisps of these types from GC (comma-separated, e.g., agent,rig) -f, --force Actually delete (default: preview only) ``` ### bd mol wisp list List all wisps (ephemeral molecules) in the current context. Wisps are issues with Ephemeral=true in the main database. They are stored locally but not synced via git. The list shows: * ID: Issue ID of the wisp * Title: Wisp title * Status: Current status (open, in\_progress, closed) * Started: When the wisp was created * Updated: Last modification time Old wisp detection: * Old wisps haven't been updated in 24+ hours * Use 'bd mol wisp gc' to clean up old/abandoned wisps Examples: bd mol wisp list # List all wisps bd mol wisp list --json # JSON output for programmatic use bd mol wisp list --all # Include closed wisps ``` bd mol wisp list [flags] ``` **Flags:** ``` --all Include closed wisps --type string Filter by issue type (e.g., agent, task, patrol) ``` # bd note Source: https://beads.gascity.com/cli-reference/note Append a note to an issue's notes field. Generated from `bd help --doc note`. Append a note to an issue's notes field. Shorthand for 'bd update \ --append-notes "text"'. Examples: bd note gt-abc "Fixed the flaky test" bd note gt-abc Fixed the flaky test echo "note from pipe" | bd note gt-abc --stdin bd note gt-abc --file notes.txt ``` bd note [text...] [flags] ``` **Flags:** ``` --file string Read note text from file --stdin Read note text from stdin ``` # bd notion Source: https://beads.gascity.com/cli-reference/notion Commands for syncing issues between beads and Notion. Generated from `bd help --doc notion`. Commands for syncing issues between beads and Notion. ``` bd notion [flags] ``` ## bd notion connect Connect bd to an existing Notion database or data source ``` bd notion connect [flags] ``` **Flags:** ``` --url string Existing Notion database or data source URL ``` ## bd notion init Create a dedicated Beads database in Notion ``` bd notion init [flags] ``` **Flags:** ``` --parent string Parent page ID --title string Database title (default "Beads Issues") ``` ## bd notion pull Pull one or more items from Notion. Accepts bead IDs or external references as positional arguments. Equivalent to: bd notion sync --pull --issues \ ``` bd notion pull [refs...] [flags] ``` **Flags:** ``` --dry-run Preview pull without making changes ``` ## bd notion push Push one or more beads issues to Notion. Accepts bead IDs as positional arguments. Equivalent to: bd notion sync --push --issues \ ``` bd notion push [bead-ids...] [flags] ``` **Flags:** ``` --dry-run Preview push without making changes ``` ## bd notion status Show Notion sync status ``` bd notion status [flags] ``` ## bd notion sync Synchronize issues between beads and Notion. By default this performs bidirectional sync. Use --pull or --push to limit direction. ``` bd notion sync [flags] ``` **Flags:** ``` --create-only Only create missing remote pages, do not update existing ones --dry-run Preview changes without making mutations --issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent. --parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues. --prefer-local On conflict, keep the local beads version --prefer-notion On conflict, use the Notion version --pull Only pull issues from Notion --push Only push issues to Notion --state string Issue state to sync: open, closed, or all (default "all") ``` # bd onboard Source: https://beads.gascity.com/cli-reference/onboard Display a minimal snippet to add to your agent instructions file for bd integration. Generated from `bd help --doc onboard`. Display a minimal snippet to add to your agent instructions file for bd integration. By default, the agent instructions file is AGENTS.md. Use 'bd init --agents-file' to configure a different filename (e.g. BEADS.md). This outputs a small (\~10 line) snippet that points to 'bd prime' for full workflow context. This is the same minimal profile that 'bd init' generates by default. This approach: • Keeps your agent file lean (doesn't bloat with instructions) • bd prime provides dynamic, always-current workflow details • Hooks auto-inject bd prime at session start For agents or environments that do not auto-inject hook output, use 'bd init --agents-profile=full' to embed the complete command reference. ``` bd onboard [flags] ``` # bd orphans Source: https://beads.gascity.com/cli-reference/orphans Identify orphaned issues - issues that are referenced in commit messages but remain open or in_progress in the database. Generated from `bd help --doc orphans`. Identify orphaned issues - issues that are referenced in commit messages but remain open or in\_progress in the database. This helps identify work that has been implemented but not formally closed. Examples: bd orphans # Show orphaned issues bd orphans --json # Machine-readable output bd orphans --details # Show full commit information bd orphans --fix # Close orphaned issues with confirmation bd orphans --label theme:personal # Only orphans with this label bd orphans --label-any theme:personal,theme:ventures # Orphans with either label ``` bd orphans [flags] ``` **Flags:** ``` --details Show full commit information -f, --fix Close orphaned issues with confirmation -l, --label strings Filter by labels (AND: must have ALL). Can combine with --label-any --label-any strings Filter by labels (OR: must have AT LEAST ONE). Can combine with --label ``` # bd ping Source: https://beads.gascity.com/cli-reference/ping Lightweight health check that confirms bd can reach its database. Generated from `bd help --doc ping`. Lightweight health check that confirms bd can reach its database. Steps: 1. Resolve the .beads workspace 2. Open the store (embedded or server) 3. Run a trivial query (issue count) 4. Report timing Exit 0 on success, exit 1 on failure. Examples: bd ping # Quick connectivity check bd ping --json # Structured output for automation ``` bd ping [flags] ``` # bd preflight Source: https://beads.gascity.com/cli-reference/preflight Display a checklist of common pre-PR checks for contributors. Generated from `bd help --doc preflight`. Display a checklist of common pre-PR checks for contributors. This command helps catch common issues before pushing to CI: * Tests not run locally * Lint errors * Unformatted Go files * .beads/issues.jsonl pollution * Stale nix vendorHash * Version mismatches Examples: bd preflight # Show checklist bd preflight --check # Run checks automatically bd preflight --check --json # JSON output for programmatic use bd preflight --check --skip-lint # Explicitly skip lint check ``` bd preflight [flags] ``` **Flags:** ``` --check Run checks automatically --fix Auto-fix issues where possible (not yet implemented) --json Output results as JSON --skip-lint Skip lint check explicitly ``` # bd prime Source: https://beads.gascity.com/cli-reference/prime Output essential Beads workflow context in AI-optimized markdown format. Generated from `bd help --doc prime`. Output essential Beads workflow context in AI-optimized markdown format. Automatically detects if MCP server is active and adapts output: * MCP mode: Brief workflow reminders (\~50 tokens) * CLI mode: Full command reference (\~1-2k tokens) Designed for Claude Code, Gemini CLI, and Codex SessionStart hooks to prevent agents from forgetting bd workflow after context compaction. Config options: * no-git-ops: When true, outputs stealth mode (no git commands in session close protocol). Set via: bd config set no-git-ops true Useful when you want to control when commits happen manually. Workflow customization: * Place a .beads/PRIME.md file in the local clone or resolved workspace to override the default output entirely. * Use --export to dump the default content for customization. * Use --memories-only for hook contexts that should inject only persistent memories. ``` 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) --mcp Force MCP mode (minimal output) --memories-only Output only persistent memories for compact hook contexts --stealth Stealth mode (no git operations, flush only) ``` # bd priority Source: https://beads.gascity.com/cli-reference/priority Set the priority of an issue. Generated from `bd help --doc priority`. Set the priority of an issue. Shorthand for 'bd update \ --priority \'. Priority levels: 0 - Critical (security, data loss, broken builds) 1 - High (major features, important bugs) 2 - Medium (default) 3 - Low (polish, optimization) 4 - Backlog (future ideas) Examples: bd priority bd-123 0 # Critical bd priority bd-123 2 # Medium ``` bd priority [flags] ``` # bd promote Source: https://beads.gascity.com/cli-reference/promote Promote a wisp (ephemeral issue) to a permanent bead. Generated from `bd help --doc promote`. Promote a wisp (ephemeral issue) to a permanent bead. This copies the issue from the wisps table (dolt\_ignored) to the permanent issues table (Dolt-versioned), preserving labels, dependencies, events, and comments. The original ID is preserved so all links keep working. A comment is added recording the promotion and optional reason. Examples: bd promote bd-wisp-abc123 bd promote bd-wisp-abc123 --reason "Worth tracking long-term" ``` bd promote [flags] ``` **Flags:** ``` -r, --reason string Reason for promotion ``` # bd prune Source: https://beads.gascity.com/cli-reference/prune Permanently delete closed non-ephemeral beads and their associated data. Generated from `bd help --doc prune`. Permanently delete closed non-ephemeral beads and their associated data. Use this to trim closed regular beads (tasks, features, bugs, chores, etc.) that are no longer useful. The common case is a long-lived repo where closed work has piled up and is bloating auto-export or slowing queries. Requires --older-than or --pattern. The flag is a safety gate — without it, a muscle-memory `--force` could wipe every closed bead in the repo. Use `--pattern '*'` if you really do want to sweep everything closed. Deletes: issues, dependencies, labels, events, and comments for matching beads. Skips: pinned beads (protected), open/in-progress beads, and ephemeral beads. To delete closed ephemeral beads (wisps, transient molecules) use `bd purge` instead. For full Dolt storage reclaim after deleting many rows, follow with `bd flatten` so history can be collapsed and old chunks can be garbage-collected. EXAMPLES: bd prune --older-than 30d # Preview closed beads >30d old bd prune --older-than 30d --force # Delete them bd prune --older-than 90d --dry-run # Detailed preview with stats bd prune --pattern "*" --force # Delete all closed regular beads bd prune --pattern "gm-temp-*" --force # Scope to a pattern ``` bd prune [flags] ``` **Flags:** ``` --dry-run Preview what would be pruned with stats -f, --force Actually prune (without this, shows preview) --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-*') ``` # bd purge Source: https://beads.gascity.com/cli-reference/purge Permanently delete closed ephemeral beads and their associated data. Generated from `bd help --doc purge`. Permanently delete closed ephemeral beads and their associated data. Closed ephemeral beads (wisps, transient molecules) accumulate rapidly and have no value once closed. This command removes them to reclaim storage. Deletes: issues, dependencies, labels, events, and comments for matching beads. Skips: pinned beads (protected). To delete closed non-ephemeral beads (regular tasks, features, bugs, etc.) use `bd prune` instead. For full Dolt storage reclaim after deleting many rows, follow with `bd flatten` so history can be collapsed and old chunks can be garbage-collected. EXAMPLES: bd purge # Preview what would be purged bd purge --force # Delete all closed ephemeral beads bd purge --older-than 7d --force # Only purge items closed 7+ days ago bd purge --pattern "*-wisp-*" # Only purge matching ID pattern bd purge --dry-run # Detailed preview with stats ``` bd purge [flags] ``` **Flags:** ``` --dry-run Preview what would be purged with stats -f, --force Actually purge (without this, shows preview) --older-than string Only purge beads closed more than N ago (e.g., 7d, 2w, 30) --pattern string Only purge beads matching ID glob pattern (e.g., *-wisp-*) ``` # bd q Source: https://beads.gascity.com/cli-reference/q Quick capture creates an issue and outputs only the issue ID. Generated from `bd help --doc q`. Quick capture creates an issue and outputs only the issue ID. Designed for scripting and AI agent integration. Example: bd q "Fix login bug" # Outputs: bd-a1b2 ISSUE=\$(bd q "New feature") # Capture ID in variable bd q "Task" | xargs bd show # Pipe to other commands ``` bd q [title] [flags] ``` **Flags:** ``` -l, --labels strings Labels -p, --priority string Priority (0-4 or P0-P4) (default "2") -t, --type string Issue type (default "task") ``` # bd query Source: https://beads.gascity.com/cli-reference/query Query issues using a simple query language that supports compound filters, Generated from `bd help --doc query`. Query issues using a simple query language that supports compound filters, boolean operators, and date-relative expressions. The query language enables complex filtering that would otherwise require multiple flags or piping through jq. Syntax: field=value Equality comparison field!=value Inequality comparison field>value Greater than field>=value Greater than or equal field\1" bd query "status=open AND priority\<=2 AND updated>7d" bd query "(status=open OR status=blocked) AND priority\<2" bd query "type=bug AND label=urgent" bd query "NOT status=closed" bd query "assignee=none AND type=task" bd query "created>30d AND status!=closed" bd query "label=frontend OR label=backend" bd query "title=authentication AND priority=0" ``` bd query [expression] [flags] ``` **Flags:** ``` -a, --all Include closed issues (default: exclude closed) -n, --limit int Limit results (default: 50, 0 = unlimited) (default 50) --long Show detailed multi-line output for each issue --offset int Skip the first N matching results (0-based). Only supported under --proxied-server. --parse-only Only parse the query and show the AST (for debugging) -r, --reverse Reverse sort order --sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee ``` # bd quickstart Source: https://beads.gascity.com/cli-reference/quickstart Display a quick start guide showing common bd workflows and patterns. Generated from `bd help --doc quickstart`. Display a quick start guide showing common bd workflows and patterns. ``` bd quickstart [flags] ``` # bd ready Source: https://beads.gascity.com/cli-reference/ready Show ready work (open issues with no active blockers). Generated from `bd help --doc ready`. Show ready work (open issues with no active blockers). Excludes in\_progress, blocked, deferred, and hooked issues. This uses the GetReadyWork API which applies blocker-aware semantics to find truly claimable work. Note: 'bd list --ready' uses the same blocker-aware ready-work semantics. Use --mol to filter to a specific molecule's steps: bd ready --mol bd-patrol # Show ready steps within molecule Use --gated to find molecules ready for gate-resume dispatch: bd ready --gated # Find molecules where a gate closed Use --claim to atomically claim the first ready issue matching the filters: bd ready --claim --json This is useful for agents executing molecules to see which steps can run next. ``` bd ready [flags] ``` **Flags:** ``` -a, --assignee string Filter by assignee --claim Atomically claim the first ready issue matching the filters --exclude-label strings Exclude issues that have ANY of these labels --exclude-type strings Exclude issue types from results (comma-separated or repeatable, e.g., --exclude-type=convoy,epic) --explain Show dependency-aware reasoning for why issues are ready or blocked --gated Find molecules ready for gate-resume dispatch --has-metadata-key string Filter issues that have this metadata key set --include-deferred Include issues with future defer_until timestamps --include-ephemeral Include ephemeral issues (wisps) in results -l, --label strings Filter by labels (AND: must have ALL). Can combine with --label-any --label-any strings Filter by labels (OR: must have AT LEAST ONE). Can combine with --label -n, --limit int Maximum issues to show (use 0 for unlimited) (default 100) --metadata-field stringArray Filter by metadata field (key=value, repeatable) --mol string Filter to steps within a specific molecule --mol-type string Filter by molecule type: swarm, patrol, or work --offset int Skip the first N matching results (0-based). Only supported under --proxied-server. --parent string Filter to descendants of this bead/epic --plain Display issues as a plain numbered list --pretty Display issues in a tree format with status/priority symbols (default true) -p, --priority int Filter by priority -s, --sort string Sort policy: priority (default), hybrid, oldest (default "priority") -t, --type string Filter by issue type (task, bug, feature, epic, decision, merge-request). Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision -u, --unassigned Show only unassigned issues ``` # bd recall Source: https://beads.gascity.com/cli-reference/recall Retrieve the full content of a memory by its key. Generated from `bd help --doc recall`. Retrieve the full content of a memory by its key. Examples: bd recall dolt-phantoms bd recall auth-jwt ``` bd recall [flags] ``` # bd recompute-blocked Source: https://beads.gascity.com/cli-reference/recompute-blocked Recompute the denormalized is_blocked flag for every issue and wisp. Generated from `bd help --doc recompute-blocked`. Recompute the denormalized is\_blocked flag for every issue and wisp. is\_blocked is derived from the dependency graph and maintained automatically by local writes and by a post-pull recompute scoped to what the merge changed. If that scoped recompute is skipped — a recompute that failed after its merge committed, or a conflicted pull resolved by hand — the flag can go stale, and a later pull that merges nothing will not refresh it (bd-6dnrw\.37). 'bd ready' trusts the flag, so stale values silently hide ready work or surface blocked work. This command runs the full recompute unconditionally and commits the result. It is idempotent: on a consistent database it changes nothing. Works in both embedded and server mode (unlike 'bd doctor', which is server-mode only). Examples: bd recompute-blocked # Repair stale is\_blocked flags bd recompute-blocked --json # Machine-parseable \{"rows\_corrected": N} ``` bd recompute-blocked [flags] ``` # bd remember Source: https://beads.gascity.com/cli-reference/remember Store a memory that persists across sessions and account rotations. Generated from `bd help --doc remember`. Store a memory that persists across sessions and account rotations. Memories are injected at prime time (bd prime) so you have them in every session without manual loading. The positional arg is the memory CONTENT (the key is auto-generated from it unless --key is given). As a convenience, if the arg is a bare key naming an existing memory, it is RECALLED instead of stored (same as 'bd recall'); a bare key naming nothing is refused. Use --key to store slug-like content. Examples: bd remember "always run tests with -race flag" bd remember "Dolt phantom DBs hide in three places" --key dolt-phantoms bd remember "auth module uses JWT not sessions" --key auth-jwt bd remember dolt-phantoms # bare existing key: reads it (= bd recall) ``` bd remember "" [flags] ``` **Flags:** ``` --key string Explicit key for the memory (auto-generated from content if not set). If a memory with this key already exists, it will be updated in place ``` # bd rename Source: https://beads.gascity.com/cli-reference/rename Rename an issue from one ID to another. Generated from `bd help --doc rename`. Rename an issue from one ID to another. This updates: * The issue's primary ID * All references in other issues (descriptions, titles, notes, etc.) * Dependencies pointing to/from this issue * Labels, comments, and events Examples: bd rename bd-w382l bd-dolt # Rename to memorable ID bd rename gt-abc123 gt-auth # Use descriptive ID Note: The new ID must use a valid prefix for this database. ``` bd rename [flags] ``` # bd rename-prefix Source: https://beads.gascity.com/cli-reference/rename-prefix Rename the issue prefix for all issues in the database. Generated from `bd help --doc rename-prefix`. Rename the issue prefix for all issues in the database. This will update all issue IDs and all text references across all fields. USE CASES: * Shortening long prefixes (e.g., 'knowledge-work-' → 'kw-') * Rebranding project naming conventions * Consolidating multiple prefixes after database corruption * Migrating to team naming standards Prefix validation rules: * Max length: 8 characters * Allowed characters: lowercase letters, numbers, hyphens * Must start with a letter * Must end with a hyphen (e.g., 'kw-', 'work-') * Cannot be empty or just a hyphen Multiple prefix detection and repair: If issues have multiple prefixes (corrupted database), use --repair to consolidate them. The --repair flag will rename all issues with incorrect prefixes to the new prefix, preserving issues that already have the correct prefix. EXAMPLES: bd rename-prefix kw- # Rename from 'knowledge-work-' to 'kw-' bd rename-prefix mtg- --repair # Consolidate multiple prefixes into 'mtg-' bd rename-prefix team- --dry-run # Preview changes without applying NOTE: This is a rare operation. Most users never need this command. ``` bd rename-prefix [flags] ``` **Flags:** ``` --dry-run Preview changes without applying them --repair Repair database with multiple prefixes by consolidating them ``` # bd reopen Source: https://beads.gascity.com/cli-reference/reopen Reopen closed issues by setting status to 'open' and clearing the closed_at timestamp. Generated from `bd help --doc reopen`. Reopen closed issues by setting status to 'open' and clearing the closed\_at timestamp. This is more explicit than 'bd update --status open' and emits a Reopened event. ``` bd reopen [id...] [flags] ``` **Flags:** ``` -r, --reason string Reason for reopening ``` # bd repo Source: https://beads.gascity.com/cli-reference/repo Configure and manage multiple repository support for multi-repo hydration. Generated from `bd help --doc repo`. Configure and manage multiple repository support for multi-repo hydration. Multi-repo support allows hydrating issues from multiple beads repositories into a single database for unified cross-repo issue tracking. Configuration is stored in .beads/config.yaml under the 'repos' section: repos: primary: "." additional: * \~/beads-planning * \~/work-repo Examples: bd repo add \~/beads-planning # Add planning repo bd repo add ../other-repo # Add relative path repo bd repo list # Show all configured repos bd repo remove \~/beads-planning # Remove by path bd repo sync # Sync from all configured repos ``` bd repo [flags] ``` ## bd repo add Add a repository path to the repos.additional list in config.yaml. The path should point to a directory containing a .beads folder. Paths can be absolute or relative (they are stored as-is). This modifies .beads/config.yaml, which is version-controlled and shared across all clones of this repository. ``` bd repo add [flags] ``` **Flags:** ``` --json Output JSON ``` ## bd repo list List all repositories configured in .beads/config.yaml. Shows the primary repository (always ".") and any additional repositories configured for hydration. ``` bd repo list [flags] ``` **Flags:** ``` --json Output JSON ``` ## bd repo remove Remove a repository path from the repos.additional list in config.yaml. The path must exactly match what was added (e.g., if you added "~~/foo", you must remove "~~/foo", not "/home/user/foo"). This command also removes any previously-hydrated issues from the database that came from the removed repository. ``` bd repo remove [flags] ``` **Flags:** ``` --json Output JSON ``` ## bd repo sync Synchronize issues from all configured additional repositories. Reads issues.jsonl from each additional repository and imports them into the primary database with their original prefixes and source\_repo set. Uses mtime caching to skip repos whose JSONL hasn't changed. Also triggers Dolt push/pull if a remote is configured. ``` bd repo sync [flags] ``` **Flags:** ``` --json Output JSON --verbose Show detailed sync progress ``` # bd restore Source: https://beads.gascity.com/cli-reference/restore Restore the pre-compaction content of a compacted issue. Generated from `bd help --doc restore`. Restore the pre-compaction content of a compacted issue. When an issue is compacted, its description/design/notes/acceptance criteria are summarized and the originals are archived to a compaction snapshot. This command recovers that original content. By default it is read-only: it displays the archived content without modifying the database. Pass --apply to write the original content back into the issue and step its compaction level back down. If no archived snapshot exists (e.g. the issue was compacted by an older bd before snapshot archiving), restore falls back to a best-effort reconstruction from Dolt version history, which can only be displayed, not applied. ``` bd restore [flags] ``` **Flags:** ``` --apply Write the restored content back into the issue (default: display only) --json Output restore results in JSON format ``` # bd rules Source: https://beads.gascity.com/cli-reference/rules Audit and compact Claude rules Generated from `bd help --doc rules`. Audit and compact Claude rules ``` bd rules [flags] ``` ## bd rules audit Scan rules for contradictions and merge opportunities ``` bd rules audit [flags] ``` **Flags:** ``` --path string Path to rules directory (default ".claude/rules/") --threshold float Jaccard similarity threshold (default 0.6) ``` ## bd rules compact Merge related rules into composites ``` bd rules compact [flags] ``` **Flags:** ``` --auto Apply audit suggestions --dry-run Preview without applying --group strings Rule names to merge --path string Path to rules directory (default ".claude/rules/") ``` # bd search Source: https://beads.gascity.com/cli-reference/search Search issues across title and ID (excludes closed issues by default). Generated from `bd help --doc search`. Search issues across title and ID (excludes closed issues by default). ID-like queries (e.g., "bd-123", "hq-319") use fast exact/prefix matching. Text queries search titles. Use --desc-contains for description search. Use --status all to include closed issues. Examples: bd search "authentication bug" bd search "login" --status open bd search "database" --label backend --limit 10 bd search --query "performance" --assignee alice bd search "bd-5q" # Search by partial ID (fast prefix match) bd search "security" --priority-min 0 --priority-max 2 bd search "bug" --created-after 2025-01-01 bd search "refactor" --status all # Include closed issues bd search "bug" --sort priority bd search "task" --sort created --reverse bd search "api" --desc-contains "endpoint" bd search "cleanup" --no-assignee --no-labels ``` bd search [query] [flags] ``` **Flags:** ``` -a, --assignee string Filter by assignee --closed-after string Filter issues closed after date (YYYY-MM-DD or RFC3339) --closed-before string Filter issues closed before date (YYYY-MM-DD or RFC3339) --created-after string Filter issues created after date (YYYY-MM-DD or RFC3339) --created-before string Filter issues created before date (YYYY-MM-DD or RFC3339) --desc-contains string Filter by description substring (case-insensitive) --empty-description Filter issues with empty or missing description --external-contains string Filter by external ref substring (case-insensitive) --has-metadata-key string Filter issues that have this metadata key set -l, --label strings Filter by labels (AND: must have ALL) --label-any strings Filter by labels (OR: must have AT LEAST ONE) -n, --limit int Limit results (default: 50) (default 50) --long Show detailed multi-line output for each issue --metadata-field stringArray Filter by metadata field (key=value, repeatable) --no-assignee Filter issues with no assignee --no-labels Filter issues with no labels --notes-contains string Filter by notes substring (case-insensitive) --priority-max string Filter by maximum priority (inclusive, 0-4 or P0-P4) --priority-min string Filter by minimum priority (inclusive, 0-4 or P0-P4) --query string Search query (alternative to positional argument) -r, --reverse Reverse sort order --sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed, all). Default excludes closed; use 'all' to include closed. Note: dependency-blocked issues use 'bd blocked' -t, --type string Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate) --updated-after string Filter issues updated after date (YYYY-MM-DD or RFC3339) --updated-before string Filter issues updated before date (YYYY-MM-DD or RFC3339) ``` # bd set-state Source: https://beads.gascity.com/cli-reference/set-state Atomically set operational state on an issue. Generated from `bd help --doc set-state`. Atomically set operational state on an issue. This command: 1. Creates an event bead recording the state change (source of truth) 2. Removes any existing label for the dimension 3. Adds the new dimension:value label (fast lookup cache) State labels follow the convention \:\, for example: patrol:active, patrol:muted mode:normal, mode:degraded health:healthy, health:failing Examples: bd set-state agent-abc patrol=muted --reason "Investigating stuck worker" bd set-state agent-abc mode=degraded --reason "High error rate detected" bd set-state agent-abc health=healthy The --reason flag provides context for the event bead (recommended). ``` bd set-state = [flags] ``` **Flags:** ``` --reason string Reason for the state change (recorded in event) ``` # bd setup Source: https://beads.gascity.com/cli-reference/setup Setup integration files for AI editors and coding assistants. Generated from `bd help --doc setup`. Setup integration files for AI editors and coding assistants. Recipes define where beads workflow instructions are written. Built-in recipes include cursor, claude, copilot, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode. Examples: bd setup cursor # Install Cursor IDE integration bd setup codex # Install Codex skill + AGENTS.md guidance + native hooks bd setup codex --global # Install global Codex skill + guidance + native hooks bd setup copilot # Install Copilot CLI plugin + repository instructions bd setup mux --project # Install Mux workspace layer (.mux/AGENTS.md) bd setup mux --global # Install Mux global layer (\~/.mux/AGENTS.md) bd setup mux --project --global # Install both Mux layers bd setup --list # Show all available recipes bd setup --print # Print the template to stdout bd setup -o rules.md # Write template to custom path bd setup --add myeditor .myeditor/rules.md # Add custom recipe Use 'bd setup \ --check' to verify installation status. Use 'bd setup \ --remove' to uninstall. ``` bd setup [recipe] [flags] ``` **Flags:** ``` --add string Add a custom recipe with given name --check Check if integration is installed --global Install globally (claude/codex/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 --project Install for this project only (gemini/mux) --remove Remove the integration --stealth Use stealth mode (claude/gemini) ``` # bd ship Source: https://beads.gascity.com/cli-reference/ship Ship a capability to satisfy cross-project dependencies. Generated from `bd help --doc ship`. Ship a capability to satisfy cross-project dependencies. This command: 1. Finds issue with export:\ label 2. Validates issue is closed (or --force to override) 3. Adds provides:\ label External projects can depend on this capability using: bd dep add \ external:\:\ The capability is resolved when the external project has a closed issue with the provides:\ label. Examples: bd ship mol-run-assignee # Ship the mol-run-assignee capability bd ship mol-run-assignee --force # Ship even if issue is not closed bd ship mol-run-assignee --dry-run # Preview without making changes ``` bd ship [flags] ``` **Flags:** ``` --dry-run Preview without making changes --force Ship even if issue is not closed ``` # bd show Source: https://beads.gascity.com/cli-reference/show Show issue details Generated from `bd help --doc show`. Show issue details ``` bd show [id...] [--id=...] [--current] [flags] ``` **Aliases:** view **Flags:** ``` --as-of string Show issue as it existed at a specific commit hash or branch (requires Dolt) --children Show only the children of this issue --current Show the currently active issue (in-progress, hooked, or last touched) --id stringArray Issue ID (use for IDs that look like flags, e.g., --id=gt--xyz) --include-comments Stream full comment bodies in JSON output (--json only; may be slow on issues with many comments) --include-dependents Stream full dependent issues in JSON output (--json only; may be slow on hub beads) --local-time Show timestamps in local time instead of UTC --long Show all available fields (extended metadata, agent identity, gate fields, etc.) --refs Show issues that reference this issue (reverse lookup) --short Show compact one-line output per issue --thread Show full conversation thread (for messages) -w, --watch Watch for changes and auto-refresh display ``` # bd sql Source: https://beads.gascity.com/cli-reference/sql Execute a raw SQL query against the underlying database (SQLite or Dolt). Generated from `bd help --doc sql`. Execute a raw SQL query against the underlying database (SQLite or Dolt). Useful for debugging, maintenance, and working around bugs in higher-level commands. Examples: bd sql 'SELECT COUNT(\*) FROM issues' bd sql 'SELECT id, title FROM issues WHERE status = "open" LIMIT 5' bd sql 'DELETE FROM dirty\_issues WHERE issue\_id = "bd-abc123"' bd sql --csv 'SELECT id, title, status FROM issues' The query is passed directly to the database. SELECT queries return results as a table (or JSON/CSV with --json/--csv). Non-SELECT queries (INSERT, UPDATE, DELETE) report the number of rows affected. WARNING: Direct database access bypasses the storage layer. Use with caution. ``` bd sql [flags] ``` **Flags:** ``` --csv Output results in CSV format ``` # bd stale Source: https://beads.gascity.com/cli-reference/stale Show issues that haven't been updated recently and may need attention. Generated from `bd help --doc stale`. Show issues that haven't been updated recently and may need attention. This helps identify: * In-progress issues with no recent activity (may be abandoned) * Open issues that have been forgotten * Issues that might be outdated or no longer relevant ``` bd stale [flags] ``` **Flags:** ``` -d, --days int Issues not updated in this many days (default 30) -n, --limit int Maximum issues to show (default 50) -s, --status string Filter by status (open|in_progress|blocked|deferred) ``` # bd state Source: https://beads.gascity.com/cli-reference/state Query the current value of a state dimension from an issue's labels. Generated from `bd help --doc state`. Query the current value of a state dimension from an issue's labels. State labels follow the convention \:\, for example: patrol:active mode:degraded health:healthy This command extracts the value for a given dimension. Examples: bd state witness-abc patrol # Output: active bd state witness-abc mode # Output: normal bd state witness-abc health # Output: healthy ``` bd state [flags] ``` ## bd state list List all state labels (dimension:value format) on an issue. This filters labels to only show those following the state convention. Example: bd state list witness-abc # Output: # patrol: active # mode: normal # health: healthy ``` bd state list [flags] ``` # bd status Source: https://beads.gascity.com/cli-reference/status Show a quick snapshot of the issue database state and statistics. Generated from `bd help --doc status`. Show a quick snapshot of the issue database state and statistics. This command provides a summary of issue counts by state (open, in\_progress, blocked, closed), ready work, extended statistics (pinned issues, average lead time), and recent activity over the last 24 hours from git history. Similar to how 'git status' shows working tree state, 'bd status' gives you a quick overview of your issue database without needing multiple queries. Use cases: * Quick project health check * Onboarding for new contributors * Integration with shell prompts or CI/CD * Daily standup reference Examples: bd status # Show summary with activity bd status --no-activity # Skip git activity (faster) bd status --json # JSON format output bd status --assigned # Show issues assigned to current user bd stats # Alias for bd status ``` bd status [flags] ``` **Aliases:** stats **Flags:** ``` --all Show all issues (default behavior) --assigned Show issues assigned to current user --no-activity Skip git activity tracking (faster) ``` # bd statuses Source: https://beads.gascity.com/cli-reference/statuses List all valid issue statuses and their categories. Generated from `bd help --doc statuses`. List all valid issue statuses and their categories. Built-in statuses (open, in\_progress, blocked, etc.) are always valid. Additional statuses can be configured via status.custom: bd config set status.custom "in\_review:active,qa\_testing:wip,on\_hold:frozen" Categories control behavior: active — appears in 'bd ready' and default 'bd list' wip — excluded from 'bd ready', visible in default 'bd list' done — excluded from 'bd ready' and default 'bd list' frozen — excluded from 'bd ready' and default 'bd list' Statuses without a category (legacy format) are valid but excluded from 'bd ready'. Examples: bd statuses # List all statuses with icons and categories bd statuses --json # Output as JSON ``` bd statuses [flags] ``` # bd supersede Source: https://beads.gascity.com/cli-reference/supersede Mark an issue as superseded by a newer version. Generated from `bd help --doc supersede`. Mark an issue as superseded by a newer version. The superseded issue is automatically closed with a reference to the replacement. Useful for design docs, specs, and evolving artifacts. Examples: bd supersede bd-old --with bd-new # Mark bd-old as superseded by bd-new ``` bd supersede --with [flags] ``` **Flags:** ``` --with string Replacement issue ID (required) ``` # bd swarm Source: https://beads.gascity.com/cli-reference/swarm Swarm management commands for coordinating parallel work on epics. Generated from `bd help --doc swarm`. Swarm management commands for coordinating parallel work on epics. 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 [flags] ``` ## bd swarm create Create a swarm molecule to orchestrate parallel work on an epic. The swarm molecule: * Links to the epic it orchestrates * Has mol\_type=swarm for discovery * Specifies a coordinator (optional) * Can be picked up by any coordinator agent If given a single issue (not an epic), it will be auto-wrapped: * Creates an epic with that issue as its only child * Then creates the swarm molecule for that epic Examples: bd swarm create bd-epic-123 # Create swarm for epic bd swarm create bd-epic-123 --coordinator=observer/ # With specific coordinator bd swarm create bd-task-456 # Auto-wrap single issue ``` bd swarm create [epic-id] [flags] ``` **Flags:** ``` --coordinator string Coordinator address (e.g., my-project/witness) --force Create new swarm even if one already exists ``` ## bd swarm list List all swarm molecules with their status. Shows each swarm molecule with: * Progress (completed/total issues) * Active workers * Epic ID and title Examples: bd swarm list # List all swarms bd swarm list --json # Machine-readable output ``` bd swarm list [flags] ``` ## bd swarm status Show the current status of a swarm, computed from beads. Accepts either: * An epic ID (shows status for that epic's children) * A swarm molecule ID (follows the link to find the epic) Displays issues grouped by state: * Completed: Closed issues * Active: Issues currently in\_progress (with assignee) * Ready: Open issues with all dependencies satisfied * Blocked: Open issues waiting on dependencies The status is COMPUTED from beads, not stored separately. If beads changes, status changes. Examples: bd swarm status gt-epic-123 # Show swarm status by epic bd swarm status gt-swarm-456 # Show status via swarm molecule bd swarm status gt-epic-123 --json # Machine-readable output ``` bd swarm status [epic-or-swarm-id] [flags] ``` ## bd swarm validate Validate an epic's structure to ensure it's ready for swarm execution. Checks for: * Correct dependency direction (requirement-based, not temporal) * Orphaned issues (roots with no dependents) * Missing dependencies (leaves that should depend on something) * Cycles (impossible to resolve) * Disconnected subgraphs Reports: * Ready fronts (waves of parallel work) * Estimated worker-sessions * Maximum parallelism * Warnings for potential issues Examples: bd swarm validate gt-epic-123 # Validate epic structure bd swarm validate gt-epic-123 --verbose # Include detailed issue graph ``` bd swarm validate [epic-id] [flags] ``` **Flags:** ``` --verbose Include detailed issue graph in output ``` # bd tag Source: https://beads.gascity.com/cli-reference/tag Add a label to an issue. Generated from `bd help --doc tag`. Add a label to an issue. Shorthand for 'bd update \ --add-label \