Use cli.toml for default start listen address (clockworklabs#4900)

# Description of Changes

This change addresses reviewer feedback on clockworklabs#4576.

As requested by `@cloutiertyler`, here are the changes:

- moved the persistent default listen address for `spacetime start` from
project `spacetime.json` to CLI `cli.toml`
- threaded the already-loaded CLI `Config` into `spacetime start`
instead of introducing a separate project-config lookup in that
subcommand
- preserved precedence so explicit `--listen-addr` / `-l` still wins
over config, and config still wins over the built-in standalone default
- documented the setting in the `spacetime start` CLI reference instead
of the standalone runtime-config page

Behavior precedence is now:

1. Explicit CLI flag, such as `spacetime start --listen-addr
127.0.0.1:5000`
2. `listen_addr` from `cli.toml`
3. Built-in standalone default `0.0.0.0:3000`

Example:

```toml
listen_addr = "0.0.0.0:4000"
```

With that config in place, `spacetime start` will bind to `0.0.0.0:4000`
unless the user passes `--listen-addr` explicitly.

Implementation details:

- added a top-level `listen_addr` field to the existing CLI config
parser and persistence path
- updated `spacetime start` to use the loaded CLI config rather than
reading project config directly
- added/kept focused tests for `--listen-addr` and `-l` detection so
config is only injected when the user did not provide an explicit listen
address
- updated the checked-in CLI reference text for `spacetime start`

Related:

- Follow-up to clockworklabs#4576

# API and ABI breaking changes

None.

This change does not modify any public API or ABI. It only changes where
the CLI reads an optional default value for an existing `spacetime
start` flag.

# Expected complexity level and risk

Complexity: 2/5

This is a small, localized CLI behavior change.

The main interaction point is precedence between forwarded CLI args and
persisted CLI config. Risk is low because this change:

- preserves the existing standalone default when `listen_addr` is absent
- preserves explicit CLI `--listen-addr` and `-l` precedence
- reuses the existing `cli.toml` loading path instead of adding another
config system

# Testing

Completed:

- [x] `cargo fmt --all --check`
- [x] `cargo check -p spacetimedb-cli`
- [x] `cargo clippy -p spacetimedb-cli --all-targets`
- [x] `cargo test -p spacetimedb-cli config::tests --lib`
- [x] `cargo test -p spacetimedb-cli subcommands::start::tests --lib`

Reviewer checks:

- [ ] Run `spacetime start` without `listen_addr` in `cli.toml` and
confirm it still binds to `0.0.0.0:3000`
- [ ] Add `listen_addr = "0.0.0.0:4000"` to `cli.toml`, run `spacetime
start`, and confirm it binds to `0.0.0.0:4000`
- [ ] Run `spacetime start --listen-addr 127.0.0.1:5000` with config
present and confirm the CLI flag still wins

---------

Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Co-authored-by: Zeke Foppa <bfops@users.noreply.github.com>

Author: 4 people

crates/cli/src/config.rs

@@ -12,6 +12,7 @@ use toml_edit::ArrayOfTables;
 const DEFAULT_SERVER_KEY: &str = "default_server";
 const WEB_SESSION_TOKEN_KEY: &str = "web_session_token";
 const SPACETIMEDB_TOKEN_KEY: &str = "spacetimedb_token";
+const LISTEN_ADDR_KEY: &str = "listen_addr";
 const SERVER_CONFIGS_KEY: &str = "server_configs";
 const NICKNAME_KEY: &str = "nickname";
 const HOST_KEY: &str = "host";
@@ -124,6 +125,7 @@ pub struct RawConfig {
     // TODO: Move these IDs/tokens out of config so we're no longer storing sensitive tokens in a human-edited file.
     web_session_token: Option<String>,
     spacetimedb_token: Option<String>,
+    listen_addr: Option<String>,
 }
 
 #[derive(Debug, Clone)]
@@ -173,6 +175,7 @@ impl RawConfig {
             server_configs: vec![maincloud, local],
             web_session_token: None,
             spacetimedb_token: None,
+            listen_addr: None,
         }
     }
 
