Support .beads/.env for per-project Dolt credentials

[restarter]

Problem

There's no per-project way to configure Dolt credentials. This creates a dilemma when you have a mix of local and remote projects:

project-a/  → remote Dolt on VPS (database "app_a")
project-b/  → remote Dolt on VPS (database "app_b")
project-c/  → local embedded Dolt, no remote server at all

If I set BEADS_DOLT_* env vars globally (e.g., in .zshrc), then project-c breaks - it tries to connect to the remote server where no database exists for it, instead of using local embedded Dolt.

If I don't set them globally, then project-a and project-b can't connect to the remote server without external tooling.

Why external tooling doesn't work

direnv / .zshrc functions - only work in interactive terminals. Tools like Claude Code execute each shell command in a separate non-interactive subprocess (/bin/sh -c "..."). The direnv hook (eval "$(direnv hook zsh)") never fires, and .zshrc functions aren't loaded. Same applies to any AI coding agent, CI/CD pipeline, or script that spawns bd as a subprocess.

Shell wrapper script (current workaround) - a bd script in PATH that finds .beads/.env, exports vars, and calls the real binary. Works everywhere but is fragile: breaks on go install updates (overwrites the wrapper), requires manual setup per machine, and adds an indirection layer.

metadata.json - supports dolt_server_host/dolt_server_user but dolt_server_port is deprecated, and password is intentionally env-only (configfile.go:34). Credentials end up split across two config sources.

The common thread: the solution needs to live inside bd itself, not in the shell environment.

Proposed Solution

Auto-load .beads/.env into process environment before any GetDolt*() calls.

Implementation

In PersistentPreRun (cmd/bd/main.go), after beadsDir is resolved (~line 476) but before configfile.Load() (~line 492):

envFile := filepath.Join(beadsDir, ".env")
if _, err := os.Stat(envFile); err == nil {
    _ = gotenv.Load(envFile)
}

gotenv (github.com/subosio/gotenv) is already an indirect dependency via viper. gotenv.Load() is non-overriding - shell env always wins.

.beads/.env format

BEADS_DOLT_SERVER_HOST=<server-ip>
BEADS_DOLT_SERVER_PORT=3306
BEADS_DOLT_SERVER_USER=<username>
BEADS_DOLT_PASSWORD=<password>

How it solves the problem

• project-a/.beads/.env exists → connects to remote server
• project-b/.beads/.env exists → connects to remote server
• project-c/ has no .beads/.env → uses local embedded Dolt (current default, unchanged)

No global env vars needed. No external tools. No shell wrappers. Works in terminals, AI agents, CI/CD, scripts - anywhere bd runs.

Env var precedence (preserved)

shell environment > .beads/.env > metadata.json defaults

Scope limitation

BEADS_DIR in .beads/.env would NOT affect config.yaml discovery (loaded earlier in init() → config.Initialize()). This is acceptable - the primary use case is BEADS_DOLT_* connection params.

Environment

• beads v0.59.0 (dev)
• macOS, multiple projects with mix of local and remote Dolt

[maphew]

Triage update (2026-03-15):

PR #2521 ("feat: Load .beads/.env for per-project Dolt credentials") was closed unmerged on 2026-03-12.

I've confirmed that per-project Dolt credential configuration is not currently supported via any built-in mechanism. The codebase reads all BEADS_DOLT_* env vars directly from the process environment (os.Getenv() calls in internal/storage/dolt/store.go, internal/doltserver/doltserver.go, etc.). While metadata.json supports dolt_server_host and dolt_server_user, the password is intentionally env-only, and there is no automatic .env file loading anywhere.

The gotenv library (github.com/subosio/gotenv) is already an indirect dependency via viper, so the proposed implementation approach from the issue remains viable.

Status: This remains an open feature request. The core problem — needing per-project Dolt connection config without relying on shell environment or external tooling — is still unaddressed.

[DreadPirateRobertz]

Valid use case — the mix of local/remote Dolt projects is a real configuration gap.

The .beads/.env approach is clean and follows established patterns (Docker Compose, Rails, etc.). A few implementation thoughts:

• Load order: .beads/.env should override global env vars but be overridden by explicit CLI flags. So: defaults → global env → .beads/.env → CLI flags
• Security: .beads/.env should be added to .gitignore by default (credentials shouldn't be committed). bd init could create a .beads/.gitignore that includes .env
• Variable scoping: Only BEADS_DOLT_* vars should be honored from .beads/.env — don't turn it into a general env file that could override PATH or other system vars
• Discovery: bd doctor could warn when it detects mismatched Dolt connection state (e.g., env says remote but metadata says embedded)

This would also help the multi-machine setup described in steveyegge/gastown#2801 — each project could point to its own Dolt server without polluting the global environment.

[DreadPirateRobertz]

PR #2640 implements this — auto-loads .beads/.env using gotenv.Load (already an indirect dependency). Non-overriding so shell env always takes precedence. Also adds .env to the gitignore template to protect credentials.

[DreadPirateRobertz]

Fix submitted in PR #2640 — loads .beads/.env via gotenv early in PersistentPreRunE. Doctor's gitignore check updated to include .env pattern.

[maphew]

@restarter please let us know when you've had a chance to exercise this fix and what the results are. Thanks!

[restarter]

Testing PR #2640 — Results

Built from feat/beads-env-file branch (commit ddfe1fa) and tested against a live VPS Dolt server (Direct SQL mode, port 3306).

Setup

• macOS, beads v0.60.0 → v0.61.0 (auto-migrated on first run)
• .beads/.env with BEADS_DOLT_SERVER_HOST, BEADS_DOLT_SERVER_PORT, BEADS_DOLT_SERVER_USER, BEADS_DOLT_PASSWORD
• All shell env vars explicitly unset via env -u for each test

Results

Test	Result	Notes
bd ready without env vars	PASS	.env auto-loaded, connected to VPS, returned tasks
bd list --status=in_progress	PASS	Same — works without wrapper
Shell env overrides .env	PASS	Setting BEADS_DOLT_SERVER_HOST=192.168.99.99 caused expected connection failure
Project without .env	PASS	Falls through to local Dolt (no remote connection attempted)
bd doctor	FAIL	Starts local Dolt server instead of connecting to VPS (see bug below)

Bug: bd doctor doesn't load .beads/.env

doctor is in the noDbCommands list (cmd/bd/main.go:352), so PersistentPreRunE returns early at line 393-394 — before loadBeadsEnvFile() is called at line 513.

When doctor later creates its own store connections (via RunServerHealthChecks → cfg.GetDoltServerHost() → os.Getenv("BEADS_DOLT_SERVER_HOST")), the env vars are empty, so it falls back to 127.0.0.1 and auto-starts a local Dolt server.

Fix: Move loadBeadsEnvFile() above the noDbCommands early-return, or call it explicitly in the doctor command's Run(). The .env loading only needs beadsDir which is resolved earlier via FindDatabasePath.

Bottom line

The core feature works — bd ready, bd list, bd show, etc. all connect to the remote VPS using .beads/.env without any wrapper script or global env vars. This is exactly what we needed. The doctor bug is minor and doesn't block the main use case.

[maphew]

thanks! I've created #2677 for the bd doctor bug