Configuration

Environment overrides

Environment overrides are opt-in. Once enabled, per-key reads check the environment first and fall back to the config file only when the matching variable is absent.

Enable a prefix

Rust

let cfg = DotCfg::new("mytool")
    .with_env_prefix("myapp");

let port: u16 = cfg.get_as("port")?;

The key port maps to MYAPP_PORT. Nested dots become underscores, so user.name maps to MYAPP_USER_NAME. Both the prefix and key are uppercased for the environment-variable name.

Precedence

Environment variable→Config file

If MYAPP_PORT exists, its value wins. If it is absent, dotcfg reads port from the file. A malformed environment value is an error—it is not silently ignored in favor of the file.

Typed environment values

Environment variables start as strings, so get_as() interprets them for the requested Rust type.

Numbers

Parsed using Rust's normal string parsing.

Booleans

true/false and 1/0, case-insensitive.

Sequences

Comma-separated: MYAPP_TAGS=cli,fast.

Option<T>

A variable that exists is treated as Some(T).

Structs and maps

A single environment variable cannot represent a struct or map. Express those values as nested keys instead—for example, use MYAPP_SERVER_HOST for server.host.

Writes never touch the environment

set() and set_val() always write to the config file. Environment variables only participate in reads, keeping persistence explicit and predictable.