@@ -461,6 +464,7 @@ impl TryFrom<&toml_edit::DocumentMut> for RawConfig {
         let default_server = read_opt_str(value, DEFAULT_SERVER_KEY)?;
         let web_session_token = read_opt_str(value, WEB_SESSION_TOKEN_KEY)?;
         let spacetimedb_token = read_opt_str(value, SPACETIMEDB_TOKEN_KEY)?;
+        let listen_addr = read_opt_str(value, LISTEN_ADDR_KEY)?;
 
         let mut server_configs = Vec::new();
         if let Some(arr) = read_table(value, SERVER_CONFIGS_KEY)? {
@@ -474,6 +478,7 @@ impl TryFrom<&toml_edit::DocumentMut> for RawConfig {
             server_configs,
             web_session_token,
             spacetimedb_token,
+            listen_addr,
         })
     }
 }
@@ -483,6 +488,10 @@ impl Config {
         self.home.default_server.as_deref()
     }
 
+    pub fn start_listen_addr(&self) -> Option<&str> {
+        self.home.listen_addr.as_deref()
+    }
+
     /// Add a `ServerConfig` to the home configuration.
     ///
     /// Returns an `Err` on name conflict,
@@ -654,11 +663,13 @@ impl Config {
             server_configs: old_server_configs,
             web_session_token,
             spacetimedb_token,
+            listen_addr,
         } = &self.home;
 
         set_value(DEFAULT_SERVER_KEY, default_server.as_deref());
         set_value(WEB_SESSION_TOKEN_KEY, web_session_token.as_deref());
         set_value(SPACETIMEDB_TOKEN_KEY, spacetimedb_token.as_deref());
