envigil 0.1.0

Keep vigil over your environment — load, parse, and validate env vars with zero dependencies.
Documentation

envigil

Keep vigil over your environment.

Load, parse, and validate environment variables with zero dependencies and first-class error reporting.

Crates.io Downloads Docs.rs License MSRV


Why envigil?

std::env envy envconfig dotenvy figment config envigil
Zero dependencies ✅ ❌ ❌ ❌ ❌ ❌ ✅
Typed parsing ❌ ✅ ✅ ❌ ✅ ✅ ✅
Semantic validation ❌ ❌ ❌ ❌ ❌ ❌ ✅
Multi-error reporting ❌ ❌ ❌ ❌ ❌ ❌ ✅
Secret redaction ❌ ❌ ❌ ❌ ❌ ❌ ✅
.env file support ❌ ❌ ❌ ✅ ✅ ✅ ✅ (feature)
Derive macro ❌ ✅ ✅ ❌ ❌ ❌ ✅ (feature)
Layered config ❌ ❌ ❌ ❌ ✅ ✅ ❌
CLI args ❌ ❌ ❌ ❌ ❌ ❌ ❌
Async support ❌ ❌ ❌ ❌ ✅ ✅ ❌
MSRV — 1.60+ — 1.65+ 1.70+ 1.75+ 1.85
Actively maintained ✅ ⚠️ ❌ ✅ ✅ ✅ 🆕

envigil is not a replacement for figment or config (layered providers, async, file formats). It is a lightweight alternative to envy / envconfig for those who need validation, multi-error reporting, and secret redaction without pulling in dependencies.

The core crate is std-only. No serde, no syn, no anyhow. Proc-macro and .env support are opt-in feature flags.

Quick start

[dependencies]
envigil = "0.1"

Builder API

use envigil::{EnvSource, VarBuilder};
use envigil::validate;
use std::time::Duration;

fn main() -> Result<(), envigil::Error> {
    let cfg = EnvSource::new()
        .prefix("APP_")
        .declare(
            VarBuilder::new("PORT", |v| v.parse::<u16>().map_err(|e| e.to_string()))
                .default(8080)
                .validate(validate::range(1..=65535)),
        )
        .declare(
            VarBuilder::new("DATABASE_URL", |v| Ok(v.to_owned()))
                .required()
                .secret(),
        )
        .declare(
            VarBuilder::new("TIMEOUT_SECS", envigil::parse::secs)
                .default(Duration::from_secs(30)),
        )
        .load()?;

    let port: &u16 = cfg.get("APP_PORT")?;
    let url: &envigil::Secret<String> = cfg.get("APP_DATABASE_URL")?;

    println!("listening on :{port}");
    println!("db = {url}"); // prints: db = [REDACTED]

    Ok(())
}

Derive API

[dependencies]
envigil = { version = "0.1", features = ["derive"] }
use envigil::{EnvConfig, Secret};
use std::time::Duration;

#[derive(Debug, EnvConfig)]
#[env(prefix = "APP_")]
struct Config {
    #[env(default = "8080")]
    port: u16,

    #[env(secret)]
    database_url: Secret<String>,

    #[env(default = "30", parse_with = envigil::parse::secs)]
    timeout: Duration,
}

fn main() -> Result<(), envigil::Error> {
    let cfg = Config::from_env()?;
    println!("{cfg:?}");
    // Config { port: 8080, database_url: Secret([REDACTED]), timeout: 30s }
    Ok(())
}

Error output

All errors are collected and reported together:

environment configuration failed (2 errors)

  environment variable 'APP_PORT' is required but not set

  failed to parse 'APP_TIMEOUT_SECS': invalid number of seconds: invalid digit (received: "abc")

Validation

Built-in validators:

use envigil::validate;

VarBuilder::new("PORT", |v| v.parse::<u16>().map_err(|e| e.to_string()))
    .validate(validate::range(1..=65535))

VarBuilder::new("EMAIL", |v| Ok(v.to_owned()))
    .validate(validate::not_empty())
    .validate(validate::contains("@"))

VarBuilder::new("DSN", |v| Ok(v.to_owned()))
    .validate(validate::starts_with("postgres://"))

Custom validators — any closure:

VarBuilder::new("WORKERS", |v| v.parse::<u32>().map_err(|e| e.to_string()))
    .validate_with(|n| {
        if *n > 0 && *n <= 128 { Ok(()) }
        else { Err("must be 1–128".to_owned()) }
    })

Or implement the trait:

use envigil::validate::Validator;

struct EvenOnly;

impl Validator<u32> for EvenOnly {
    fn validate(&self, value: &u32) -> Result<(), String> {
        if value % 2 == 0 { Ok(()) }
        else { Err(format!("{value} is odd")) }
    }
}

Secret handling

Variables marked .secret() are stored as Secret<T>:

  • Debug / Display print [REDACTED]
  • Inner value accessible via .expose()
  • get::<String>() on a secret variable fails — you must use get::<Secret<String>>()
let url: &Secret<String> = cfg.get("APP_DATABASE_URL")?;
let raw: &str = url.expose(); // explicit opt-in

Parse helpers

use envigil::parse;

parse::secs("30")       // Ok(Duration::from_secs(30))
parse::millis("500")    // Ok(Duration::from_millis(500))
parse::flag("yes")      // Ok(true)  — also: true/1/on, false/0/no/off
parse::list("a, b, c")  // Ok(vec!["a", "b", "c"])
parse::list_sep(';')("x; y")  // Ok(vec!["x", "y"])

.env file support

[dependencies]
envigil = { version = "0.1", features = ["dotenv"] }
let cfg = EnvSource::new()
    .dotenv()                    // loads .env from CWD (optional)
    .dotenv_path(".env.local")   // or a specific path
    .declare(VarBuilder::new("PORT", |v| v.parse::<u16>().map_err(|e| e.to_string())))
    .load()?;

Real environment variables always take priority over .env entries. Missing files are silently ignored.

Supported syntax:

# Comment
PORT=8080
NAME="hello world"
export TOKEN='s3cret'
EMPTY=

Feature flags

Feature Default Adds
derive ❌ #[derive(EnvConfig)] (pulls envigil-derive)
dotenv ❌ .env file loading (own parser, no external deps)

With no features enabled, envigil has zero dependencies.

Minimum Supported Rust Version

1.85.0 (edition 2024). MSRV bumps come with a minor version bump and are noted in the changelog.

License