docs(cli): describe embedded mode in bd dolt help (#5852)

Embedded Dolt is the default and has no sql-server, but the help says beads
uses one for all database operations and auto-starts it transparently. That
points users and agents at a server that cannot exist, usually via
bd dolt start/stop/set/test, all of which refuse on an embedded database.

State the embedded default, scope the server-only subcommands, and mark
status and show as working in both modes. Help text only, no behavior change.

Refs #5741

Co-authored-by: postoso <postoso@users.noreply.github.com>
Co-authored-by: Bee <bee@ghosttrack.com>
This commit is contained in:
postoso 2026-08-19 13:12:08 -04:00 • committed by GitHub
commit aa39d07728
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 27 additions and 6 deletions

View file

@ -34,17 +34,21 @@ var doltCmd = &cobra.Command{
Short: "Configure Dolt database settings",
Long: `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.
Beads runs Dolt embedded (in-process) by default: there is no sql-server and
nothing is auto-started. A database only uses a dolt sql-server when it is
configured for one: shared-server mode, an explicit server mode, or a
non-localhost dolt_server_host. The server-only commands below fail with
"not supported in embedded mode (no Dolt server)" on an embedded database.
Server lifecycle:
Server lifecycle (server mode only):
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:
Diagnostics (both modes):
bd dolt status Show Dolt engine status (embedded: in-process, data dir)
bd dolt show Show current Dolt configuration with connection test
Configuration (server mode only):
bd dolt set <k> <v> Set a configuration value
bd dolt test Test server connection

View file

@ -22,3 +22,20 @@ func TestDoltHelpMentionsRemoteAuth(t *testing.T) {
t.Error("dolt set help should explain why password is not a set key")
}
}
// GH#5741: the default is embedded Dolt, so the help must not describe a
// sql-server as the architecture every database uses, and must scope the
// server-only subcommands.
func TestDoltHelpDescribesEmbeddedDefault(t *testing.T) {
if strings.Contains(doltCmd.Long, "Beads uses a dolt sql-server for all database operations") {
t.Error("dolt help still describes a sql-server as the architecture for all databases")
}
for _, needle := range []string{
"embedded (in-process) by default",
"server mode only",
} {
if !strings.Contains(doltCmd.Long, needle) {
t.Errorf("dolt help missing %q", needle)
}
}
}