* test(feat): red — Add soft watchdog warning for long-running schema migrations (refs be-yyzzs) * feat: green — Add soft watchdog warning for long-running schema migrations (refs be-yyzzs) * fix(schema): address review follow-ups on migration watchdog doc citation (refs be-yyzzs, review be-sogif) Round 1 review (be-sogif) flagged criterion 7: the soft-watchdog comment at schema.go cited engdocs/plans/be-m65rs-migration-watchdog-scoping.md, which was never landed to any reachable ref (only exists on PM's own unmerged worktree branch). Replace the dangling file citation with an inline summary of the rationale plus reachable citations: the existing initSchema comment in store.go (migration 0047 as a concrete long-runner example) and `bd show be-m65rs` for the full scoping decision. Comment-only change; no functional/behavioral diff. gofmt/build/vet clean; full package suite reconfirmed 132 PASS, 0 FAIL, 0 SKIP. * test(schema): red — watchdog is silent off a tty, and ignores bare seconds Both from review #5997. TestRunMigrationsWatchdogSurvivesNonTTY drives runMigrations end to end with a deliberately slow first migration body and a 10ms interval, with the progress writer put in the state a non-tty caller really sees. It fails with an empty buffer: runMigrations hands the watchdog the package stderr var, which is io.Discard whenever os.Stderr is not a terminal, so the warning is discarded under bd serve, systemd, CI and any piped invocation — the exact cases where a migration running for twenty minutes needs to be visible. On a tty it works, which is why this went unnoticed. Asserting on the wiring rather than on a package variable, so the fix has to actually reach the call site. The interval table gains bare-seconds cases. store.go's parseTimeout — the convention migrationWatchdogIntervalDuration's own doc comment claims to follow — documents "bare numbers treated as seconds (e.g. \"90\")", and this one does not, so an operator setting the value to 90 silently gets 5m. Note the review's own example value, 300, cannot serve as the test input: 300s IS the 5m default, so it passes whether the value was parsed or discarded. Using 90 and 600 instead, which distinguish. watchdogStderr exists here but is not yet wired, so the red is behavioural rather than a compile error. Refs be-lotba. * fix(schema): point the watchdog's last dangling citation at bd show be-m65rs Review #5997 point 1. Round 2 replaced the citation on the call-site comment but missed the one in runMigrationWithWatchdog's own doc comment, which still named engdocs/plans/be-m65rs-migration-watchdog-scoping.md. That path does not exist, and neither does engdocs/plans/ — so the comment sent a reader after a file that was never committed. Points it at bd show be-m65rs, matching what the call site already says. This was the last engdocs/plans reference in the repo; a repo-wide grep for that prefix is now empty, so the two comments can no longer disagree. Refs be-lotba. * fix(schema): send the migration watchdog WARN somewhere a non-tty caller sees Review #5997 point 2. The package's stderr var is io.Discard whenever os.Stderr is not a terminal (schema.go:26-37) — it was introduced for routine per-migration progress lines, where discarding off a tty is correct. Wiring the watchdog to it inherited that gating, so the WARN was emitted only on an interactive terminal and silently dropped under bd serve, systemd, CI and any piped invocation: precisely the situations where a migration still running after twenty minutes is worth knowing about. On a tty it worked, which is why it was not caught earlier. Routes the watchdog through its own writer instead. This is not a new convention for the package — remote_migrate_gate.go, smart_remote_migrate _gate.go and both schema-skew notices in this file already write operator warnings straight to os.Stderr, ungated, for the same reason. stderr keeps its terminal gating and its progress lines. Chose the writer over the alternative the review offered (scoping the doc comment to "interactive runs"), since the feature's stated purpose in be-m65rs is telling an operator reading logs that a migration is still working — and logs are the non-tty case. Turns TestRunMigrationsWatchdogSurvivesNonTTY green; it asserts through runMigrations rather than on the package var, so the wiring at the call site is what is under test. Refs be-lotba. * fix(schema): accept a bare-seconds watchdog interval, matching parseTimeout Review #5997 nit. BEADS_MIGRATION_WATCHDOG_INTERVAL=300 fell back to the 5m default instead of meaning 300s, so an operator changing the value got the number they were trying to change and no diagnostic. The doc comment claimed to follow internal/storage/dolt/store.go's timeoutFromEnv, but only its unset/invalid-falls-back shape. timeoutFromEnv is a one-line wrapper; the contract lives in parseTimeout below it, which retries an unparsable value as raw+"s" so bare numbers mean seconds. This function skipped that half, so the comment promised a convention the code did not implement. Now mirrors parseTimeout's full shape — including its non-positive handling on both branches — and cites parseTimeout by name, since that is where the behavior being mirrored actually is. On the review's related note that d > 0 is the only floor: that is deliberate and is also parseTimeout's only floor. Diverging here would make the two disagree again, which is what produced this nit. Happy to add a minimum on both together if you want one. Not reused directly because parseTimeout is unexported in another package. The interval table gains bare-seconds cases; 90 and 600 rather than the review's 300, since 300s is the 5m default and so cannot distinguish "parsed as seconds" from "fell back". Refs be-lotba. * docs(changelog): add the migration watchdog to Unreleased Review #5997 nit: a new user-facing env var and a new WARN line earn an Deliberately CHANGELOG only, not docs/reference/configuration.md — even though BEADS_FSCK_TIMEOUT, the sibling this env var's parsing mirrors, has a row in that page's table. docs/ describes the pinned release (docs/cli-docs.pin is v1.2.2, which does not contain this feature) rather than main, per engdocs/decisions/2026-07-17-docs-release-pin.md. The table row belongs with the pin bump at release time; adding it now would document a flag no released bd accepts. Refs be-lotba. * fix(bazel): list migration_watchdog_test.go in the schema go_test srcs Base added internal/storage/schema/BUILD.bazel after this PR's merge base, enumerating go_test srcs file by file. The PR's new migration_watchdog_test.go was therefore absent from it, so under Bazel the target reported "Executed 1 out of 1 test: 1 test passes" while running NONE of the new tests ("testing: warning: no tests to run") -- a silent green. Measured both ways on the adopted head: without this entry 0 watchdog tests run; with it, all 7 tests and 8 subtests execute and pass (bazel test //internal/storage/schema:schema_test). The enumeration is maintained at 100% repo-wide -- all 56 unlisted test files are //go:build-tagged -- so this file would have been the only untagged omission. Maintainer fixup applied during PR adoption's rebase gate. No contributor code changed; the contributor could not have seen this file, which did not exist at the merge base. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(schema): scope the watchdog promise to the migration body, stop the warner on panic Maintainer fixup applied during PR adoption's review loop (iteration 1), addressing the one major plus the three non-gating findings in the review synthesis. No contributor commit was rewritten. Major -- Change Impact / Blast Radius (scope). The watchdog wraps only execMigrationBody, while a migration step also runs the dirty-table snapshot, preMigrationRepair, the cursor INSERT and commitMigrationStep -- and this file already says the per-step DOLT_ADD/DOLT_COMMIT is "the expensive, fallible part of this step on the production embedded path". The CHANGELOG therefore over-promised: it told users a wedged migration no longer "looked identical from outside", which is false for a wedge in that commit. The synthesis offered two arms and said explicitly not to do both. Taking the minimal-sufficient arm: CHANGELOG.md now scopes the guarantee to the migration body and states that a stall in the per-step commit is still quiet, and a comment at the call site records that the narrow boundary is deliberate, and why. The extension arm was declined on cost: widening the wrap means moving the snapshot/commit ordering that carries this loop's atomic-commit contract (#4566, #4690), under a strict-ordered sqlmock expectation set and the cross-package migrateStepFaultHook tests -- more risk than an observability-only change should carry. Measured: this fix leaves runMigrations at gocyclo 16 / gocognit 29, byte-identical to before, whereas nesting the whole step in a closure would have driven the cognitive score well past its current band. Minor -- Resource Lifecycle & Cleanup. close(done)/wg.Wait() moved into a defer. A panic out of fn skipped the straight-line close and orphaned the ticker goroutine, which then went on warning about a migration that was no longer running, for the life of the process, on the deliberately un-gated watchdogStderr. Reachability is open rather than proven (internal/httpapi/server.go:1406 recovers everything but http.ErrAbortHandler and keeps serving), which is the argument for taking the one-keyword fix. Pinned by a new test: against the pre-fix schema.go it reds with "3 WARN lines when the panic unwound, 8 after a further 50ms"; with the defer it passes under -race. Minor -- Test Evidence Quality. TestMigrationWatchdogIntervalDuration's "unset_defaults_to_5m" arm never unset anything, so the ambient environment flowed straight into the call. Two-arm control: with BEADS_MIGRATION_WATCHDOG_INTERVAL=600 exported the old arm reds ("= 10m0s; want 5m0s") and the fixed arm passes, with the subtest confirmed to have actually run rather than being filtered out. Nit -- Contract & Interface Fidelity. BEADS_MIGRATION_WATCHDOG_INTERVAL added to docs/reference/configuration.md's env table, beside the BEADS_FSCK_TIMEOUT row whose duration contract it mirrors. Validation: go test ./internal/storage/schema/ -count=1 green (41s); 8 watchdog tests + 8 subtests PASS, 0 SKIP, 0 FAIL; gofmt clean; go vet clean; git diff --check clean; ./scripts/check-doc-freshness.sh PASSED. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(bazel): list golang.org/x/term in the schema go_test deps migration_watchdog_test.go imports golang.org/x/term directly. Under Bazel it compiled only through embed = [":schema"], but gazelle lists a test file's own imports in the go_test's deps, so `bazel run //:gazelle` rewrites this BUILD file. Since the base now gates PRs on the Bazel lanes, BAZEL_TEST's "BUILD files in sync (gazelle, go_srcs, MODULE.bazel)" step would fail on exactly this one line. This is the line gazelle produces. Measured on the adopted head refreshed onto current main: the whole CI sync step run locally (go_srcs.py --check, bazel run //:gazelle, go_srcs.py, bazel mod tidy) leaves this line as the only drift in the repository. With it, bazel test //internal/storage/schema:schema_test --config=ci passes: 433 test cases, 0 failures, all 16 watchdog cases run (0 skipped), and tools/bazel/check_testcases.py plus equivalence.py report no schema divergence. Maintainer fixup applied during PR adoption's pre-approval CI repair. No contributor code changed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
643 lines
38 KiB
Markdown
643 lines
38 KiB
Markdown
---
|
||
title: Configuration
|
||
description: Complete reference for bd configuration across config.yaml and database-stored settings, with precedence, secrets, auto-commit, backup, and integrations.
|
||
---
|
||
|
||
Complete configuration reference for beads.
|
||
|
||
Last reviewed: 2026-08-28
|
||
|
||
Freshness source: `cmd/bd/main.go`, `cmd/bd/config.go`, and `internal/configfile/`.
|
||
|
||
beads has two complementary configuration systems:
|
||
|
||
1. **Tool-level configuration** (YAML, managed by [Viper](https://github.com/spf13/viper)) — startup flags and tool behavior, stored in `config.yaml` files. These are user preferences: output format, auto-commit behavior, CLI ergonomics.
|
||
2. **Project-level configuration** (managed by `bd config`) — integration credentials, status maps, and project-specific settings, stored in the Dolt database. Some keys are routed to `config.yaml` instead (see [YAML-only keys](#yaml-only-keys-startup-settings) below).
|
||
|
||
The split is deliberate: tool settings are user-specific; project config is team-shared and travels with the database when you run `bd dolt push`. That is also why secrets are refused in the database — see [Security](#security-where-secrets-live).
|
||
|
||
Dolt is the only storage backend. Embedded mode (the default) stores data at `.beads/embeddeddolt/`; server mode (`bd init --server` or `BEADS_DOLT_SERVER_MODE=1`) uses `.beads/dolt/`. See [Dolt architecture](/architecture/dolt).
|
||
|
||
## Configuration Locations
|
||
|
||
`config.yaml` is searched in this order, with later files overriding earlier ones:
|
||
|
||
1. `~/.beads/config.yaml` (legacy user-level, lowest priority)
|
||
2. `~/.config/bd/config.yaml` (user-level; this exact path is checked even on platforms whose native user-config directory differs)
|
||
3. `<repo>/.beads/config.yaml` (project-level, walked up from the current directory)
|
||
4. `$BEADS_DIR/config.yaml` (highest priority, when `BEADS_DIR` points at a different workspace)
|
||
|
||
A `config.local.yaml` next to the project `config.yaml` is also merged in last for machine-specific overrides that should not be committed.
|
||
|
||
## Precedence
|
||
|
||
For Viper-managed (YAML) keys, highest to lowest:
|
||
|
||
1. **Command-line flags** (e.g. `--json`, `--db`, `--actor`)
|
||
2. **Environment variables** (`BD_*`, plus a small set of legacy `BEADS_*` names — see below)
|
||
3. **`config.yaml`** files (in the order listed above)
|
||
4. **Built-in defaults**
|
||
|
||
Project-level keys written via `bd config set` (Jira, Linear, GitHub, status maps, etc.) live in the Dolt database. They are read at command time and have no env var override.
|
||
|
||
When a config.yaml value or environment variable shadows a database key, `bd config list` prints an override warning, and `bd config show` reports the source of every effective key.
|
||
|
||
## Managing Configuration
|
||
|
||
```bash
|
||
# Set a value (auto-routes to config.yaml or the database)
|
||
bd config set jira.url "https://company.atlassian.net"
|
||
bd config set validation.on-create warn # YAML-only key
|
||
|
||
# Set many values in one go (single auto-commit; validates before writing)
|
||
bd config set-many jira.url=https://example.atlassian.net jira.project=PROJ
|
||
|
||
# Get a value
|
||
bd config get jira.url
|
||
bd config get --json jira.url
|
||
# → {"key":"jira.url","value":"https://company.atlassian.net"}
|
||
|
||
# List all database-stored config (with override warnings)
|
||
bd config list
|
||
|
||
# Show all effective config with provenance (env / config.yaml / default / database)
|
||
bd config show
|
||
bd config show --source config.yaml
|
||
bd config show --json
|
||
|
||
# Validate sync-related configuration
|
||
bd config validate
|
||
|
||
# Remove a value
|
||
bd config unset jira.url
|
||
```
|
||
|
||
`bd config set` automatically routes the write to the right location: keys in the YAML namespace (see below) are written to the project `config.yaml`; everything else is written to the Dolt database. `beads.role` is stored in git config.
|
||
|
||
Unrecognized keys produce a warning with a did-you-mean suggestion; use the `custom.*` namespace for user-defined keys.
|
||
|
||
## YAML-only Keys (Startup Settings)
|
||
|
||
These keys must live in `config.yaml`, not the database, because they are read before the database is opened. Writing them with `bd config set` automatically updates `config.yaml`.
|
||
|
||
The full namespaces routed to YAML are:
|
||
|
||
`routing.*`, `sync.*`, `git.*`, `directory.*`, `repos.*`, `external_projects.*`, `validation.*`, `lint.*`, `hierarchy.*`, `ai.*`, `backup.*`, `export.*`, `dolt.*`, `federation.*`, `metrics.*`, `list.*`, `audit.*`, `storage-class.*`
|
||
|
||
`lint.*` holds lint settings: `lint.sections.<type>` is a comma-separated, additive list of sections that `bd lint` additionally requires for issues of that type (built-in required sections still apply; unset means no behavior change).
|
||
|
||
Plus these individual keys:
|
||
|
||
`no-db`, `json`, `db`, `actor`, `identity`, `no-push`, `no-git-ops`, `agent.profile`, `create.require-description`, `import.auto`, `import.path`, `prime.max-memories`, `prime.max-memory-chars`, and the secret keys `github.token`, `gitlab.token`, `jira.api_token`, `ado.pat`, `linear.api_key`, `linear.oauth_client_id`, `linear.oauth_client_secret`, `notion.token`.
|
||
|
||
Any key whose name contains `api_key`, `api-key`, `secret`, `token`, or `password` is treated as a secret: it is refused on git-tracked `config.yaml` files unless you pass `--force-git-tracked`. Prefer exporting the value as an environment variable instead (e.g. `LINEAR_API_KEY`).
|
||
|
||
`bd config unset` on one of these secret keys clears the `config.yaml` entry and also deletes any copy an older bd stored in the database, reporting which of them it removed. Keys reached YAML routing at different points in bd's history, so a workspace configured before the move can still hold the value in a table that `bd dolt push` replicates. The database half is best effort: the command never creates a database to look in, so it is skipped where reaching the row would mean provisioning one — but not for a server-mode or proxied workspace whose database is real and simply not on local disk; a database that refuses the delete is reported as a row that is still stored. Deleting it locally does not unpublish it — rotate a secret that has already been pushed.
|
||
|
||
## Tool-Level Settings (config.yaml)
|
||
|
||
| Setting | Flag | Env Var | Default | Description |
|
||
|---|---|---|---|---|
|
||
| `json` | `--json` | `BD_JSON` | `false` | JSON output for scripting |
|
||
| `db` | `--db` | `BD_DB` | (auto-discover) | Database path |
|
||
| `actor` | `--actor` | `BEADS_ACTOR` | `git config user.name` | Actor name for audit trail (see [Actor identity](#actor-identity-resolution)) |
|
||
| `identity` | `--identity` | `BEADS_IDENTITY` | (git user / hostname) | Sender identity for `bd mail` |
|
||
| `no-db` | `--no-db` | `BD_NO_DAEMON` (related) | `false` | Run without opening the database |
|
||
| `no-push` | `--no-push` | `BD_NO_PUSH` | `false` | Skip pushing to the remote in `bd dolt push` |
|
||
| `no-git-ops` | — | — | `false` | Disable git ops in `bd prime` close protocol |
|
||
| `agent.profile` | — | `BD_AGENT_PROFILE` | `conservative` | Policy profile `bd prime` uses for git/commit authority: `conservative`, `minimal`, `team-maintainer`; invalid values fall back to `conservative` |
|
||
| `prime.max-memories` | `--max-memories` | `BD_PRIME_MAX_MEMORIES` | `0` | Max persistent memories injected by `bd prime` (0 = unlimited) |
|
||
| `prime.max-memory-chars` | `--max-memory-chars` | `BD_PRIME_MAX_MEMORY_CHARS` | `0` | Max total bytes of memory entries injected by `bd prime`, at whole-memory boundaries (0 = unlimited) |
|
||
| `dolt.auto-commit` | `--dolt-auto-commit` | `BD_DOLT_AUTO_COMMIT` | `on` | `off\|on\|batch`: `on` creates a Dolt history commit after each successful write; `batch`/`off` defer it to `bd dolt commit` (see [below](#auto-commit-sql-commits-vs-dolt-commits)) |
|
||
| `dolt.auto-push` | — | `BD_DOLT_AUTO_PUSH` | `false` | Auto-push to Dolt remote after writes (opt-in; see [below](#auto-push)) |
|
||
| `dolt.auto-push-interval` | — | `BD_DOLT_AUTO_PUSH_INTERVAL` | `5m` | Minimum time between auto-pushes |
|
||
| `dolt.auto-push-timeout` | — | `BD_DOLT_AUTO_PUSH_TIMEOUT` | `30s` | Timeout for a single auto-push attempt |
|
||
| `dolt.shared-server` | `--shared-server` | `BEADS_DOLT_SHARED_SERVER` | `false` | Share one Dolt server at `~/.beads/shared-server/` |
|
||
| `dolt.max-conns` | — | `BEADS_DOLT_MAX_CONNS` | `10` | Connection pool size |
|
||
| `git.author` | — | `BD_GIT_AUTHOR` | (none) | Override commit author for beads commits |
|
||
| `git.no-gpg-sign` | — | `BD_GIT_NO_GPG_SIGN` | `false` | Disable GPG signing for beads commits |
|
||
| `create.require-description` | — | `BD_CREATE_REQUIRE_DESCRIPTION` | `false` | Require description on `bd create` |
|
||
| `validation.on-create` | — | `BD_VALIDATION_ON_CREATE` | `none` | Template validation: `none`, `warn`, `error` |
|
||
| `validation.on-close` | — | `BD_VALIDATION_ON_CLOSE` | `none` | Template validation on close |
|
||
| `validation.on-sync` | — | `BD_VALIDATION_ON_SYNC` | `none` | Template validation before sync |
|
||
| `validation.metadata.mode` | — | — | `none` | Metadata schema validation |
|
||
| `hierarchy.max-depth` | — | — | `3` | Max hierarchical ID nesting depth |
|
||
| `backup.enabled` | — | `BD_BACKUP_ENABLED` | `false` | Enable periodic Dolt-native backup to `.beads/backup/` (see [below](#auto-backup)) |
|
||
| `backup.interval` | — | `BD_BACKUP_INTERVAL` | `15m` | Minimum time between auto-backups |
|
||
| `backup.git-push` | — | — | `false` | Auto-push backup repo |
|
||
| `backup.git-repo` | — | `BD_BACKUP_GIT_REPO` | (none) | Backup git repo URL; when set, backups go to a `backup/` directory inside that repo |
|
||
| `audit.enabled` | — | `BD_AUDIT_ENABLED` | `false` | Enable the optional JSONL interaction sidecar at `.beads/interactions.jsonl`, written by `bd audit record` / `bd audit label`. While disabled, `bd init` does not create the file and `bd audit record` / `bd audit label` refuse to write. Issue history is always recorded in the database either way — see `bd history <id> --events` |
|
||
| `export.auto` | — | — | `false` | Refresh `.beads/issues.jsonl` export after every write; not cross-machine sync |
|
||
| `export.path` | — | — | `issues.jsonl` | Output filename relative to `.beads/` |
|
||
| `export.interval` | — | — | `60s` | Minimum time between auto-exports |
|
||
| `export.git-add` | — | — | `false` | Run `git add` on the export file |
|
||
| `import.auto` | — | `BD_IMPORT_AUTO` | `true` | Master switch for automatic JSONL imports: the git-hook fallback used when no Dolt remote is configured, and the empty-database recovery import when `.beads/issues.jsonl` exists but the database is empty. `false` disables all auto-imports; explicit `bd import` always works |
|
||
| `import.path` | — | — | `issues.jsonl` | Input filename relative to `.beads/` for implied JSONL imports (including `bd init --from-jsonl` and empty-DB auto-import); use relative paths for portability |
|
||
| `routing.mode` | — | — | (none) | Multi-repo routing: `auto`, `maintainer`, `contributor`, `explicit` |
|
||
| `routing.default` | — | — | `.` | Default routing target |
|
||
| `routing.maintainer` | — | — | `.` | Maintainer-routed path |
|
||
| `routing.contributor` | — | — | `~/.beads-planning` | Contributor-routed path |
|
||
| `list.limit` | `--limit` / `-n` | `BD_LIST_LIMIT` | `50` | Default limit for `bd list` results |
|
||
| `directory.labels` | — | — | `{}` | Map directory patterns → labels for monorepos |
|
||
| `external_projects` | — | — | `{}` | Map project names → paths for cross-project deps |
|
||
| `federation.remote` | — | `BD_FEDERATION_REMOTE` | (none) | Dolt remote URL (`dolthub://`, `gs://`, `s3://`, `az://`, `file://`) |
|
||
| `federation.sovereignty` | — | `BD_FEDERATION_SOVEREIGNTY` | (none) | Sovereignty tier: `T1`, `T2`, `T3`, `T4` (see [below](#sync-and-federation)) |
|
||
| `federation.allowed-remote-patterns` | — | — | `[]` | Glob patterns restricting allowed remote URLs |
|
||
| `federation.exclude_types` | — | — | `[wisp]` | Issue types excluded from federation push |
|
||
| `sync.require_confirmation_on_mass_delete` | — | — | `false` | Prompt before pushing when a merge deletes most issues |
|
||
| `output.title-length` | — | — | `255` | Title display in feedback (`0` hides); see routing note below |
|
||
| `ai.model` | — | `BD_AI_MODEL` | `claude-haiku-4-5-20251001` | Default AI model |
|
||
| `agents.file` | — | — | `AGENTS.md` | Agents instruction filename; see routing note below |
|
||
|
||
<Warning>
|
||
**JSONL export is opt-in**
|
||
|
||
`export.auto` and `export.git-add` are disabled unless configured explicitly.
|
||
`.beads/issues.jsonl` is an optional export for viewers, interchange, and
|
||
issue-level migration. It is not the canonical source of truth, not
|
||
cross-machine sync, and not a full database backup.
|
||
|
||
Workflows that depend on a fresh, git-staged JSONL file should opt in:
|
||
|
||
```bash
|
||
bd config set export.auto true
|
||
bd config set export.git-add true
|
||
```
|
||
|
||
Use `bd dolt push` / `bd dolt pull` for sync and `bd backup` for restorable
|
||
database backups.
|
||
</Warning>
|
||
|
||
Routing note: `output.title-length` and `agents.file` are functionally tool-level settings, but `bd config set` writes them to the Dolt database. They are typically read from `config.yaml` when set there directly.
|
||
|
||
`bd config show` is the source of truth for what's currently effective on your machine, including provenance.
|
||
|
||
## Dolt History, Backup, and Push
|
||
|
||
Three post-write behaviors run after each successful write command, in this order: auto-commit, auto-backup, auto-push.
|
||
|
||
### Auto-commit: SQL Commits vs Dolt Commits
|
||
|
||
There are two different kinds of "commit":
|
||
|
||
- **SQL transaction commit** — what happens when a `bd` command updates tables successfully (durable in the Dolt *working set*).
|
||
- **Dolt version-control commit** — what records those changes into Dolt *history* (visible in `bd history`, and what push/pull/merge workflows operate on).
|
||
|
||
By default (`dolt.auto-commit: on`), `bd` creates a Dolt history commit after each successful write command, so changes are never left only in the working set. The cost is more Dolt commits over time — one per write command — which is intentional; use `bd compact` to squash old history.
|
||
|
||
Disable for a single command:
|
||
|
||
```bash
|
||
bd --dolt-auto-commit off create "No history commit for this one"
|
||
```
|
||
|
||
Or in `config.yaml`:
|
||
|
||
```yaml
|
||
dolt:
|
||
auto-commit: off
|
||
```
|
||
|
||
`batch` and `off` defer the Dolt history commit instead of skipping the write: the change is
|
||
still durable in the working set, and `bd dolt commit` records the accumulated batch as a single
|
||
Dolt commit. This applies on every storage mode — embedded, direct SQL-server, and
|
||
proxied-server. In proxied-server mode the deferral covers the writes the CLI makes on that
|
||
route, including workspace config and version metadata, and `bd dolt commit` is the only flush
|
||
point there: the SIGTERM/SIGHUP flush of a live batch-mode process needs an open store, which
|
||
proxied mode never has (it does run in embedded and direct SQL-server modes).
|
||
|
||
Two kinds of write stay outside the deferral, in every mode:
|
||
|
||
- **Explicit commit points** — `bd batch` (whose commit message defaults to a synthesized one
|
||
when `-m` is absent, so every batch commits), `bd mol bond`, `bd mol pour`, `bd mol squash`,
|
||
`bd mol wisp create`, and the wisp half of `bd mol burn` — commit what they wrote, with the
|
||
message they were given: the commit is that command's contract rather than auto-commit
|
||
policy. Burning a *persistent* molecule is an ordinary delete, so it honors the policy and
|
||
defers with everything else.
|
||
- **Writes made by a `bd serve` process**, whose HTTP API requests carry their own context
|
||
instead of the CLI's, so a daemon keeps committing per write even while the CLI on the same
|
||
database defers.
|
||
|
||
### Auto-backup
|
||
|
||
Periodic Dolt-native backup to `.beads/backup/` provides a recovery path independent of the live database. Local Dolt commits (via `dolt.auto-commit`) remain the primary safety net; backup is a secondary layer. Unlike `bd export` or `.beads/issues.jsonl`, this is a full database backup: it preserves tables, branches, commit history, and working-set data.
|
||
|
||
```yaml
|
||
backup:
|
||
enabled: true # Enable auto-backup after write commands
|
||
interval: 15m # Minimum time between auto-backups
|
||
```
|
||
|
||
How it works:
|
||
|
||
- After each write command, `bd` compares the Dolt HEAD commit hash against the last backup state.
|
||
- If data changed and the throttle interval has passed, a Dolt-native backup is synced to `.beads/backup/` (or to a `backup/` directory inside `backup.git-repo` when configured).
|
||
- State is tracked in `backup_state.json` inside the backup directory.
|
||
|
||
Manual commands (see [bd backup](/cli-reference/backup)):
|
||
|
||
```bash
|
||
bd backup init <path> # Register a destination (filesystem or DoltHub URL)
|
||
bd backup sync # Push to the configured destination
|
||
bd backup restore [path] # Restore from a backup (--force to overwrite)
|
||
bd backup remove # Unregister the destination
|
||
bd backup status # Show configuration and last sync time
|
||
```
|
||
|
||
### Auto-push
|
||
|
||
By default, `bd` does not push automatically after write commands. Auto-push is explicit opt-in because concurrent pushes to git-protocol Dolt remotes can corrupt or strand remote history when multiple writers race.
|
||
|
||
```yaml
|
||
dolt:
|
||
auto-push: true # Explicit opt-in; safe for single-writer setups
|
||
auto-push-interval: 5m # Minimum time between auto-pushes
|
||
auto-push-timeout: 30s # Bound one push attempt when the remote is unreachable
|
||
```
|
||
|
||
How it works:
|
||
|
||
- After each write command (after auto-commit and auto-backup), `bd` checks whether a push is due.
|
||
- Pushes are debounced: skipped if the last push was less than `dolt.auto-push-interval` ago.
|
||
- Change detection: skipped if the Dolt HEAD commit hasn't changed since the last push.
|
||
- Push failures are warnings only (non-fatal), and failed attempts are throttled too.
|
||
- Last push time and commit are tracked in `.beads/push-state.json`, a per-machine file (not in the database, to avoid merge conflicts across machines).
|
||
|
||
Before pushing, `bd` verifies the local chunk store with `dolt fsck --quiet`, bounded by a 30-second timeout. For large stores, raise it with the runtime-only `BEADS_FSCK_TIMEOUT` environment variable (accepts durations like `2m` or bare seconds like `90`).
|
||
|
||
## Actor Identity Resolution
|
||
|
||
The actor name (used for `created_by` and audit trails) is resolved in this order:
|
||
|
||
1. `--actor` flag (explicit override)
|
||
2. `BEADS_ACTOR` environment variable
|
||
3. `BD_ACTOR` environment variable (deprecated alias)
|
||
4. `git config user.name`
|
||
5. `$USER` environment variable
|
||
6. `"unknown"` (final fallback)
|
||
|
||
For most developers no configuration is needed — issue authorship matches commit authorship automatically. To override, set `BEADS_ACTOR` in your shell profile:
|
||
|
||
```bash
|
||
export BEADS_ACTOR="my-github-handle"
|
||
```
|
||
|
||
## Project-Level Settings (Database)
|
||
|
||
These are written to the Dolt database by `bd config set` and have no env var override. Common namespaces:
|
||
|
||
| Namespace | Purpose |
|
||
|---|---|
|
||
| `jira.*` | Jira integration (URL, project(s), status_map, type_map, custom_fields) |
|
||
| `linear.*` | Linear integration (team_id(s), priority_map, state_map, label_type_map, relation_map) |
|
||
| `github.*` | GitHub integration (org, repo, label_map) |
|
||
| `gitlab.*` | GitLab integration |
|
||
| `ado.*` | Azure DevOps integration (org, project(s), state_map, type_map) |
|
||
| `notion.*` | Notion integration |
|
||
| `custom.*` | User-defined / custom integrations |
|
||
| `<tracker>.last_sync` | Updated automatically after each tracker sync; enables incremental sync |
|
||
| `status.custom` | Custom statuses with optional behavior categories (see [below](#custom-statuses-and-types)) |
|
||
| `types.custom` | Comma-separated list of custom issue types |
|
||
| `types.infra` | Infra types routed to the wisps table instead of the versioned issues table |
|
||
| `compact_tier1_days`, `compact_tier2_days` | Age thresholds in days for `bd admin compact` tier eligibility (defaults `30` and `90`) |
|
||
| `issue_id_mode` | `hash` (default) \| `counter` (see [below](#sequential-counter-ids)) |
|
||
| `min_hash_length`, `max_hash_length` | Adaptive ID bounds (defaults `3` and `8`) |
|
||
| `max_collision_prob` | Hash ID collision tolerance (default `0.25`) |
|
||
| `claim.pools` | Comma-separated pool aliases: placeholder assignees that any actor can take with `bd update <id> --claim` (see [below](#claim-pools)). Unset by default, which turns pool claiming off |
|
||
| `doctor.suppress.*` | Suppress specific `bd doctor` warnings by check slug (warnings only; errors always show) |
|
||
|
||
Issue prefix (`issue_prefix`) is **not** settable via `bd config set` — use `bd init --prefix`, `bd bootstrap`, or `bd rename-prefix`.
|
||
|
||
### Custom Statuses and Types
|
||
|
||
Custom statuses supplement the built-ins (`open`, `in_progress`, `blocked`, `deferred`, `closed`). Each entry is `name` or `name:category`:
|
||
|
||
```bash
|
||
bd config set status.custom "in_review:active,qa_testing:wip,on_hold:frozen,archived:done"
|
||
```
|
||
|
||
The category controls how the status behaves:
|
||
|
||
| Category | In `bd ready` | In default `bd list` |
|
||
|---|---|---|
|
||
| `active` | yes | yes |
|
||
| `wip` | no | yes |
|
||
| `done` | no | no (terminal) |
|
||
| `frozen` | no | no (on hold) |
|
||
| (none) | no | yes (backward compatible) |
|
||
|
||
Custom types extend the built-in issue types:
|
||
|
||
```bash
|
||
bd config set types.custom "agent,molecule,event"
|
||
```
|
||
|
||
Use `bd statuses` and `bd types` to list everything configured.
|
||
|
||
### Sequential Counter IDs
|
||
|
||
By default, beads generates hash-based IDs (e.g. `bd-a3f2`). For projects that prefer short sequential IDs (`bd-1`, `bd-2`, ...), enable counter mode:
|
||
|
||
```bash
|
||
bd config set issue_id_mode counter
|
||
|
||
bd create "First issue" -p 1 # → bd-1
|
||
bd create "Second issue" -p 2 # → bd-2
|
||
```
|
||
|
||
| Value | Behavior |
|
||
|---|---|
|
||
| `hash` | (default) Hash-based IDs, adaptive length, collision-safe |
|
||
| `counter` | Sequential integers per prefix: `bd-1`, `bd-2`, `bd-3`, ... |
|
||
|
||
Counter mode behavior:
|
||
|
||
- Each prefix (`bd`, `plug`, ...) has its own independent counter, so multi-repo or routed setups don't interleave.
|
||
- The counter is stored atomically in the database; concurrent creates within a single Dolt session are safe.
|
||
- On first use (including switching an existing repository to counter mode), the counter seeds itself from the highest existing numeric ID for that prefix, so new IDs don't collide with old ones.
|
||
- An explicit `--id` flag on `bd create` bypasses ID generation entirely; the counter is not incremented.
|
||
- Counter mode applies only to regular issues, not wisps.
|
||
|
||
Tradeoff — hash vs. counter:
|
||
|
||
| | Hash IDs | Counter IDs |
|
||
|---|---|---|
|
||
| Human readability | Lower (`bd-a3f2`) | Higher (`bd-1`) |
|
||
| Distributed/concurrent safety | Excellent (collision-free across branches) | Needs care (counters can diverge on parallel branches) |
|
||
| Predictability | Unpredictable | Sequential |
|
||
| Best for | Multi-agent, multi-branch workflows | Single-writer or project-management UIs |
|
||
|
||
### Adaptive Hash IDs
|
||
|
||
Hash IDs size themselves to the database: lengths start at `min_hash_length` and grow toward `max_hash_length` to keep the collision probability under `max_collision_prob`.
|
||
|
||
```bash
|
||
bd config set max_collision_prob "0.01" # Stricter collision tolerance (default 0.25)
|
||
bd config set min_hash_length "5" # Force minimum 5-char IDs (default 3)
|
||
bd config set max_hash_length "8" # Upper bound (default 8)
|
||
```
|
||
|
||
### Claim Pools
|
||
|
||
A dispatcher can pre-assign issues to a pool alias, a placeholder assignee such as `fable-crew`, and let any actor take them with `bd update <id> --claim`. List the aliases in `claim.pools`:
|
||
|
||
```bash
|
||
bd config set claim.pools "fable-crew,night-crew"
|
||
```
|
||
|
||
Claiming reads this key from the database only. A `claim.pools` value in `config.yaml` or in an environment variable has no effect, even though `bd config show` lists a `config.yaml` value with the source `(config.yaml)`. A value that claiming uses shows the source `(database)`.
|
||
|
||
- **Exact match.** The value is split on commas and each entry is trimmed of surrounding whitespace. An issue counts as pool-assigned only when its assignee equals one of the entries exactly, including case: `Crew-A` is not the pool `crew-a`.
|
||
- **Claiming.** Taking a pool-assigned issue works like taking an unassigned one: the claimer becomes the assignee, the status moves to `in_progress`, and the claim gets the normal lease.
|
||
- **Anti-steal.** Issues assigned to a real actor, or to an alias that is not listed, keep their protection: `--claim` refuses them.
|
||
- **Reassigning.** `bd assign` and `bd update <id> --assignee` can move an `in_progress` issue that a pool alias holds without `--force`.
|
||
- **`bd ready --claim`** takes only unassigned issues, so it skips pool-assigned ones even though `bd ready` lists them. Claim those by ID.
|
||
- **Lease expiry.** If the claimer's lease expires, `bd reclaim` sets the issue back to `open` with no assignee. It does not return the issue to the pool alias, so a dispatcher that wants it back in the pool has to reassign it.
|
||
|
||
## Sync and Federation
|
||
|
||
Beads syncs exclusively through Dolt remotes (`bd dolt push` / `bd dolt pull`) with cell-level merge. Use `bd export` for issue portability and `bd backup` for restorable database backups.
|
||
|
||
Federation settings live in `config.yaml`:
|
||
|
||
```yaml
|
||
federation:
|
||
remote: dolthub://myorg/beads
|
||
sovereignty: T2
|
||
```
|
||
|
||
- `federation.remote`: Dolt remote URL (`dolthub://org/beads`, `gs://bucket/beads`, `s3://bucket/beads`, `az://account.blob.core.windows.net/container/beads`, `file://...`)
|
||
- `federation.sovereignty`: data sovereignty tier:
|
||
- `T1`: Full sovereignty — data never leaves controlled infrastructure
|
||
- `T2`: Regional sovereignty — data stays within region/jurisdiction
|
||
- `T3`: Provider sovereignty — data with trusted cloud provider
|
||
- `T4`: No restrictions — data can be anywhere
|
||
|
||
`bd config validate` checks the remote URL format, the sovereignty tier, `federation.allowed-remote-patterns`, and `routing.mode`.
|
||
|
||
## Integration Configuration
|
||
|
||
Tracker settings are project-level config under the tracker's namespace; secrets (`jira.api_token`, `linear.api_key`, `github.token`, `gitlab.token`, `ado.pat`, `notion.token`) are YAML-routed and better supplied as environment variables. Every tracker records `<tracker>.last_sync` automatically after a sync, enabling incremental syncs.
|
||
|
||
### Jira
|
||
|
||
```bash
|
||
bd config set jira.url "https://company.atlassian.net"
|
||
bd config set jira.project "PROJ"
|
||
bd config set jira.projects "PROJ1,PROJ2" # Multiple projects (comma-separated)
|
||
export JIRA_API_TOKEN="YOUR_TOKEN" # or: bd config set jira.api_token ...
|
||
|
||
# Map bd statuses to Jira statuses
|
||
bd config set jira.status_map.open "To Do"
|
||
bd config set jira.status_map.in_progress "In Progress"
|
||
bd config set jira.status_map.closed "Done"
|
||
|
||
# Map bd issue types to Jira issue types
|
||
bd config set jira.type_map.bug "Bug"
|
||
bd config set jira.type_map.feature "Story"
|
||
bd config set jira.type_map.task "Task"
|
||
|
||
# Set Jira custom fields on pushed issues
|
||
bd config set jira.custom_fields.customfield_10042 '{"value":"AI Platform"}'
|
||
bd config set jira.custom_fields.Story.customfield_10042 '{"value":"AI Platform"}'
|
||
```
|
||
|
||
`jira.custom_fields.<field>` applies to every issue pushed to Jira. `jira.custom_fields.<JiraType>.<field>` applies only when the mapped Jira issue type matches `<JiraType>`; per-type fields override global fields with the same field key. Values beginning with `{` or `[` are sent as JSON (useful for select-like fields); other values are sent as strings. `jira.url`, `jira.project`/`jira.projects`, and `jira.api_token` fall back to the `JIRA_URL`, `JIRA_PROJECT`/`JIRA_PROJECTS`, and `JIRA_API_TOKEN` environment variables. See [bd jira](/cli-reference/jira).
|
||
|
||
### Linear
|
||
|
||
```bash
|
||
export LINEAR_API_KEY="lin_api_YOUR_API_KEY" # Settings → API → Personal API keys
|
||
|
||
bd config set linear.team_id "team-uuid-here"
|
||
bd config set linear.team_ids "uuid-1,uuid-2" # Multiple teams (or LINEAR_TEAM_IDS)
|
||
```
|
||
|
||
When `linear.team_ids` is set, `bd linear sync` fetches issues from all listed teams; push with multiple teams configured requires an explicit `--team`. The singular `linear.team_id` remains supported.
|
||
|
||
Mapping namespaces — `linear.priority_map.*` (Linear 0–4 → beads 0–4), `linear.state_map.*` (Linear state types and custom state names → beads statuses, e.g. `bd config set linear.state_map.in_review in_progress`), `linear.label_type_map.*` (Linear labels → bd issue types), and `linear.relation_map.*` (Linear relations → bd dependencies; imported only when pulling with `--relations`) — are documented with defaults in [bd linear](/cli-reference/linear).
|
||
|
||
Staleness detection: after each successful pull, `bd` writes a timestamp to `.beads/last_pull` (a local-only, per-machine file covered by the `.beads/.gitignore` template). `bd linear sync --pull-if-stale` pulls only when data is older than the threshold (`--threshold`, default 20m), and a 5-minute debounce prevents agent loops. `bd prime` and other core commands never contact Linear — run `bd linear sync --pull-if-stale` from a session-start hook to keep data fresh in agent sessions.
|
||
|
||
### GitHub
|
||
|
||
```bash
|
||
bd config set github.org "myorg"
|
||
bd config set github.repo "myrepo"
|
||
export GITHUB_TOKEN="YOUR_TOKEN" # or: bd config set github.token ...
|
||
|
||
# Map bd labels to GitHub labels
|
||
bd config set github.label_map.bug "bug"
|
||
bd config set github.label_map.feature "enhancement"
|
||
```
|
||
|
||
See [bd github](/cli-reference/github).
|
||
|
||
### Azure DevOps
|
||
|
||
Connection keys (`ado.pat`, `ado.org`, `ado.project`, `ado.projects`, `ado.url`) each have an `AZURE_DEVOPS_*` environment variable equivalent; config keys take priority over env vars. When `ado.projects` is set, `bd ado sync` fetches work items from all listed projects in a single query. State maps default to the Agile process template (override with `ado.state_map.*` / `ado.type_map.*` for Scrum or CMMI), and priority mapping (ADO 1–4 ↔ beads 0–4, with backlog collapsing to low) is automatic and not configurable. Full setup, mapping tables, and sync commands: [Azure DevOps integration](/integrations/azure-devops) and [bd ado](/cli-reference/ado).
|
||
|
||
## Environment Variables
|
||
|
||
The Viper env prefix is `BD_`. Config keys map to env vars by upper-casing and replacing `.` and `-` with `_` (e.g. `dolt.auto-commit` → `BD_DOLT_AUTO_COMMIT`, `validation.on-create` → `BD_VALIDATION_ON_CREATE`).
|
||
|
||
Selected commonly-used variables:
|
||
|
||
| Variable | Description |
|
||
|---|---|
|
||
| `BD_DB`, `BEADS_DB` | Database path (legacy `BEADS_DB` still honored) |
|
||
| `BD_JSON` | Force JSON output |
|
||
| `BD_DOLT_AUTO_COMMIT` | Override `dolt.auto-commit` (`on`/`off`) |
|
||
| `BD_DOLT_AUTO_PUSH`, `BD_DOLT_AUTO_PUSH_INTERVAL`, `BD_DOLT_AUTO_PUSH_TIMEOUT` | Override auto-push settings |
|
||
| `BD_BACKUP_ENABLED`, `BD_BACKUP_INTERVAL`, `BD_BACKUP_GIT_REPO` | Override backup settings |
|
||
| `BD_AGENT_PROFILE` | Override `agent.profile` |
|
||
| `BD_AI_MODEL` | Override AI model |
|
||
| `BD_FEDERATION_REMOTE`, `BD_FEDERATION_SOVEREIGNTY` | Override federation settings |
|
||
| `BD_VALIDATION_ON_CREATE` / `_ON_CLOSE` / `_ON_SYNC` | Override validation modes |
|
||
| `BD_NO_PAGER`, `BD_PAGER` | Pager behavior |
|
||
| `BD_NON_INTERACTIVE` | Disable prompts |
|
||
| `BD_DEBUG` | Enable debug logging |
|
||
| `BD_MIGRATION_FREEZE_FILE` | Check this exact path for the freeze marker instead of walking ancestor directories; authoritative when set (see [Migration Freeze](#migration-freeze)) |
|
||
| `BEADS_DIR` | Force the active beads workspace directory |
|
||
| `BEADS_CEILING_DIRECTORIES` | Directories (separated like `PATH`) that `.beads` and `config.yaml` discovery never looks at or above, like git's `GIT_CEILING_DIRECTORIES`; the starting directory is always examined. For sandboxes such as `bazel test` that must not reach the user's own `~/.beads` |
|
||
| `BEADS_ACTOR` | Actor identity (preferred over `BD_ACTOR`, which is a deprecated alias) |
|
||
| `BEADS_IDENTITY` | Sender identity for `bd mail` |
|
||
| `BEADS_FSCK_TIMEOUT` | Runtime-only timeout for the pre-push `dolt fsck --quiet` integrity check (default `30s`) |
|
||
| `BEADS_MIGRATION_WATCHDOG_INTERVAL` | Interval between soft WARN lines while a schema migration's SQL keeps running (default `5m`; accepts durations like `10m` or bare seconds like `90`). Observability only — it never aborts a migration |
|
||
| `BEADS_DOLT_SERVER_MODE`, `BEADS_DOLT_SHARED_SERVER`, `BEADS_DOLT_DATA_DIR`, `BEADS_DOLT_PORT`, ... | Embedded/server Dolt overrides |
|
||
| `BEADS_DOLT_BIN` | Pin the exact external `dolt` CLI binary managed proxied-server mode spawns, overriding PATH lookup (highest precedence; an explicit path that fails validation is an error, not a silent fallback to PATH). On Windows the executable extension may be omitted — `C:\tools\dolt` finds `C:\tools\dolt.exe` via PATHEXT, though a file at the exact spelled path wins if both exist |
|
||
|
||
Integration secrets follow tracker-specific conventions: `LINEAR_API_KEY`, `GITHUB_TOKEN`, `GITLAB_TOKEN`, `JIRA_API_TOKEN`, `AZURE_DEVOPS_PAT`, `ANTHROPIC_API_KEY`. These are preferred over storing the value in `config.yaml` for git-tracked projects.
|
||
|
||
`bd config show` will display the source of every effective key, making overrides explicit.
|
||
|
||
## Migration Freeze
|
||
|
||
Maintenance that runs outside `bd` — moving a database to a new host, rewriting schema by hand — needs a way to stop writes for its duration without uninstalling the tool. Create a file named `MIGRATION-FREEZE` and every write command refuses to run until you delete it.
|
||
|
||
bd looks for the marker in the workspace directory and in the working directory, plus every ancestor of each, so one file above a tree of repositories freezes all of them at once — and targeting a frozen workspace from elsewhere (`BEADS_DIR=…`, `bd -C …`) is refused the same way.
|
||
|
||
Markers found in a world-writable sticky directory such as `/tmp` are ignored: anyone on a shared machine could plant one there, and the sticky bit would stop you removing it. Put the marker at the root of the tree you are freezing.
|
||
|
||
A freeze marker must be a regular file. A directory or a symlink named `MIGRATION-FREEZE` that the ancestor walk finds is ignored — the symlink with a one-line warning on stderr, so a stray link never disarms the gate in silence. To drive the freeze through an indirection on purpose, name that link with `BD_MIGRATION_FREEZE_FILE` (below), which bd follows.
|
||
|
||
```bash
|
||
touch MIGRATION-FREEZE # the file's existence is the whole signal
|
||
|
||
# Optional payload: operator, RFC3339 timestamp, and reason, tab-separated
|
||
# on one line. bd echoes it back in the refusal.
|
||
printf 'alice\t2026-08-16T12:00:00Z\tmoving to the new server\n' > MIGRATION-FREEZE
|
||
|
||
bd create "new work"
|
||
# ⛔ ERROR: workspace is frozen for migration (by alice).
|
||
# Reason: moving to the new server
|
||
# bd create is blocked by the freeze marker at /work/MIGRATION-FREEZE.
|
||
# To resume writes, remove that file.
|
||
|
||
rm MIGRATION-FREEZE # thaw
|
||
```
|
||
|
||
Blocked commands exit **14** — a stable code scripts branch on to tell "someone is migrating this workspace, come back later" from a generic failure worth an immediate retry. That includes the destructive ones: `bd init --reinit-local` and `bd bootstrap` are refused too.
|
||
|
||
Reads (`bd list`, `bd show`, `bd ready`, …) keep working during a freeze, and bd's own background maintenance stands down with them — version-bump migration, JSONL auto-import, Dolt auto-commit, auto-backup, auto-export and auto-push are all skipped, so running a read does not leave a commit in the store you are migrating.
|
||
|
||
<Warning>
|
||
A `bd serve` process started before the marker appeared keeps accepting HTTP writes: the freeze is a CLI-invocation gate, and a running server never re-reads it. Stop the server before you freeze.
|
||
</Warning>
|
||
|
||
If bd cannot tell whether a marker is present — a permission error on the marker or on a directory above it — it refuses the write and says so, rather than assuming the workspace is open.
|
||
|
||
`BD_MIGRATION_FREEZE_FILE` names one explicit path to consult instead of walking ancestors, for markers that live outside the tree. It is authoritative: when it is set, nothing else is checked. Because you name that path deliberately, it may be a symlink — bd follows it and freezes when the link resolves to a regular marker file — so an indirection such as `current -> releases/42/MIGRATION-FREEZE` works as the authoritative signal.
|
||
|
||
## Security: Where Secrets Live
|
||
|
||
- Tokens and API keys are never stored in the Dolt database — database config is pushed to remotes, which would expose secrets and trip GitHub secret scanning. `bd config set` routes secret keys to the local `config.yaml` instead.
|
||
- Writing a secret to a git-tracked `config.yaml` is refused unless you pass `--force-git-tracked`; environment variables are the safer default.
|
||
- `bd init` writes a `.beads/.gitignore` that keeps the database directories (`embeddeddolt/`, `dolt/`), runtime files, push state, and the federation credential key out of git.
|
||
|
||
## Example `.beads/config.yaml`
|
||
|
||
```yaml
|
||
# Default JSON output for scripting
|
||
json: true
|
||
|
||
# Dolt history & sync
|
||
dolt:
|
||
auto-commit: on # Create a Dolt commit after each successful write
|
||
auto-push: false # Opt-in for single-writer setups
|
||
|
||
# Issue creation policies
|
||
create:
|
||
require-description: true
|
||
|
||
validation:
|
||
on-create: warn # Warn when creating issues missing required sections
|
||
on-close: none
|
||
on-sync: none
|
||
|
||
# Git commit signing for beads commits (GH#600)
|
||
git:
|
||
author: "beads-bot <beads@example.com>"
|
||
no-gpg-sign: true
|
||
|
||
# Periodic Dolt-native backup to .beads/backup/
|
||
backup:
|
||
enabled: true
|
||
interval: 15m
|
||
|
||
# Optional auto-export of issues.jsonl after writes for viewers/interchange
|
||
export:
|
||
auto: false
|
||
path: issues.jsonl
|
||
interval: 60s
|
||
git-add: false
|
||
|
||
# Optional Dolt federation
|
||
federation:
|
||
remote: dolthub://myorg/beads
|
||
sovereignty: T2
|
||
|
||
# Directory-aware label scoping for monorepos (GH#541)
|
||
directory:
|
||
labels:
|
||
packages/maverick: maverick
|
||
packages/agency: agency
|
||
|
||
# Cross-project dependency resolution (bd-h807)
|
||
external_projects:
|
||
beads: ../beads
|
||
other-project: /absolute/path/to/other-project
|
||
|
||
output:
|
||
title-length: 255
|
||
```
|
||
|
||
For machine-specific overrides that should not be committed, drop them in `.beads/config.local.yaml`; it is merged in last.
|
||
|
||
## Per-Command Override
|
||
|
||
```bash
|
||
bd --db /tmp/test.db list # Override database for one command
|
||
bd --json --actor "ci-bot" create "Fix things" # Multiple flags
|
||
```
|
||
|
||
## Use in Scripts
|
||
|
||
Configuration is designed for scripting; every `bd config` subcommand takes `--json`:
|
||
|
||
```bash
|
||
# Get one value ({"key":"jira.url","value":"..."})
|
||
JIRA_URL=$(bd config get --json jira.url | jq -r '.value')
|
||
|
||
# Get all database config as a flat object
|
||
bd config list --json | jq -r '.["jira.project"]'
|
||
```
|
||
|
||
## Viewing Active Configuration
|
||
|
||
```bash
|
||
bd config show # Effective config with provenance
|
||
bd config show --json # Machine-readable
|
||
bd config list # Database-stored config
|
||
bd info --json | jq '.config' # Quick snapshot
|
||
```
|