You need four sources of truth
You're writing a web server. Hardcoding port: 8080 works until your teammate asks to run two instances locally. You add a config file. That works until you deploy to a container where the environment variable PORT is already set by the orchestrator. Now you need CLI flags for quick overrides during debugging. You end up with four sources of truth fighting for control.
The solution isn't picking one source. It's layering them so each level can override the one below it. This pattern gives you flexibility without chaos. You get sensible defaults, user-friendly files, deployment-friendly environment variables, and operator-friendly CLI flags. The hierarchy decides which value wins when conflicts arise.
The hierarchy pattern
Think of configuration like a set of nested boxes. The innermost box holds your hard-coded defaults. That's the baseline. The next box wraps around it and contains values from a file. If the file has a value, it covers the default. The next box holds environment variables, covering the file. The outermost box holds command-line arguments.
When you ask for a value, you check the outermost box first. If it's empty, you peel back a layer and check the next one. This pattern is called a configuration hierarchy. It ensures that explicit user input always beats implicit settings. A flag typed on the command line should override a value in a file. A value in a file should override a default in the code.
Peel the layers. The outermost value always wins.
Minimal implementation
The code follows the hierarchy order. You start with defaults, then apply overrides from the file, then environment variables, then CLI flags. Each step only updates the config if the source provides valid data.
struct Config {
port: u16,
debug: bool,
}
fn main() {
// 1. Defaults
// Start with hard-coded values.
// These apply if no other source provides data.
let mut config = Config {
port: 8080,
debug: false,
};
// 2. File
// Load overrides from a config file.
// Only update fields if the file exists and parses successfully.
if let Ok(file_config) = load_file_config() {
config.port = file_config.port;
config.debug = file_config.debug;
}
// 3. Environment Variables
// Env vars override both defaults and file values.
// Use `if let` to handle missing variables gracefully.
if let Ok(port_str) = std::env::var("APP_PORT") {
if let Ok(port) = port_str.parse::<u16>() {
config.port = port;
}
}
if let Ok(debug_str) = std::env::var("APP_DEBUG") {
config.debug = debug_str == "true";
}
// 4. CLI Flags
// CLI flags have the highest precedence.
// Skip the first argument, which is the program name.
for arg in std::env::args().skip(1) {
if let Some(value) = arg.strip_prefix("--port=") {
if let Ok(port) = value.parse::<u16>() {
config.port = port;
}
} else if arg == "--debug" {
config.debug = true;
}
}
println!("Final config: port={}, debug={}", config.port, config.debug);
}
/// Simulates loading configuration from a file.
/// Returns an error if the file is missing or malformed.
fn load_file_config() -> Result<Config, std::io::Error> {
// In a real app, parse a TOML or JSON file here.
// Return an error if the file is missing or malformed.
Err(std::io::Error::new(std::io::ErrorKind::NotFound, "config.toml not found"))
}
Order is law. Swap the blocks and you break the precedence.
How the precedence flows
The compiler sees config as a mutable struct. Each step updates specific fields. The order matters. If you swap the env block and the CLI block, CLI flags won't override environment variables. The runtime behavior follows the code flow.
Defaults initialize the struct. The file check uses if let to handle the absence of a file gracefully. Environment variables use std::env::var, which returns an error if the variable isn't set. The if let pattern discards that error without crashing. CLI parsing iterates over arguments, skipping the program name. Each source only touches the config if it has valid data. This prevents partial updates from breaking the structure.
If APP_PORT is set to "abc", parse::<u16>() returns an error. The inner if let catches that error and leaves config.port unchanged. The app keeps running with the previous value. This is safe for optional overrides. For required values, you'd want to fail fast.
Swap the blocks and you break the precedence.
Real-world structure
Production code needs better error handling. You can't silently ignore a malformed config file. You also want to return the config from a function so other parts of the app can use it. The Result type lets you propagate errors up the call stack.
use std::env;
use std::path::Path;
/// Represents the application configuration.
/// Fields are public for demonstration; consider using getters in production.
pub struct AppConfig {
pub port: u16,
pub debug: bool,
pub host: String,
}
/// Builds configuration from multiple sources with precedence.
/// Order: Defaults < File < Env < CLI.
pub fn build_config(config_path: Option<&Path>) -> Result<AppConfig, Box<dyn std::error::Error>> {
// 1. Defaults
// Initialize with safe baseline values.
let mut config = AppConfig {
port: 8080,
debug: false,
host: "127.0.0.1".to_string(),
};
// 2. File
// Only attempt file load if a path is provided.
// This allows the app to run without a file if other sources suffice.
if let Some(path) = config_path {
if path.exists() {
let content = std::fs::read_to_string(path)?;
// Placeholder for TOML parsing.
// In real code, use `toml::from_str::<AppConfig>(&content)?`.
// Here we simulate a partial override.
config.debug = true;
}
}
// 3. Environment Variables
// Env vars override file and defaults.
// Use `var` to fail if required, or `var_os` for sensitive data.
if let Ok(val) = env::var("APP_PORT") {
config.port = val.parse()?;
}
if let Ok(val) = env::var("APP_DEBUG") {
config.debug = val == "true" || val == "1";
}
if let Ok(val) = env::var("APP_HOST") {
config.host = val;
}
// 4. CLI Flags
// CLI has highest precedence.
// Use a crate like `clap` in production for robust parsing.
let args: Vec<String> = env::args().collect();
for arg in args.iter().skip(1) {
match arg.as_str() {
"--debug" => config.debug = true,
a if a.starts_with("--port=") => {
config.port = a.trim_start_matches("--port=").parse()?;
}
a if a.starts_with("--host=") => {
config.host = a.trim_start_matches("--host=").to_string();
}
_ => {} // Ignore unknown flags for this example.
}
}
Ok(config)
}
Fail fast. A broken config is better than a broken runtime.
Parsing and type safety
Rust's type system helps here. The Config struct enforces that port is always a u16. You can't accidentally store a string. When parsing, you convert immediately. This catches errors at the boundary.
If you try to assign a String to a u16 field, you get E0308 (mismatched types). The compiler rejects the code before it runs. Always parse into the target type. This prevents runtime surprises. If you stored raw strings and parsed later, you'd get errors deep in the logic. Parse early. Store typed values.
Convention aside: The community calls this "parse at the boundary". Convert external data to internal types as soon as possible. This keeps the rest of your code free from parsing logic.
Parse at the boundary. Trust the types.
Environment variables and secrets
Environment variables are the standard way to pass configuration in containers. The orchestrator sets them, and the app reads them. This keeps config separate from code. It also makes it easy to change values without rebuilding the binary.
std::env::var returns Result<String, VarError>. VarError has two variants: NotPresent and NotUnicode. NotPresent is expected for optional vars. NotUnicode is rare but possible. If you need to handle non-unicode paths or values, use var_os. For config values, unicode is usually safe.
Convention aside: Name environment variables with a prefix matching your app name. APP_PORT is better than PORT. This prevents collisions when your app runs alongside others. Convention aside: Keep secrets out of config files. Use environment variables or a secret manager for passwords and API keys. Never commit files containing sensitive data to version control.
Never commit secrets. Use the environment.
CLI flags and robustness
Manual CLI parsing is brittle. --port=80 works. -p 80 doesn't. --port 80 doesn't. Crates like clap handle this. They support short flags, long flags, help messages, and validation. If you write manual parsing, document the format clearly. Or use clap for CLI and manual parsing for the rest. Mixing approaches is common.
Convention aside: Use clap for any app that operators will run manually. The ergonomics are worth the dependency. For internal tools or daemons where config comes from files and env vars, manual parsing might suffice.
Document your flags. Operators will thank you.
When to write this yourself
Rust has crates like config that do this automatically. They handle merging, multiple formats, and hot-reloading. Why write it manually? Manual implementation teaches the precedence logic. It avoids a dependency for simple apps. It gives you exact control over error messages.
Crates are great for complex apps. They save time when you need TOML, JSON, YAML, and env vars all merging together. But they add compile time and a dependency graph. For a small tool, manual hierarchy is lighter. You get exactly what you need. You understand every line.
Start simple. Add complexity only when the use case demands it.
Decision matrix
Use hard-coded defaults when you need a baseline that guarantees the app runs out of the box. Use configuration files when users need to set many options at once or share settings across environments. Use environment variables when deploying to containers or cloud platforms where the orchestrator manages secrets and dynamic values. Use CLI flags when operators need quick overrides for debugging or one-off runs. Use a dedicated crate like config or dotenvy when the hierarchy gets complex or you need support for multiple file formats. Reach for std::env and manual parsing only when dependencies are forbidden or the config is trivial.
Start simple. Add complexity only when the use case demands it.