From aa39d07728ddb7e2015e2bd34bdea0e6d7b3c309 Mon Sep 17 00:00:00 2001 From: postoso Date: Wed, 19 Aug 2026 13:12:08 -0400 Subject: [PATCH] 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 Co-authored-by: Bee --- cmd/bd/dolt.go | 16 ++++++++++------ cmd/bd/dolt_help_auth_test.go | 17 +++++++++++++++++ 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/cmd/bd/dolt.go b/cmd/bd/dolt.go index 574874a11..00037fec8 100644 --- a/cmd/bd/dolt.go +++ b/cmd/bd/dolt.go @@ -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 Set a configuration value bd dolt test Test server connection diff --git a/cmd/bd/dolt_help_auth_test.go b/cmd/bd/dolt_help_auth_test.go index 6aeb3e446..eb5cd3a24 100644 --- a/cmd/bd/dolt_help_auth_test.go +++ b/cmd/bd/dolt_help_auth_test.go @@ -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) + } + } +}