fix(init): make JSONL auto-export opt-in (#4063)

* fix(init): make JSONL auto-export opt-in

Default export.auto and export.git-add to false for new repos, make the init prompt opt-in, and update docs/tests to describe JSONL as an optional viewer/interchange/backup export rather than core sync behavior.

Fixes GH#4062

* refactor(auto-export): check commit before throttle

Move cheap Dolt commit change detection ahead of the auto-export throttle and extract the throttle decision into a tested helper. This keeps the default-off design while carrying the compatible part of Jeremy Longshore's GH#4061 refactor.

Based-on: 313e1f8258

Co-authored-by: jeremylongshore <jeremylongshore@users.noreply.github.com>

* docs: regenerate versioned CLI references
* docs: call out JSONL export opt-in change

---------

_codex-gpt-5.5-medium on behalf of CI Bot_
_codex-gpt-5.5-high on behalf of matt wilkie_
Co-authored-by: CI Bot <ci@beads.test>
This commit is contained in:
matt wilkie 2026-05-21 16:21:00 -07:00 • committed by GitHub
commit 3988db7e0d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
20 changed files with 390 additions and 93 deletions

View file

@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Upgrade Notes
- **JSONL auto-export and auto-staging are now opt-in.** Repositories that
relied on the previous implicit default should set it explicitly before or
after upgrading:
```bash
bd config set export.auto true
bd config set export.git-add true
```
Dolt is the primary datastore. `.beads/issues.jsonl` is now treated as an
optional export for viewers such as `bv`, interchange, and issue-level
migration. It is not the canonical git-tracked source of truth, not
cross-machine sync, and not a full database backup. Use `bd dolt push` /
`bd dolt pull` for sync and `bd backup` for restorable database backups.
Existing repositories that already have `export.auto: true` or
`export.git-add: true` configured keep that behavior.
### Added
- **Foreign keys across issue and wisp tables.** Migrations `0040`–`0042` and the new `ignored/0001`–`ignored/0004` add explicit FKs with `ON DELETE CASCADE ON UPDATE CASCADE` on `dependencies`, `labels`, `comments`, `events`, `issue_snapshots`, `compaction_snapshots`, `child_counters`, and the matching `wisp_*` tables. Deleting or renaming a parent row now cascades automatically — the manual cleanup loops in `issueops/delete.go`, `dolt/wisps.go`, `dolt/ephemeral_routing.go`, and `cmd/bd/rename_prefix.go` have been removed (net ~300 lines down). ([#3952](https://github.com/gastownhall/beads/pull/3952))
@ -43,7 +62,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- **Init refusal messages follow What/Why/Next structure** — runtime error text no longer echoes copy-pasteable destructive invocations. Token values and exact override commands live in `bd help init-safety` and `docs/RECOVERY.md` only. Closes the failure class where an AI agent destroyed 247 issues by pattern-matching on the tool's own error output (`58f5989bf`).
- **`beads.OpenBestAvailable` signature changed (breaking)** — returns `(Storage, error)` instead of `(Storage, Unlocker, error)`. The per-open flock and `Unlocker` return value were removed; the embedded Dolt engine handles its own concurrency internally. External SDK consumers that call `OpenBestAvailable` must drop the second return value. ([PR #3614](https://github.com/gastownhall/beads/pull/3614))
- **Embedded-mode flock removed** — the process-lifetime exclusive flock on `.beads/embeddeddolt/` has been removed. Concurrent `bd` processes now open the embedded engine independently. If the GH#2571 nil-deref stack (`NewConnector` → `DoltDB.SetCrashOnFatalError` → `CollectDBs`) resurfaces under concurrent access, it should be filed and fixed in `dolthub/driver`, not reintroduced as a beads-side flock. ([PR #3614](https://github.com/gastownhall/beads/pull/3614))
- **Auto-export is now on by default** — pending Dolt changes are committed automatically and exported to JSONL when configured, reducing manual sync drift in coordinated repos.
- **Auto-export is now opt-in by default** — repositories without explicit
`export.auto` / `export.git-add` settings leave JSONL refresh and staging
disabled unless a viewer or JSONL integration explicitly enables them. This
keeps `.beads/issues.jsonl` as an optional export surface, not the default
mutation path. ([GH#4062](https://github.com/gastownhall/beads/issues/4062))
- **Release workflow uses the checked-in beads-release formula** — the old release shell path now delegates to the formula-backed release workflow with CI gates.
### Deprecated

View file

@ -36,15 +36,17 @@ Common namespaces:
- doctor.suppress.* Suppress specific bd doctor warnings (GH#1095)
Auto-Export (config.yaml):
Writes .beads/issues.jsonl after every write command (throttled).
Enabled by default. Useful for viewers (bv) and interchange; not a backup.
Optional JSONL export to .beads/issues.jsonl after write commands (throttled).
Useful for viewers (bv), interchange, and issue-level migration; not a backup.
It is not cross-machine sync; use bd dolt push/pull with a Dolt remote.
Disabled by default. Enable only for integrations that need fresh JSONL.
Auto-staging is separate and disabled by default.
Keys:
export.auto Enable/disable auto-export (default: true)
export.auto Enable/disable auto-export (default: false)
export.path Output filename relative to .beads/ (default: issues.jsonl)
export.interval Minimum time between exports (default: 60s)
export.git-add Auto-stage the export file (default: true)
export.git-add Auto-stage the export file (default: false)
Custom Status States:
You can define custom status states for multi-step pipelines using the
@ -65,8 +67,9 @@ Suppressing Doctor Warnings:
To unsuppress: bd config unset doctor.suppress.<slug>
Examples:
bd config set export.auto false # Disable auto-export
bd config set export.auto true # Enable auto-export for viewer integrations
bd config set export.path "beads.jsonl" # Custom export filename
bd config set export.git-add true # Also stage the export file
bd config set jira.url "https://company.atlassian.net"
bd config set jira.project "PROJ"
bd config set status.custom "awaiting_review,awaiting_testing"

View file

@ -54,19 +54,27 @@ func maybeAutoExport(ctx context.Context) {
return
}
// Load state and check throttle
// Resolve the export path before throttle/check detection so all decisions
// refer to the path that would actually be written.
exportPath := config.GetString("export.path")
if exportPath == "" {
if globalFlag {
exportPath = "global-issues.jsonl"
} else {
exportPath = "issues.jsonl"
}
}
fullPath := filepath.Join(beadsDir, exportPath)
// Load state + interval.
state := loadExportAutoState(beadsDir)
interval := config.GetDuration("export.interval")
if interval == 0 {
interval = 60 * time.Second
}
if !state.Timestamp.IsZero() && time.Since(state.Timestamp) < interval {
debug.Logf("auto-export: throttled (last export %s ago, interval %s)\n",
time.Since(state.Timestamp).Round(time.Second), interval)
return
}
// Change detection via Dolt commit hash
// Change detection via Dolt commit hash. This is cheap, so do it before
// throttle: when there are no changes, there is nothing to throttle.
currentCommit, err := store.GetCurrentCommit(ctx)
if err != nil {
fmt.Fprintf(os.Stderr, "Warning: auto-export skipped: failed to get current commit: %v\n", err)
@ -77,16 +85,11 @@ func maybeAutoExport(ctx context.Context) {
return
}
// Determine output path
exportPath := config.GetString("export.path")
if exportPath == "" {
if globalFlag {
exportPath = "global-issues.jsonl"
} else {
exportPath = "issues.jsonl"
}
if !shouldExport(state, interval) {
debug.Logf("auto-export: throttled (last export %s ago, interval %s)\n",
time.Since(state.Timestamp).Round(time.Second), interval)
return
}
fullPath := filepath.Join(beadsDir, exportPath)
// Run the export — memories are excluded from auto-export because they
// contain private agent context that must not reach git history (GH#3650).
@ -128,6 +131,18 @@ func maybeAutoExport(ctx context.Context) {
saveExportAutoState(beadsDir, &newState)
}
// shouldExport reports whether the throttle window has elapsed, or whether
// this is the first auto-export attempt. It returns false only when a recent
// export exists and the configured interval has not elapsed.
//
// Extracted from Jeremy Longshore's GH#4061 throttle-decision refactor.
func shouldExport(state *exportAutoState, interval time.Duration) bool {
if state.Timestamp.IsZero() {
return true
}
return time.Since(state.Timestamp) >= interval
}
// exportToFile atomically exports issues + memories to the given file path.
// Writes to a temp file first, then renames into place so readers never see
// a partial or truncated export. Used by both `bd export -o` and auto-export.

View file

@ -6,6 +6,7 @@ import (
"path/filepath"
"strings"
"testing"
"time"
"github.com/spf13/cobra"
)
@ -547,3 +548,54 @@ func TestGitAddFile_RedirectCase_DoesNotStageInMainRepo(t *testing.T) {
checkNoStage("worktree", worktree)
checkNoStage("main", mainRepo)
}
// TestShouldExport covers the pure throttle-window decision used by
// maybeAutoExport. Adapted from Jeremy Longshore's GH#4061 refactor.
func TestShouldExport(t *testing.T) {
now := time.Now()
cases := []struct {
name string
state *exportAutoState
interval time.Duration
want bool
}{
{
name: "first run always exports",
state: &exportAutoState{},
interval: time.Minute,
want: true,
},
{
name: "throttle window active blocks",
state: &exportAutoState{Timestamp: now.Add(-10 * time.Second)},
interval: time.Minute,
want: false,
},
{
name: "throttle window elapsed allows",
state: &exportAutoState{Timestamp: now.Add(-2 * time.Minute)},
interval: time.Minute,
want: true,
},
{
name: "at interval boundary allows",
state: &exportAutoState{Timestamp: now.Add(-time.Minute)},
interval: time.Minute,
want: true,
},
{
name: "zero interval allows",
state: &exportAutoState{Timestamp: now.Add(-time.Microsecond)},
interval: 0,
want: true,
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
if got := shouldExport(tc.state, tc.interval); got != tc.want {
t.Errorf("shouldExport(%+v, %s) = %v, want %v", tc.state, tc.interval, got, tc.want)
}
})
}
}

View file

@ -53,17 +53,17 @@ 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 enabled by default. After every write command, bd exports
issues to .beads/issues.jsonl (throttled to once per 60s). This keeps
viewers (bv) and interchange up to date without extra steps.
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 disable: bd config set export.auto false
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 (enabled)
• 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.`,
Run: func(cmd *cobra.Command, _ []string) {
@ -1275,22 +1275,23 @@ Non-interactive mode (--non-interactive or BD_NON_INTERACTIVE=1):
}
}
// Auto-export prompt: enabled by default, let user opt out interactively (GH#2973).
// In non-interactive mode the default (enabled) is kept.
// Auto-export prompt: disabled by default, let users opt in
// interactively for viewers and other JSONL integrations (GH#4062).
// In non-interactive mode the default (disabled) is kept.
if !nonInteractive && !quiet {
wantExport, err := promptAutoExport()
if err != nil && isCanceled(err) {
fmt.Fprintln(os.Stderr, "Setup canceled.")
exitCanceled()
}
if !wantExport {
if err := config.SetYamlConfig("export.auto", "false"); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to disable auto-export: %v\n", err)
if wantExport {
if err := config.SetYamlConfig("export.auto", "true"); err != nil {
fmt.Fprintf(os.Stderr, "Warning: failed to enable auto-export: %v\n", err)
} else {
fmt.Printf(" %s Auto-export disabled (enable later with: bd config set export.auto true)\n", ui.RenderPass("✓"))
fmt.Printf(" %s Auto-export enabled -> .beads/issues.jsonl\n", ui.RenderPass("✓"))
}
} else if !quiet {
fmt.Printf(" %s Auto-export enabled → .beads/issues.jsonl\n", ui.RenderPass("✓"))
fmt.Printf(" %s Auto-export disabled (enable later with: bd config set export.auto true)\n", ui.RenderPass("✓"))
}
}
@ -1978,12 +1979,13 @@ func promptContributorMode() (isContributor bool, err error) {
return isContributor, nil
}
// promptAutoExport asks the user whether to keep auto-export enabled (the default).
// Returns true to keep it enabled, false to disable.
// promptAutoExport asks the user whether to enable optional auto-export.
// Returns true to enable it, false to leave it disabled.
func promptAutoExport() (bool, error) {
fmt.Printf("\n%s Auto-export keeps .beads/issues.jsonl up to date after every write command.\n", ui.RenderAccent("▶"))
fmt.Println(" This is useful for viewers (bv) and interchange. Dolt remotes/backups handle sync and backup.")
fmt.Print("\nEnable auto-export? [Y/n]: ")
fmt.Printf("\n%s Auto-export can keep .beads/issues.jsonl up to date after write commands.\n", ui.RenderAccent("▶"))
fmt.Println(" This optional JSONL export is useful for viewers (bv), interchange, and issue-level migration.")
fmt.Println(" Dolt remotes/backups handle cross-machine sync and backup.")
fmt.Print("\nEnable auto-export? [y/N]: ")
reader := bufio.NewReader(os.Stdin)
response, err := readLineWithContext(getRootContext(), reader, os.Stdin)
@ -1995,8 +1997,8 @@ func promptAutoExport() (bool, error) {
}
response = strings.TrimSpace(strings.ToLower(response))
// Default to yes (empty or "y" or "yes")
return response == "" || response == "y" || response == "yes", nil
// Default to no. Users and integrations can enable it explicitly.
return response == "y" || response == "yes", nil
}
func shouldWireInitRemote(syncURL string, syncFromRemote, syncURLFromConfig, syncURLFromGitOrigin bool) bool {

View file

@ -2,7 +2,11 @@ package main
import (
"os"
"os/exec"
"path/filepath"
"strings"
"testing"
"time"
)
// TestIsNonInteractiveInit tests the non-interactive detection logic.
@ -126,3 +130,62 @@ func TestIsNonInteractiveInitPrecedence(t *testing.T) {
t.Error("BD_NON_INTERACTIVE=1 should return true")
}
}
func TestInitNonInteractiveAutoExportDefaultOffAndOptIn(t *testing.T) {
bd := buildBDForInitTests(t)
dir := t.TempDir()
runBDForAutoExportInitTest(t, bd, dir, "init", "--prefix", "test", "--quiet", "--non-interactive", "--skip-hooks", "--skip-agents")
if got := strings.TrimSpace(runBDStdoutForAutoExportInitTest(t, bd, dir, "config", "get", "export.auto")); got != "false" {
t.Fatalf("export.auto default = %q, want false", got)
}
if got := strings.TrimSpace(runBDStdoutForAutoExportInitTest(t, bd, dir, "config", "get", "export.git-add")); got != "false" {
t.Fatalf("export.git-add default = %q, want false", got)
}
runBDForAutoExportInitTest(t, bd, dir, "create", "default-off issue", "-p", "2")
jsonlPath := filepath.Join(dir, ".beads", "issues.jsonl")
if _, err := os.Stat(jsonlPath); !os.IsNotExist(err) {
t.Fatalf("default-off create wrote %s; stat err=%v", jsonlPath, err)
}
runBDForAutoExportInitTest(t, bd, dir, "config", "set", "export.interval", "1ms")
runBDForAutoExportInitTest(t, bd, dir, "config", "set", "export.auto", "true")
if got := strings.TrimSpace(runBDStdoutForAutoExportInitTest(t, bd, dir, "config", "get", "export.auto")); got != "true" {
t.Fatalf("explicit export.auto = %q, want true", got)
}
time.Sleep(10 * time.Millisecond)
runBDForAutoExportInitTest(t, bd, dir, "create", "explicit export issue", "-p", "2")
data, err := os.ReadFile(jsonlPath)
if err != nil {
t.Fatalf("explicit export.auto did not write %s: %v", jsonlPath, err)
}
if !strings.Contains(string(data), "explicit export issue") {
t.Fatalf("JSONL export did not contain created issue:\n%s", data)
}
}
func runBDStdoutForAutoExportInitTest(t *testing.T, bd, dir string, args ...string) string {
t.Helper()
cmd := exec.Command(bd, args...)
cmd.Dir = dir
cmd.Env = append(os.Environ(), "BD_NON_INTERACTIVE=1")
out, err := cmd.Output()
if err != nil {
t.Fatalf("bd %v failed: %v", args, err)
}
return string(out)
}
func runBDForAutoExportInitTest(t *testing.T, bd, dir string, args ...string) string {
t.Helper()
cmd := exec.Command(bd, args...)
cmd.Dir = dir
cmd.Env = append(os.Environ(), "BD_NON_INTERACTIVE=1")
out, err := cmd.CombinedOutput()
if err != nil {
t.Fatalf("bd %v failed: %v\n%s", args, err, out)
}
return string(out)
}

View file

@ -81,6 +81,14 @@ func renderInitConfigYAML(prefix string, noDbMode bool) []byte {
# git-push: false # Disable git push (backup locally only)
# git-repo: "" # Separate git repo for backups (default: project repo)
# Optional JSONL auto-export for viewers, interchange, and issue-level migration.
# Disabled by default; enable only when an integration needs fresh .beads/issues.jsonl.
# export:
# auto: false
# path: issues.jsonl
# interval: 60s
# git-add: false
# Integration settings (access with 'bd config get/set')
# Non-secret keys (stored in the database):
# - jira.url, jira.project

View file

@ -89,3 +89,85 @@ func TestReadLineWithContextCanceled(t *testing.T) {
t.Fatal("timeout waiting for readLineWithContext")
}
}
func TestPromptAutoExportDefaultsOff(t *testing.T) {
got, output, err := runPromptAutoExport(t, "\n")
if err != nil {
t.Fatalf("promptAutoExport returned error: %v", err)
}
if got {
t.Fatal("empty response should leave auto-export disabled")
}
if !strings.Contains(output, "Enable auto-export? [y/N]:") {
t.Fatalf("prompt did not show opt-in default:\n%s", output)
}
if !strings.Contains(output, "optional JSONL export") {
t.Fatalf("prompt should describe JSONL as optional export:\n%s", output)
}
if !strings.Contains(output, "Dolt remotes/backups handle cross-machine sync and backup") {
t.Fatalf("prompt should direct sync to Dolt remotes:\n%s", output)
}
}
func TestPromptAutoExportAcceptsYes(t *testing.T) {
got, _, err := runPromptAutoExport(t, "yes\n")
if err != nil {
t.Fatalf("promptAutoExport returned error: %v", err)
}
if !got {
t.Fatal("yes response should enable auto-export")
}
}
func runPromptAutoExport(t *testing.T, input string) (bool, string, error) {
t.Helper()
stdinFile, err := os.CreateTemp(t.TempDir(), "stdin-*")
if err != nil {
t.Fatalf("create temp stdin: %v", err)
}
if _, err := stdinFile.WriteString(input); err != nil {
t.Fatalf("write temp stdin: %v", err)
}
if _, err := stdinFile.Seek(0, 0); err != nil {
t.Fatalf("rewind temp stdin: %v", err)
}
oldStdin := os.Stdin
oldStdout := os.Stdout
oldRootCtx := rootCtx
oldRootCancel := rootCancel
var oldCmdRootCtx context.Context
var oldCmdRootCancel context.CancelFunc
if cmdCtx != nil {
oldCmdRootCtx = cmdCtx.RootCtx
oldCmdRootCancel = cmdCtx.RootCancel
}
r, w, err := os.Pipe()
if err != nil {
t.Fatalf("create stdout pipe: %v", err)
}
ctx, cancel := context.WithCancel(context.Background())
setRootContext(ctx, cancel)
os.Stdin = stdinFile
os.Stdout = w
got, promptErr := promptAutoExport()
_ = w.Close()
var b strings.Builder
_, _ = io.Copy(&b, r)
_ = r.Close()
os.Stdin = oldStdin
os.Stdout = oldStdout
cancel()
rootCtx = oldRootCtx
rootCancel = oldRootCancel
if cmdCtx != nil {
cmdCtx.RootCtx = oldCmdRootCtx
cmdCtx.RootCancel = oldCmdRootCancel
}
_ = stdinFile.Close()
return got, b.String(), promptErr
}

View file

@ -8,6 +8,7 @@ stdout 'initialized successfully'
! exists .beads/export-state.json
# First real write must export immediately, not wait for throttle to expire.
bd config set export.auto true
bd create 'First issue'
exists .beads/issues.jsonl
grep 'First issue' .beads/issues.jsonl

View file

@ -2584,15 +2584,17 @@ Common namespaces:
- doctor.suppress.* Suppress specific bd doctor warnings (GH#1095)
Auto-Export (config.yaml):
Writes .beads/issues.jsonl after every write command (throttled).
Enabled by default. Useful for viewers (bv) and interchange; not a backup.
Optional JSONL export to .beads/issues.jsonl after write commands (throttled).
Useful for viewers (bv), interchange, and issue-level migration; not a backup.
It is not cross-machine sync; use bd dolt push/pull with a Dolt remote.
Disabled by default. Enable only for integrations that need fresh JSONL.
Auto-staging is separate and disabled by default.
Keys:
export.auto Enable/disable auto-export (default: true)
export.auto Enable/disable auto-export (default: false)
export.path Output filename relative to .beads/ (default: issues.jsonl)
export.interval Minimum time between exports (default: 60s)
export.git-add Auto-stage the export file (default: true)
export.git-add Auto-stage the export file (default: false)
Custom Status States:
You can define custom status states for multi-step pipelines using the
@ -2613,8 +2615,9 @@ Suppressing Doctor Warnings:
To unsuppress: bd config unset doctor.suppress.&lt;slug&gt;
Examples:
bd config set export.auto false # Disable auto-export
bd config set export.auto true # Enable auto-export for viewer integrations
bd config set export.path "beads.jsonl" # Custom export filename
bd config set export.git-add true # Also stage the export file
bd config set jira.url "https://company.atlassian.net"
bd config set jira.project "PROJ"
bd config set status.custom "awaiting_review,awaiting_testing"
@ -3343,17 +3346,17 @@ 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 enabled by default. After every write command, bd exports
issues to .beads/issues.jsonl (throttled to once per 60s). This keeps
viewers (bv) and interchange up to date without extra steps.
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 disable: bd config set export.auto false
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 (enabled)
• 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.

View file

@ -346,10 +346,10 @@ Configuration keys use dot-notation namespaces to organize settings:
- `min_hash_length` - Minimum hash ID length (default: 4)
- `max_hash_length` - Maximum hash ID length (default: 8)
- `import.orphan_handling` - How to handle hierarchical issues with missing parents during import (default: `allow`)
- `export.auto` - Refresh the JSONL export after every write command (default: `true`). This is for viewers, interchange, and issue-level migration; it is not cross-machine sync and not a full database backup.
- `export.auto` - Refresh the JSONL export after every write command (default: `false`). This is for viewers, interchange, and issue-level migration; it is not cross-machine sync and not a full database backup.
- `export.path` - Output filename relative to `.beads/` (default: `issues.jsonl`)
- `export.interval` - Minimum time between auto-exports (default: `60s`)
- `export.git-add` - Run `git add` on the export file after writing (default: `true`)
- `export.git-add` - Run `git add` on the export file after writing (default: `false`)
- `export.error_policy` - Error handling strategy for exports (default: `strict`)
- `export.retry_attempts` - Number of retry attempts for transient errors (default: 3)
- `export.retry_backoff_ms` - Initial backoff in milliseconds for retries (default: 100)
@ -360,6 +360,20 @@ Configuration keys use dot-notation namespaces to organize settings:
- `sync.branch` - Name of the dedicated sync branch for beads data (see docs/PROTECTED_BRANCHES.md)
- `sync.require_confirmation_on_mass_delete` - Require interactive confirmation before pushing when >50% of issues vanish during a merge AND more than 5 issues existed before (default: `false`)
**Upgrade note:** `export.auto` and `export.git-add` are opt-in. Older releases
briefly made `.beads/issues.jsonl` look like the default git-tracked source of
truth; current releases treat it as an optional export for viewers,
interchange, and issue-level migration. If your workflow depends on fresh JSONL
or on the pre-commit hook staging that file, set both values explicitly:
```bash
bd config set export.auto true
bd config set export.git-add true
```
Use `bd dolt push` / `bd dolt pull` for cross-machine sync and `bd backup` for
restorable database backups.
### Integration Namespaces
Use these namespaces for external integrations:

View file

@ -237,13 +237,13 @@ func Initialize() error {
v.SetDefault("backup.git-push", false)
v.SetDefault("backup.git-repo", "")
// Auto-export: write JSONL after mutations for viewers, interchange, and
// backup. It is not cross-machine sync; Dolt remotes are the source of
// truth for sync. Enabled by default so tools like bv see fresh data.
v.SetDefault("export.auto", true)
// Auto-export: optional JSONL export after mutations for viewers,
// interchange, and backup. It is not cross-machine sync; Dolt remotes are
// the source of truth for sync. Viewer integrations can opt in explicitly.
v.SetDefault("export.auto", false)
v.SetDefault("export.interval", "60s")
v.SetDefault("export.path", "issues.jsonl") // relative to .beads/; canonical name
v.SetDefault("export.git-add", true)
v.SetDefault("export.git-add", false)
// Auto-import: legacy compatibility fallback for projects that have not
// configured a Dolt remote yet. Hook code skips this path when sync.remote

View file

@ -66,6 +66,8 @@ func TestDefaults(t *testing.T) {
{"json", false, func(k string) interface{} { return GetBool(k) }},
{"db", "", func(k string) interface{} { return GetString(k) }},
{"actor", "", func(k string) interface{} { return GetString(k) }},
{"export.auto", false, func(k string) interface{} { return GetBool(k) }},
{"export.git-add", false, func(k string) interface{} { return GetBool(k) }},
}
for _, tt := range tests {

View file

@ -24,15 +24,17 @@ Common namespaces:
- doctor.suppress.* Suppress specific bd doctor warnings (GH#1095)
Auto-Export (config.yaml):
Writes .beads/issues.jsonl after every write command (throttled).
Enabled by default. Useful for viewers (bv) and interchange; not a backup.
Optional JSONL export to .beads/issues.jsonl after write commands (throttled).
Useful for viewers (bv), interchange, and issue-level migration; not a backup.
It is not cross-machine sync; use bd dolt push/pull with a Dolt remote.
Disabled by default. Enable only for integrations that need fresh JSONL.
Auto-staging is separate and disabled by default.
Keys:
export.auto Enable/disable auto-export (default: true)
export.auto Enable/disable auto-export (default: false)
export.path Output filename relative to .beads/ (default: issues.jsonl)
export.interval Minimum time between exports (default: 60s)
export.git-add Auto-stage the export file (default: true)
export.git-add Auto-stage the export file (default: false)
Custom Status States:
You can define custom status states for multi-step pipelines using the
@ -53,8 +55,9 @@ Suppressing Doctor Warnings:
To unsuppress: bd config unset doctor.suppress.&lt;slug&gt;
Examples:
bd config set export.auto false # Disable auto-export
bd config set export.auto true # Enable auto-export for viewer integrations
bd config set export.path "beads.jsonl" # Custom export filename
bd config set export.git-add true # Also stage the export file
bd config set jira.url "https://company.atlassian.net"
bd config set jira.project "PROJ"
bd config set status.custom "awaiting_review,awaiting_testing"

View file

@ -30,17 +30,17 @@ 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 enabled by default. After every write command, bd exports
issues to .beads/issues.jsonl (throttled to once per 60s). This keeps
viewers (bv) and interchange up to date without extra steps.
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 disable: bd config set export.auto false
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 (enabled)
• 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.

View file

@ -108,10 +108,10 @@ Secrets in this list are refused on git-tracked `config.yaml` files unless you p
| `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 |
| `export.auto` | — | — | `true` | Refresh `.beads/issues.jsonl` export after every write; not cross-machine sync |
| `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` | — | — | `true` | Run `git add` on the export file |
| `export.git-add` | — | — | `false` | Run `git add` on the export file |
| `routing.mode` | — | — | (none) | Multi-repo routing: `auto`, `maintainer`, `contributor`, `explicit` |
| `routing.default` | — | — | `.` | Default routing target |
| `routing.maintainer` | — | — | `.` | Maintainer-routed path |
@ -127,6 +127,25 @@ Secrets in this list are refused on git-tracked `config.yaml` files unless you p
| `ai.model` | — | `BD_AI_MODEL` | `claude-haiku-4-5-20251001` | Default AI model |
| `agents.file` | — | — | `AGENTS.md` | Agents instruction filename; see routing note below |
:::important 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.
:::
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.
@ -212,12 +231,12 @@ backup:
enabled: true
interval: 15m
# Auto-export issues.jsonl after writes for viewers/interchange
# Optional auto-export of issues.jsonl after writes for viewers/interchange
export:
auto: true
auto: false
path: issues.jsonl
interval: 60s
git-add: true
git-add: false
# Optional Dolt federation
federation:

View file

@ -24,15 +24,17 @@ Common namespaces:
- doctor.suppress.* Suppress specific bd doctor warnings (GH#1095)
Auto-Export (config.yaml):
Writes .beads/issues.jsonl after every write command (throttled).
Enabled by default. Useful for viewers (bv) and interchange; not a backup.
Optional JSONL export to .beads/issues.jsonl after write commands (throttled).
Useful for viewers (bv), interchange, and issue-level migration; not a backup.
It is not cross-machine sync; use bd dolt push/pull with a Dolt remote.
Disabled by default. Enable only for integrations that need fresh JSONL.
Auto-staging is separate and disabled by default.
Keys:
export.auto Enable/disable auto-export (default: true)
export.auto Enable/disable auto-export (default: false)
export.path Output filename relative to .beads/ (default: issues.jsonl)
export.interval Minimum time between exports (default: 60s)
export.git-add Auto-stage the export file (default: true)
export.git-add Auto-stage the export file (default: false)
Custom Status States:
You can define custom status states for multi-step pipelines using the
@ -53,8 +55,9 @@ Suppressing Doctor Warnings:
To unsuppress: bd config unset doctor.suppress.&lt;slug&gt;
Examples:
bd config set export.auto false # Disable auto-export
bd config set export.auto true # Enable auto-export for viewer integrations
bd config set export.path "beads.jsonl" # Custom export filename
bd config set export.git-add true # Also stage the export file
bd config set jira.url "https://company.atlassian.net"
bd config set jira.project "PROJ"
bd config set status.custom "awaiting_review,awaiting_testing"

View file

@ -30,17 +30,17 @@ 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 enabled by default. After every write command, bd exports
issues to .beads/issues.jsonl (throttled to once per 60s). This keeps
viewers (bv) and interchange up to date without extra steps.
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 disable: bd config set export.auto false
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 (enabled)
• 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.

View file

@ -24,15 +24,17 @@ Common namespaces:
- doctor.suppress.* Suppress specific bd doctor warnings (GH#1095)
Auto-Export (config.yaml):
Writes .beads/issues.jsonl after every write command (throttled).
Enabled by default. Useful for viewers (bv) and interchange; not a backup.
Optional JSONL export to .beads/issues.jsonl after write commands (throttled).
Useful for viewers (bv), interchange, and issue-level migration; not a backup.
It is not cross-machine sync; use bd dolt push/pull with a Dolt remote.
Disabled by default. Enable only for integrations that need fresh JSONL.
Auto-staging is separate and disabled by default.
Keys:
export.auto Enable/disable auto-export (default: true)
export.auto Enable/disable auto-export (default: false)
export.path Output filename relative to .beads/ (default: issues.jsonl)
export.interval Minimum time between exports (default: 60s)
export.git-add Auto-stage the export file (default: true)
export.git-add Auto-stage the export file (default: false)
Custom Status States:
You can define custom status states for multi-step pipelines using the
@ -53,8 +55,9 @@ Suppressing Doctor Warnings:
To unsuppress: bd config unset doctor.suppress.&lt;slug&gt;
Examples:
bd config set export.auto false # Disable auto-export
bd config set export.auto true # Enable auto-export for viewer integrations
bd config set export.path "beads.jsonl" # Custom export filename
bd config set export.git-add true # Also stage the export file
bd config set jira.url "https://company.atlassian.net"
bd config set jira.project "PROJ"
bd config set status.custom "awaiting_review,awaiting_testing"

View file

@ -30,17 +30,17 @@ 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 enabled by default. After every write command, bd exports
issues to .beads/issues.jsonl (throttled to once per 60s). This keeps
viewers (bv) and interchange up to date without extra steps.
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 disable: bd config set export.auto false
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 (enabled)
• 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.