+        set_value(LISTEN_ADDR_KEY, listen_addr.as_deref());
 
         // Short-circuit if there are no servers.
         if old_server_configs.is_empty() {
@@ -929,6 +940,10 @@ protocol = "https"
 "#;
     const CONFIG_EMPTY: &str = r#"
 # Comment end
+"#;
+    const CONFIG_LISTEN_ADDR: &str = r#"listen_addr = "0.0.0.0:4000"
+
+# Comment end
 "#;
     const CONFIG_INVALID_START: &str = r#"
 this="not a valid key"
@@ -992,6 +1007,10 @@ default_server = "local"
     fn test_config_adds() -> ResultTest<()> {
         check_config(CONFIG_FULL, CONFIG_FULL, |_| Ok(()))?;
         check_config(CONFIG_EMPTY, CONFIG_EMPTY, |_| Ok(()))?;
+        check_config(CONFIG_EMPTY, CONFIG_LISTEN_ADDR, |config| {
+            config.home.listen_addr = Some("0.0.0.0:4000".to_string());
+            Ok(())
+        })?;
 
         check_config(CONFIG_EMPTY, CONFIG_FULL_NO_COMMENT, |config| {
             config.home.default_server = Some("local".to_string());
@@ -1057,6 +1076,14 @@ default_server = "local"
                 found: Box::new(toml_edit::value(1)),
             },
         )?;
+        check_invalid(
+            r#"listen_addr =1"#,
+            CliError::ConfigType {
+                key: "listen_addr".to_string(),
+                kind: "string",
+                found: Box::new(toml_edit::value(1)),
+            },
+        )?;
         check_invalid(
             r#"
 [server_configs]

crates/cli/src/lib.rs

@@ -64,7 +64,7 @@ pub async fn exec_subcommand(
         "build" => build::exec(config, args).await.map(drop),
         "server" => server::exec(config, paths, args).await,
         "subscribe" => subscribe::exec(config, args).await,
-        "start" => return start::exec(paths, args).await,
+        "start" => return start::exec(config, paths, args).await,
         "login" => login::exec(config, args).await,
         "logout" => logout::exec(config, args).await,
         "version" => return subcommands::version::exec(paths, root_dir, args).await,

crates/cli/src/subcommands/start.rs

@@ -7,6 +7,7 @@ use clap::{Arg, ArgMatches};
 use spacetimedb_paths::SpacetimePaths;
 
 use crate::util::resolve_sibling_binary;
+use crate::Config;
 
 pub fn cli() -> clap::Command {
     clap::Command::new("start")
@@ -15,6 +16,11 @@ pub fn cli() -> clap::Command {
             "\
 Start a local SpacetimeDB instance
 
+Set a persistent default listen address in cli.toml with:
+    listen_addr = \"0.0.0.0:4000\"
+
+When present, `listen_addr` is used unless `--listen-addr` is passed explicitly.
+
 Run `spacetime start --help` to see all options.",
         )
         .disable_help_flag(true)
@@ -40,9 +46,9 @@ enum Edition {
     Cloud,
 }
 
-pub async fn exec(paths: &SpacetimePaths, args: &ArgMatches) -> anyhow::Result<ExitCode> {
+pub async fn exec(config: Config, paths: &SpacetimePaths, args: &ArgMatches) -> anyhow::Result<ExitCode> {
     let edition = args.get_one::<Edition>("edition").unwrap();
-    let args = args.get_many::<OsString>("args").unwrap_or_default();
+    let forwarded_args: Vec<OsString> = args.get_many::<OsString>("args").unwrap_or_default().cloned().collect();
     let bin_name = match edition {
         Edition::Standalone => "spacetimedb-standalone",
         Edition::Cloud => "spacetimedb-cloud",
@@ -53,8 +59,15 @@ pub async fn exec(paths: &SpacetimePaths, args: &ArgMatches) -> anyhow::Result<E
         .arg("--data-dir")
         .arg(&paths.data_dir)
         .arg("--jwt-key-dir")
-        .arg(&paths.cli_config_dir)
-        .args(args);
+        .arg(&paths.cli_config_dir);
+
+    if let Some(config_addr) = config.start_listen_addr() {
+        // Prepend the config default; standalone takes the last --listen-addr value,
+        // so an explicit flag in forwarded_args wins.
+        cmd.arg("--listen-addr").arg(config_addr);
+    }
+
+    cmd.args(&forwarded_args);
 
     exec_replace(&mut cmd).with_context(|| format!("exec failed for {}", bin_path.display()))
 }

crates/smoketests/tests/smoketests/cli/server.rs

@@ -1,12 +1,102 @@
 //! CLI server command tests
 
 use spacetimedb_guard::{ensure_binaries_built, SpacetimeDbGuard};
-use std::process::Command;
+use std::fs;
+use std::io::Read;
+use std::net::TcpListener;
+use std::path::Path;
+use std::process::{Child, Command, Output, Stdio};
+use std::time::{Duration, Instant};
 
 fn cli_cmd() -> Command {
     Command::new(ensure_binaries_built())
 }
 
+fn output_stdout(output: &Output) -> String {
+    String::from_utf8_lossy(&output.stdout).to_string()
+}
+
+fn output_stderr(output: &Output) -> String {
+    String::from_utf8_lossy(&output.stderr).to_string()
+}
+
+fn assert_success(output: &Output, context: &str) {
+    assert!(
+        output.status.success(),
+        "{context} failed:\nstdout: {}\nstderr: {}",
+        output_stdout(output),
+        output_stderr(output),
+    );
+}
+
+fn free_local_port() -> u16 {
+    let listener = TcpListener::bind(("127.0.0.1", 0)).expect("failed to bind local port");
+    let port = listener.local_addr().expect("missing local addr").port();
+    drop(listener);
+    port
+}
+
+fn write_cli_toml(root_dir: &Path, listen_addr: &str) {
+    let config_dir = root_dir.join("config");
+    fs::create_dir_all(&config_dir).expect("failed to create config dir");
+    fs::write(
+        config_dir.join("cli.toml"),
+        format!("listen_addr = \"{listen_addr}\"\n"),
+    )
+    .expect("failed to write cli.toml");
+}
+
+fn spawn_start(root_dir: &Path, extra_args: &[&str]) -> Child {
+    let root_dir = root_dir.to_str().expect("root dir should be utf8");
+    cli_cmd()
+        .args(["--root-dir", root_dir, "start"])
+        .args(extra_args)
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .expect("failed to spawn spacetime start")
+}
+
+fn ping_url(url: &str) -> Output {
+    cli_cmd()
+        .args(["server", "ping", url])
+        .output()
+        .expect("failed to execute server ping")
+}
+
+fn wait_for_server(url: &str, child: &mut Child, timeout: Duration) {
+    let start = Instant::now();
+    loop {
+        let ping = ping_url(url);
+        if ping.status.success() {
+            return;
+        }
+
+        if let Some(status) = child.try_wait().expect("failed to poll child") {
+            let mut stdout = String::new();
+            let mut stderr = String::new();
+            child.stdout.take().unwrap().read_to_string(&mut stdout).unwrap();
+            child.stderr.take().unwrap().read_to_string(&mut stderr).unwrap();
+            panic!(
+                "spacetime start exited early ({status}) while waiting for {url}:\nstdout: {stdout}\nstderr: {stderr}"
+            );
+        }
+
+        if start.elapsed() > timeout {
+            child.kill().ok();
+            let _ = child.wait();
+            panic!("timed out waiting for spacetime start to answer on {url}");
+        }
+
+        std::thread::sleep(Duration::from_millis(200));
+    }
+}
+
+fn stop_child(mut child: Child) {
+    child.kill().ok();
+    let _ = child.wait();
+}
+
 #[test]
 fn cli_can_ping_spacetimedb_on_disk() {
     let spacetime = SpacetimeDbGuard::spawn_in_temp_data_dir();
@@ -20,3 +110,41 @@ fn cli_can_ping_spacetimedb_on_disk() {
         String::from_utf8_lossy(&output.stderr)
     );
 }
+
+#[test]
+fn cli_start_uses_listen_addr_from_cli_toml() {
+    let root = tempfile::tempdir().expect("failed to create tempdir");
+    let port = free_local_port();
+    let listen_addr = format!("127.0.0.1:{port}");
+    let url = format!("http://{listen_addr}");
+    write_cli_toml(root.path(), &listen_addr);
+
+    let mut child = spawn_start(root.path(), &[]);
+    wait_for_server(&url, &mut child, Duration::from_secs(20));
+
+    let ping = ping_url(&url);
+    assert_success(&ping, "server ping after config-based start");
+    stop_child(child);
+}
+
+#[test]
+fn cli_start_explicit_listen_addr_overrides_cli_toml() {
+    let root = tempfile::tempdir().expect("failed to create tempdir");
+    let config_port = free_local_port();
+    let mut explicit_port = free_local_port();
+    while explicit_port == config_port {
+        explicit_port = free_local_port();
+    }
+
+    let config_addr = format!("127.0.0.1:{config_port}");
+    let explicit_addr = format!("127.0.0.1:{explicit_port}");
+    let explicit_url = format!("http://{explicit_addr}");
+    write_cli_toml(root.path(), &config_addr);
+
+    let mut child = spawn_start(root.path(), &["--listen-addr", &explicit_addr]);
+    wait_for_server(&explicit_url, &mut child, Duration::from_secs(20));
+
+    let ping = ping_url(&explicit_url);
+    assert_success(&ping, "server ping after explicit listen-addr override");
+    stop_child(child);
+}

docs/docs/00300-resources/00200-reference/00100-cli-reference/00100-cli-reference.md

@@ -615,6 +615,11 @@ Subscribe to SQL queries on the database. WARNING: This command is UNSTABLE and
 
 Start a local SpacetimeDB instance
 
+Set a persistent default listen address in cli.toml with:
+    listen_addr = "0.0.0.0:4000"
+
+When present, `listen_addr` is used unless `--listen-addr` is passed explicitly.
+
 Run `spacetime start --help` to see all options.
 
 **Usage:** `spacetime start [OPTIONS] [args]...`