beads/website/docs/cli-reference
Eddie the Engineer 05b29caf55 fix(metrics): maintainer adoption fixes for usage-metrics + RunE refactor
Maintainer fixups for PR #4419 folded into one commit on top of the
contributor branch.

Security (blocker): metrics consent and endpoint are resolved from the
user-global config only (config.MetricsDisabledByUserConfig /
UserMetricsEndpoint). A project/BEADS_DIR config — highest viper precedence —
can no longer re-enable metrics or redirect the endpoint for a user who ran
`bd metrics off`.

First-run notice (major): the consent notice runs after the config-derived
json/quiet rebind and command classification, and is suppressed in
JSON/quiet/hook-json, BD_GIT_HOOK, hook/codex-hook/completion/shell-init/
version/prime, the metrics command, `init --stealth`, and the root
`bd --version` / `bd -V` probe, so it can never corrupt machine-readable or
hook/protocol output.

One cli_command event per invocation (major): delegating commands no longer
double-count. `bd ready --gated` and `bd mol wisp <proto>` record only their
own event by delegating to non-emitting cores (runMolReadyGatedCore /
runWispCreateCore), matching the existing runTodoListCore/runListCore pattern;
cardinality regression tests cover both aliases.

config get/show honor user-global metrics state (major): `bd config get
metrics.*` and `bd config show` report the user-global value (via
config.GetUserYamlConfig) that actually governs runtime behavior, with the
user-global path as the location, instead of a project value that has no
runtime effect.

Metrics cleanup on os.Exit paths (major): CheckReadonly and the reachable
pre-run gates (no-DB, fresh-clone, schema-skew, remote-migrate-gate, identity
mismatch) call the shared metrics.CloseAndFlush before exiting, so events
queued earlier in the run are still written and scheduled for upload instead
of stranded until the next clean exit. main()'s post-command tail uses the
same helper. `bd q` now creates its event before the readonly guard and labels
the readonly operation "q".

Telemetry coverage (major): recompute-blocked converted to RunE + HandleError
and emits a cli_command event; `metrics on/off/example` and `version` emit
cli_command events.

Consistency / minor cleanups: added SilenceUsage/SilenceErrors to the
ADO/GitHub/GitLab/Notion push/pull commands to match the jira/linear siblings
in the same file; corrected the inverted env-override "saved config" status
text; preserved 0600 when unsetting user-global config keys.

Pre-review CI repair (earlier in this commit): lint, stealth-init
cleanliness, proxied-server error handling, and regenerated CLI docs.

Tests: user-global opt-out vs project override at the config readers, runtime
resolvers, and `config get`; first-run notice suppression across
hook/protocol/json/quiet/stealth/root-version contexts; event cardinality for
the todo/ready-gated/wisp aliases; and CloseAndFlush persistence.

Original contributor commits preserved.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-22 20:44:48 +00:00
..
admin.md fix(compact): stop advertising the unimplemented Tier 2 compaction (#4465) 2026-06-20 15:29:28 -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 fix(metrics): maintainer adoption fixes for usage-metrics + RunE refactor 2026-06-22 20:44:48 +00: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(list): warn that repeated -s/--status silently overwrites (#3916) (#3917) 2026-06-22 13:18:44 -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
metrics.md fix(metrics): maintainer adoption fixes for usage-metrics + RunE refactor 2026-06-22 20:44:48 +00: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: regenerate CLI reference for bd ready --offset 2026-06-18 13:55:12 -07:00
recall.md docs: generate CLI reference from live help (#3704) 2026-05-05 19:43:49 -07:00
recompute-blocked.md fix(is_blocked): cross-mode full recompute repair for stale is_blocked (bd-6dnrw.37) (#4423) 2026-06-19 23:14:09 -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 fix(compact): archive content before destructive compaction; make restore work (#4464) 2026-06-20 14:12:07 -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