CL
CLI Configuration
Configuration hierarchy, config files, environment variables, and persistent settings management
Details
Language / Topic
_UUniversal
Category
Architecture
Rules
balanced
- Implement a clear precedence hierarchy: CLI flags > environment variables > project config file > user config file > defaults.
- Use XDG Base Directory paths for config files: ~/.config/<app>/config.toml on Linux, platform-appropriate paths on macOS/Windows.
- Support environment variable overrides for every config option. Use a consistent prefix: MYAPP_LOG_LEVEL, MYAPP_OUTPUT_FORMAT.
- Generate a default config file with --init or init subcommand. Include comments explaining every option and its default value.
- Support multiple config file formats based on ecosystem norms (TOML for Rust/Go CLIs, YAML for DevOps tools, JSON for JS tooling). Pick one and commit.
- Search for project-level config (.myapprc, myapp.config.toml) by walking up from the current directory to the filesystem root — like how .gitignore works.
- Validate config files on load and report all errors at once with line numbers: "config.toml:12 — invalid value for 'timeout': expected duration, got 'abc'".
- Expose a config show or config list subcommand that prints the resolved configuration with the source of each value (flag, env, file, default).
- Support config profiles: --profile=staging loads [staging] section from the config file. Default to the [default] profile.
- Never store secrets in config files. Use a separate credentials file with restricted permissions (0600) or integrate with OS keychain/secret manager.