beads/website/docs/cli-reference
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
..
admin.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
ado.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
assign.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
audit.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
backup.md docs: clarify export versus database backup (#4048) 2026-05-20 16:19:23 -07:00
batch.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
blocked.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
bootstrap.md fix(init): use git origin as default Dolt remote (#3909) 2026-05-13 07:02:39 -07:00
branch.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
children.md fix(cli): implement children pretty and defer reason 2026-06-13 21:22:38 -07:00
close.md fix(close): support per-id reasons (#4194) 2026-05-27 20:41:07 -07:00
comment.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
comments.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
compact.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
completion.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
config.md fix(init): honor dolt local-only remote wiring (#4227) 2026-05-28 15:41:38 -07:00
context.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
cook.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
count.md feat(count): add --include-infra for exact bd list cardinality parity (#4389) 2026-06-13 04:14:28 -07:00
create-form.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
create.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
defer.md fix(cli): implement children pretty and defer reason 2026-06-13 21:22:38 -07:00
delete.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
dep.md feat(count): add --include-infra for exact bd list cardinality parity (#4389) 2026-06-13 04:14:28 -07:00
diff.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
doctor.md fix(init): use git origin as default Dolt remote (#3909) 2026-05-13 07:02:39 -07:00
dolt.md fix(remote): remove cli invocations of 'dolt remote' and exclusively use store method and sql (#4236) 2026-06-05 13:58:21 -07:00
duplicate.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
duplicates.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
edit.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
epic.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
export.md docs: clarify export versus database backup (#4048) 2026-05-20 16:19:23 -07:00
federation.md /{docs,website,scripts}: holy fuck again 2026-06-03 15:16:55 -07:00
find-duplicates.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
flatten.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
forget.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
formula.md docs: neutralize formula workflow terminology (#3900) 2026-05-13 06:52:11 -07:00
gate.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
gc.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
github.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
gitlab.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
graph.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
history.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
hooks.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
human.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
import.md feat(count): add --include-infra for exact bd list cardinality parity (#4389) 2026-06-13 04:14:28 -07:00
index.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
info.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
init-safety.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
init.md feat(init): add --init-if-missing for idempotent init (#3490) (#4332) 2026-06-18 09:51:27 -07:00
jira.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
kv.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
label.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
linear.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
link.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
lint.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
list.md /{docs,website}: gen docs 2026-06-03 14:30:53 -07:00
mail.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
memories.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
merge-slot.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
migrate.md /{cmd,docs,website}: gen docs again 2026-05-26 10:13:11 -07:00
mol.md docs: neutralize formula workflow terminology (#3900) 2026-05-13 06:52:11 -07:00
note.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
notion.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
onboard.md init: run Codex project setup by default 2026-05-26 13:03:37 -07:00
orphans.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
ping.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
preflight.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
prime.md fix(setup): finish hook JSON migration 2026-05-08 09:21:39 -07:00
priority.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
promote.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
prune.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
purge.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
q.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
query.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
quickstart.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
ready.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
recall.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
remember.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
rename-prefix.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
rename.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
reopen.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
repo.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
restore.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
rules.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
search.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
set-state.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
setup.md init: run Codex project setup by default 2026-05-26 13:03:37 -07:00
ship.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
show.md feat(show): count-only JSON details with opt-in streamed payloads 2026-05-22 16:54:15 -07:00
sql.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
stale.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
state.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
status.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
statuses.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
supersede.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
swarm.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
tag.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
todo.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
types.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
undefer.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
update.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
upgrade.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
vc.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
version.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
where.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
worktree.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00