* feat(init): add --init-if-missing for idempotent init (#3490) bd init aborts with exit 1 when the workspace is already initialized, forcing scaffold scripts to pre-stat .beads/embeddeddolt/<prefix> to tell "already initialized" (benign) apart from real errors. Add an opt-in --init-if-missing flag: when the workspace already exists, init prints a benign "Skipping init: workspace already initialized." to stderr and exits 0. Default behavior (flag absent) is unchanged - exit 1 with the existing "already initialized ... Aborting" message. The flag is intercepted only at the existing checkExistingBeadsData guard call site; detection logic and the --force/--reinit-local paths are untouched. Docs regenerated via scripts/generate-cli-docs.sh and generate-llms-full.sh. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(init): abort --init-if-missing on explicit prefix mismatch --init-if-missing silently skipped whenever a workspace already existed, even if the caller passed an explicit --prefix that differed from the existing workspace. That masked a real mismatch: `bd init --prefix bar --init-if-missing` against an existing `foo` workspace exited 0 and ignored the requested prefix. Now, when --prefix is set explicitly (and --database is not), compare the requested prefix against the existing workspace's recorded DoltDatabase and abort on a genuine mismatch; matching or undeterminable cases still skip benignly. Extracts the prefix->dbName normalization into shared helpers so the guard derives exactly the same name init records, and factors the decision into a pure, unit-tested helper. Refs #3490 Co-authored-by: Cursor <cursoragent@cursor.com> * fix(init): don't mask operational errors or --database mismatch under --init-if-missing Two idempotent-init correctness fixes on top of #4332 (reviewer Bernoulli): 1. checkExistingBeadsData now distinguishes the benign "already initialized" outcome (errWorkspaceAlreadyInitialized, carried by a workspaceExistsError that keeps the user-facing message) from operational errors such as an unreadable .beads/embeddeddolt directory. --init-if-missing skips only the benign case; an operational error still aborts instead of being masked as a successful idempotent skip. 2. An explicit --database mismatch now aborts --init-if-missing, mirroring the existing --prefix guard. --database is the authoritative database selector, so it is checked even when --prefix is also set. Tests: initIfMissingDatabaseMismatch table; checkExistingBeadsDataAt returns a sentinel-matching error for an existing database and a non-matching (operational) error when embeddeddolt is unreadable. Agent-Signature: claude-opus-4-8-high on behalf of maphew --------- Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: matt wilkie <maphew@gmail.com>
96 lines
8.5 KiB
Markdown
96 lines
8.5 KiB
Markdown
---
|
|
id: init
|
|
title: bd init
|
|
slug: /cli-reference/init
|
|
sidebar_position: 400
|
|
---
|
|
|
|
<!-- AUTO-GENERATED: do not edit manually -->
|
|
Generated from `bd help --doc init`
|
|
|
|
## bd 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 <claude|cursor|aider|...> --stealth
|
|
|
|
By default, beads uses an embedded Dolt engine (no external server needed).
|
|
Pass --server to use an external dolt sql-server instead. In server mode,
|
|
set connection details with --server-host, --server-port, and --server-user.
|
|
Password should be set via BEADS_DOLT_PASSWORD environment variable.
|
|
|
|
Auto-export is optional. When enabled, bd exports issues to
|
|
.beads/issues.jsonl after write commands (throttled to once per 60s). This is
|
|
for viewers (bv), interchange, and issue-level migration; not backup.
|
|
Cross-machine sync and backups use Dolt remotes/backups, not JSONL import/export.
|
|
To enable: bd config set export.auto true
|
|
|
|
Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
|
|
Skips all interactive prompts, using sensible defaults:
|
|
• Role defaults to "maintainer" (override with --role)
|
|
• Fork exclude auto-configured when fork detected
|
|
• Auto-export left at default (disabled)
|
|
• --contributor and --team flags are rejected (wizards require interaction)
|
|
Also auto-detected when stdin is not a terminal or CI=true is set.
|
|
|
|
```
|
|
bd init [flags]
|
|
```
|
|
|
|
**Flags:**
|
|
|
|
```
|
|
--agents-file string Custom filename for agent instructions (default: AGENTS.md)
|
|
--agents-profile string AGENTS.md profile: 'minimal' (default, pointer to bd prime) or 'full' (complete command reference)
|
|
--agents-template string Path to custom AGENTS.md template (overrides embedded default)
|
|
--backend string Storage backend (default: dolt). --backend=sqlite prints deprecation notice.
|
|
--contributor Run OSS contributor setup wizard
|
|
--database string Use existing server database name (overrides prefix-based naming)
|
|
--debug Run the managed Dolt sql-server with --loglevel=debug and CPU profiling (--prof cpu). Persisted to config.yaml as dolt.debug. No effect on externally-managed servers.
|
|
--destroy-token string Explicit confirmation token for destructive re-init in non-interactive mode (format: 'DESTROY-<prefix>')
|
|
--discard-remote Authorize discarding the configured remote's Dolt history when re-initializing. Requires --destroy-token in non-interactive mode; see 'bd help init-safety'.
|
|
--external Server is externally managed (skip server startup); use with --shared-server or --server
|
|
--force Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence (see 'bd help init-safety').
|
|
--from-jsonl Import issues from configured import.path instead of git history
|
|
--init-if-missing If the workspace is already initialized, skip init and exit 0 instead of failing (idempotent init for scaffolds)
|
|
--non-interactive Skip all interactive prompts (auto-detected in CI or non-TTY environments)
|
|
-p, --prefix string Issue prefix (default: current directory name)
|
|
--proxied-server [EXPERIMENTAL] Use a per-workspace proxied dolt sql-server (proxy + child dolt) rooted at .beads/proxieddb
|
|
--proxied-server-config-path string [EXPERIMENTAL] Absolute path to an existing dolt sql-server YAML config (proxied-server mode only). When set, bd uses this file instead of auto-generating one. Relative paths are rejected.
|
|
--proxied-server-external-host string [EXPERIMENTAL] Hostname or IP of an externally-managed dolt sql-server the proxy should front (proxied-server mode only). Mutually exclusive with --proxied-server-external-socket-path.
|
|
--proxied-server-external-keep-alive duration [EXPERIMENTAL] TCP keepalive period for the proxy→external connection. Zero uses the package default (30s).
|
|
--proxied-server-external-port int [EXPERIMENTAL] TCP port of the externally-managed dolt sql-server (proxied-server mode only). Required when --proxied-server-external-host is set.
|
|
--proxied-server-external-socket-path string [EXPERIMENTAL] Absolute unix socket path of the externally-managed dolt sql-server (proxied-server mode only). Mutually exclusive with --proxied-server-external-host. Relative paths are rejected.
|
|
--proxied-server-external-tls [EXPERIMENTAL] Require TLS when connecting to the externally-managed dolt sql-server (proxied-server mode only).
|
|
--proxied-server-external-tls-cert-path string [EXPERIMENTAL] Absolute path to a client TLS certificate (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-key-path. Relative paths are rejected.
|
|
--proxied-server-external-tls-key-path string [EXPERIMENTAL] Absolute path to the client TLS private key (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-cert-path. Relative paths are rejected.
|
|
--proxied-server-external-user string [EXPERIMENTAL] MySQL user for the externally-managed dolt sql-server (proxied-server mode only). Defaults to "root" when empty. Password is read at runtime from $BEADS_PROXIED_SERVER_EXTERNAL_PASSWORD and is never persisted to disk.
|
|
--proxied-server-log-path string [EXPERIMENTAL] Absolute path to the proxied dolt sql-server log file (proxied-server mode only). Default: <beadsDir>/proxieddb/server.log. Relative paths are rejected.
|
|
--proxied-server-root-path string [EXPERIMENTAL] Absolute directory holding the proxied dolt sql-server's lockfiles, pidfiles, and child .dolt repository (proxied-server mode only). Default: <beadsDir>/proxieddb. May not exist yet — bd will create it. Relative paths are rejected.
|
|
-q, --quiet Suppress output (quiet mode)
|
|
--reinit-local Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence; see --discard-remote.
|
|
--remote string Dolt remote URL to clone from and persist as sync.remote
|
|
--role string Set beads role without prompting: "maintainer" or "contributor"
|
|
--server Use external dolt sql-server instead of embedded engine
|
|
--server-host string Dolt server host (default: 127.0.0.1)
|
|
--server-port int Dolt server port (default: 3307)
|
|
--server-socket string Unix domain socket path (overrides host/port)
|
|
--server-user string Dolt server MySQL user (default: root)
|
|
--setup-exclude Configure .git/info/exclude to keep beads files local (for forks)
|
|
--shared-server Enable shared Dolt server mode (all projects share one server at ~/.beads/shared-server/)
|
|
--skip-agents Skip AGENTS.md and Claude/Codex setup generation
|
|
--skip-hooks Skip git hooks installation
|
|
--stealth Enable stealth mode: global gitattributes and gitignore, no local repo tracking
|
|
--team Run team workflow setup wizard
|
|
```
|