beads/docs/cli-reference/dolt.md
Chris Sells de0200ff77 docs(emitter): Cobra-accurate usage lines, published global flags, MDX ESM guard
Three generated-content defects from the adversarial review, all
structurally invisible to the drift gate (generated-vs-generated):

- Usage lines now mirror Cobra's help template: a runnable command shows
  its UseLine, a command with subcommands shows '<path> [command]', both
  when both apply. Previously bare UseLine() stamped 'bd mol [flags]' on
  30 parent pages — a line the binary never prints.
- The generated CLI index publishes the Global Flags block; the binary
  prints it on every --help but no page carried it.
- docsmint neutralizes prose lines that Mintlify's prebuild would dedent
  into MDX ESM blocks (a line beginning 'export'/'import' outside a
  fence gets wrapped in a code span). This is why /cli-reference/mail
  returned HTTP 200 while rendering only a parse-error placeholder —
  reproduced, fixed, and covered by a planted-hazard test; fenced
  content stays verbatim.

Also rewords check-cli-docs-drift.sh's early-PASS message, which
asserted 'the supplied binary differs' as the cause when uncommitted
local edits produce the same result.

All 113 pages + docs/CLI_REFERENCE.md regenerated through the pipeline;
TDD'd in cmd/bd/help_all_test.go and tools/docsmint/docsmint_test.go.
Verified live: /cli-reference/mail renders real content, zero parse
errors; generate-cli-docs.sh --check, docsync, freshness, and
mint broken-links all pass on this tree.
2026-07-12 10:37:17 -07:00

7.7 KiB

title description
bd dolt Configure Dolt database settings

{/* AUTO-GENERATED: do not edit manually */}

Generated from bd help --doc dolt.

Configure and manage Dolt database settings and server lifecycle.

Beads uses a dolt sql-server for all database operations. The server is auto-started transparently when needed. Use these commands for explicit control or diagnostics.

Server lifecycle: bd dolt start Start the Dolt server for this project bd dolt stop Stop the Dolt server for this project bd dolt status Show Dolt server status

Configuration: bd dolt show Show current Dolt configuration with connection test bd dolt set <k> <v> Set a configuration value bd dolt test Test server connection

Version control: bd dolt commit Commit pending changes bd dolt push Push commits to Dolt remote bd dolt pull Pull commits from Dolt remote

Remote management: bd dolt remote add <name> <url> Add a Dolt remote bd dolt remote list List configured remotes bd dolt remote remove <name> Remove a Dolt remote

Configuration keys for 'bd dolt set': database Database name (default: issue prefix or "beads") host Server host (default: 127.0.0.1) port Server port (auto-detected; override with bd dolt set port <N>) user MySQL user (default: root) data-dir Custom dolt data directory (absolute path; default: .beads/dolt)

Flags for 'bd dolt set': --update-config Also write to config.yaml for team-wide defaults

Examples: bd dolt set database myproject bd dolt set host 192.168.1.100 --update-config bd dolt set data-dir /home/user/.beads-dolt/myproject bd dolt test

bd dolt [command]

bd dolt clean-databases

Identify and drop leftover test and agent databases that accumulate on the shared Dolt server from interrupted test runs and terminated agents.

Stale database prefixes: testdb_, beads_test, beads_pt*, beads_vr*, doctest_, doctortest_, benchdb_*

These waste server memory and can degrade performance under concurrent load. Use --dry-run to see what would be dropped without actually dropping.

bd dolt clean-databases [flags]

Flags:

      --dry-run   Show what would be dropped without dropping

bd dolt commit

Create a Dolt commit from any uncommitted changes in the working set.

This is the primary commit point for batch mode. When auto-commit is set to "batch", changes accumulate in the working set across multiple bd commands and are committed together here with a descriptive summary message.

Also useful before push operations that require a clean working set, or when auto-commit was off or changes were made externally.

For more options (--stdin, custom messages), see: bd vc commit

bd dolt commit [flags]

Flags:

  -m, --message string   Commit message (default: auto-generated)

