beads/website/versioned_docs/version-1.0.4/cli-reference/dolt.md
matt wilkie c97c416242
docs: publish v1.0.4 docs snapshot (#3845)
* docs: publish v1.0.4 docs snapshot

* release: guard docs version snapshots
2026-05-09 14:42:25 -07:00

304 lines
7.6 KiB
Markdown

---
id: dolt
title: bd dolt
slug: /cli-reference/dolt
sidebar_position: 999
---
<!-- AUTO-GENERATED: do not edit manually -->
Generated from `bd help --doc dolt`
## bd 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 &lt;k&gt; &lt;v&gt; 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 &lt;name&gt; &lt;url&gt; Add a Dolt remote
bd dolt remote list List configured remotes
bd dolt remote remove &lt;name&gt; 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 &lt;N&gt;)
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
```
### 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_*, doctest_*, doctortest_*, beads_pt*, beads_vr*, beads_t*
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
```
### 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 &lt;name&gt; &lt;url&gt; Add a new remote
list List all configured remotes
remove &lt;name&gt; Remove a remote
```
bd dolt remote
```
#### bd dolt remote add
Add a Dolt remote (both SQL server and CLI)
```
bd dolt remote add <name> <url>
```
#### bd dolt remote list
List configured Dolt remotes (SQL server + CLI)
```
bd dolt remote list
```
#### bd dolt remote remove
Remove a Dolt remote (both SQL server and CLI)
```
bd dolt remote remove <name> [flags]
```
**Flags:**
```
--force Force remove even when SQL and CLI URLs conflict
```
### 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 &lt;N&gt;)
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
```
### 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
```
### 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 — either 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
```
### 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
```