docs(config): document CLI config vs env precedence

README.md

@@ -10,6 +10,7 @@ This repo is home to the Stellar CLI, the command-line multi-tool for running an
 - [Cookbook](#cookbook)
 - [Install](#install)
 - [Autocomplete](#autocomplete)
+- [Configuration and Precedence](#configuration-and-precedence)
 - [Latest Release](#latest-release)
 - [Upcoming Features](#upcoming-features)
 - [To Contribute](#to-contribute)
@@ -110,6 +111,21 @@ To enable autocomplete permanently, run:
 echo "source <(stellar completion --shell bash)" >> ~/.bashrc
 ```
 
+## Configuration and Precedence
+
+The Stellar CLI resolves configuration values (such as the target network, source identity account, and fees) according to the following strict order of precedence:
+
+1. **Command-Line Arguments & Flags**: Options passed directly on the command line (e.g. `--network testnet`, `--source alice`) always take highest precedence.
+2. **Environment Variables**: Environment variables (e.g. `STELLAR_NETWORK`, `STELLAR_ACCOUNT`, `STELLAR_INCLUSION_FEE`) override configured file defaults.
+3. **CLI Configuration Defaults**: Defaults configured via `stellar network use <name>`, `stellar keys use <name>`, `stellar fees use <stroops>`, or saved in `config.toml`.
+4. **Built-in Defaults**: Built-in fallback defaults (e.g. `testnet` network, 100 stroops base inclusion fee).
+
+To inspect the currently active environment variables and defaults along with their source, run:
+
+```sh
+stellar env
+```
+
 ## Latest Release
 
 For the latest release, see [releases](https://github.com/stellar/stellar-cli/releases).

cmd/soroban-cli/src/cli.rs

@@ -204,3 +204,34 @@ fn set_env_value_from_config<T: std::fmt::Display>(name: &str, value: Option<T>)
         std::env::set_var(format!("{name}_SOURCE"), "use");
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_set_env_value_from_config_precedence() {
+        let test_var = "TEST_STELLAR_PRECEDENCE_VAR";
+        let test_var_source = format!("{test_var}_SOURCE");
+
+        // Clean up before test
+        std::env::remove_var(test_var);
+        std::env::remove_var(&test_var_source);
+
+        // 1. When env is unset, config default sets the env var with SOURCE='use'
+        set_env_value_from_config(test_var, Some("config_default_val"));
+        assert_eq!(std::env::var(test_var).unwrap(), "config_default_val");
+        assert_eq!(std::env::var(&test_var_source).unwrap(), "use");
+
+        // 2. When env var is explicitly set, config does NOT override it (env > config)
+        std::env::set_var(test_var, "explicit_env_val");
+        std::env::remove_var(&test_var_source);
+        set_env_value_from_config(test_var, Some("new_config_val"));
+        assert_eq!(std::env::var(test_var).unwrap(), "explicit_env_val");
+        assert!(std::env::var(&test_var_source).is_err());
+
+        // Clean up
+        std::env::remove_var(test_var);
+        std::env::remove_var(&test_var_source);
+    }
+}

cmd/soroban-cli/src/commands/cfg/mod.rs

@@ -3,7 +3,13 @@ mod migrate;
 
 use clap::Parser;
 
-/// Migrate config from previous versions.
+/// Manage CLI configuration.
+///
+/// Precedence order for CLI configuration:
+/// 1. Command-line options & flags (e.g. `--network`, `--source`)
+/// 2. Environment variables (e.g. `STELLAR_NETWORK`, `STELLAR_ACCOUNT`)
+/// 3. CLI configuration defaults (set via `stellar network/keys/fees use` or `config.toml`)
+/// 4. Built-in defaults
 #[derive(Debug, Parser)]
 pub enum Cmd {
     /// Migrate the local configuration to the global directory.

cmd/soroban-cli/src/commands/mod.rs

@@ -160,8 +160,15 @@ pub enum Cmd {
 
     /// Prints the environment variables
     ///
-    /// Prints to stdout in a format that can be used as .env file. Environment
-    /// variables have precedence over defaults.
+    /// Prints to stdout in a format that can be used as .env file.
+    ///
+    /// Configuration precedence in the CLI:
+    /// 1. Command-line flags and options (e.g. `--network`, `--source`)
+    /// 2. Environment variables (e.g. `STELLAR_NETWORK`, `STELLAR_ACCOUNT`)
+    /// 3. CLI configuration defaults (set via `stellar network use`, `stellar keys use`, or `config.toml`)
+    /// 4. Built-in defaults
+    ///
+    /// Environment variables have precedence over CLI configuration defaults.
     ///
     /// By default, secret values are concealed. To display them, use `--reveal`.
     ///
@@ -185,6 +192,12 @@ pub enum Cmd {
     Container(container::Cmd),
 
     /// Manage CLI configuration
+    ///
+    /// Configuration precedence in the CLI:
+    /// 1. Command-line flags and options (highest precedence)
+    /// 2. Environment variables (e.g. `STELLAR_NETWORK`, `STELLAR_ACCOUNT`)
+    /// 3. CLI configuration defaults (set via `stellar network/keys/fees use` or `config.toml`)
+    /// 4. Built-in defaults
     #[command(subcommand)]
     Config(cfg::Cmd),
 

cmd/soroban-cli/src/commands/skill/SKILL.md

@@ -21,6 +21,11 @@ Set a default network once instead of repeating `--network`, `--rpc-url`, and `-
 
 After this, other commands use that network by default and you can omit the network flags entirely.
 
+> **Precedence Note**: CLI values follow strict precedence:
+> 1. CLI options/flags (e.g. `--network <name>`) take highest precedence.
+> 2. Environment variables (e.g. `STELLAR_NETWORK`, `STELLAR_RPC_URL`) override configured defaults.
+> 3. CLI configuration defaults set via `stellar network use` apply when neither flags nor env vars are provided.
+
 - List configured networks: `stellar network ls`
 - Add a custom network: `stellar network add <name> --rpc-url <url> --network-passphrase <passphrase>`
 - Clear the default: `stellar network unset`
@@ -36,6 +41,11 @@ Create named identities and select a default with `stellar keys use`, just like
 
 After `stellar keys use`, other commands sign and pay with that identity, so you can omit the source flag entirely.
 
+> **Precedence Note**: Identity values follow strict precedence:
+> 1. CLI options/flags (e.g. `--source <name>`) take highest precedence.
+> 2. Environment variables (e.g. `STELLAR_ACCOUNT`) override configured defaults.
+> 3. CLI configuration defaults set via `stellar keys use` apply when neither flags nor env vars are provided.
+
 - List identities: `stellar keys ls`
 - Show an address: `stellar keys address alice`
 - Clear the default: `stellar keys unset`