bd dolt killall

Find and kill orphan dolt sql-server processes not tracked by the canonical PID file for the current repo's Dolt data directory.

Under an orchestrator, the canonical server lives at $GT_ROOT/.beads/. Any other dolt sql-server processes using that shared data directory are considered orphans and will be killed.

In standalone mode, only dolt sql-server processes using the current project's Dolt data directory are eligible for cleanup. Other projects' servers are preserved.

bd dolt killall [flags]

bd dolt pull

Pull commits from the configured Dolt remote into the local database.

Requires a Dolt remote to be configured in the database directory. For Hosted Dolt, set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD environment variables for authentication.

Use --remote to pull from a specific named remote instead of the default. The remote must already exist (see 'bd dolt remote add').

bd dolt pull [flags]

Flags:

      --remote string   Pull from a specific named remote instead of the default

bd dolt push

Push local Dolt commits to the configured remote.

Requires a Dolt remote to be configured in the database directory. For Hosted Dolt, set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD environment variables for authentication.

Use --force to overwrite remote changes (e.g., when the remote has uncommitted changes in its working set).

Use --remote to push to a specific named remote instead of the default. The remote must already exist (see 'bd dolt remote add').

bd dolt push [flags]

Flags:

      --force           Force push (overwrite remote changes)
      --remote string   Push to a specific named remote instead of the default

bd dolt remote

Manage Dolt remotes for push/pull replication.

Subcommands: add <name> <url> Add a new remote list List all configured remotes remove <name> Remove a remote

bd dolt remote [command]

bd dolt remote add

Add a Dolt remote

bd dolt remote add <name> <url> [flags]

Flags:

      --allow-git-origin   Allow adding a Dolt remote whose URL matches the git origin (proceed with a warning instead of aborting)

bd dolt remote list

List configured Dolt remotes

bd dolt remote list [flags]

bd dolt remote remove

Remove a Dolt remote

bd dolt remote remove <name> [flags]

bd dolt set

Set a Dolt configuration value in metadata.json.

Keys: database Database name (default: issue prefix or "beads") host Server host (default: 127.0.0.1) port Server port (auto-detected; override with bd dolt set port <N>) user MySQL user (default: root) data-dir Custom dolt data directory (absolute path; default: .beads/dolt)

Use --update-config to also write to config.yaml for team-wide defaults.

Examples: bd dolt set database myproject bd dolt set host 192.168.1.100 bd dolt set port 3307 --update-config bd dolt set data-dir /home/user/.beads-dolt/myproject

bd dolt set <key> <value> [flags]

Flags:

      --update-config   Also write to config.yaml for team-wide defaults

bd dolt show

Show current Dolt configuration with connection status

bd dolt show [flags]

bd dolt start

Start a dolt sql-server for the current beads project.

The server runs in the background on a per-project port derived from the project path. PID and logs are stored in .beads/.

The server auto-starts transparently when needed, so manual start is rarely required. Use this command for explicit control or diagnostics.

bd dolt start [flags]

bd dolt status

Show the status of the Dolt engine for the current project.

In embedded mode, reports that the Dolt engine runs in-process and shows the on-disk data directory. For beads-managed (local) servers, displays PID, port, and data directory from the local PID file. For externally- managed servers — a shared server (dolt.shared-server: true), a remote dolt_server_host, or a local server managed outside bd (dolt.auto-start: false, e.g. an orchestrator-shared sql-server) — pings the configured endpoint via SQL and reports reachability, server version, and database.

bd dolt status [flags]

bd dolt stop

Stop the dolt sql-server managed by beads for the current project.

This sends a graceful shutdown signal. The server will restart automatically on the next bd command unless auto-start is disabled.

bd dolt stop [flags]

Flags:

      --force   Force stop the server

bd dolt test

Test the connection to the configured Dolt server.

This verifies that:

  1. The server is reachable at the configured host:port
  2. The connection can be established

Use this before switching to server mode to ensure the server is running.

bd dolt test [flags]