beads/website/docs/cli-reference/init.md
Kevin Glynn d585928bb3
feat(init): add --init-if-missing for idempotent init (#3490) (#4332)
* 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>
2026-06-18 09:51:27 -07:00

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 &lt;claude|cursor|aider|...&gt; --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
```