From 7e341b6e3c8b66ef2a3d68f0fd00444f518f7851 Mon Sep 17 00:00:00 2001 From: Bot Date: Fri, 23 Oct 2026 23:33:15 +0800 Subject: [PATCH] docs(config): document CLI config vs env precedence (#2343) --- README.md | 16 +++++++++++ cmd/soroban-cli/src/cli.rs | 31 +++++++++++++++++++++ cmd/soroban-cli/src/commands/cfg/mod.rs | 8 +++++- cmd/soroban-cli/src/commands/mod.rs | 17 +++++++++-- cmd/soroban-cli/src/commands/skill/SKILL.md | 10 +++++++ 5 files changed, 79 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 19b689cbb4..8dbc1e39fc 100644 --- a/README.md +++ b/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 `, `stellar keys use `, `stellar fees use `, 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). diff --git a/cmd/soroban-cli/src/cli.rs b/cmd/soroban-cli/src/cli.rs index 30171ee713..78ad2bd22e 100644 --- a/cmd/soroban-cli/src/cli.rs +++ b/cmd/soroban-cli/src/cli.rs @@ -204,3 +204,34 @@ fn set_env_value_from_config(name: &str, value: Option) 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); + } +} diff --git a/cmd/soroban-cli/src/commands/cfg/mod.rs b/cmd/soroban-cli/src/commands/cfg/mod.rs index c182566d41..3ba5db7bbd 100644 --- a/cmd/soroban-cli/src/commands/cfg/mod.rs +++ b/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. diff --git a/cmd/soroban-cli/src/commands/mod.rs b/cmd/soroban-cli/src/commands/mod.rs index 106c054b3d..77358f523e 100644 --- a/cmd/soroban-cli/src/commands/mod.rs +++ b/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), diff --git a/cmd/soroban-cli/src/commands/skill/SKILL.md b/cmd/soroban-cli/src/commands/skill/SKILL.md index 80bf2d8275..ee60f08e0d 100644 --- a/cmd/soroban-cli/src/commands/skill/SKILL.md +++ b/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 `) 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 --rpc-url --network-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 `) 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`