envigil
Keep vigil over your environment.
Load, parse, and validate environment variables with zero dependencies and first-class error reporting.
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 sources | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
Testing without std::env |
❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
| Miette diagnostics | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ (feature) |
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, .env, and miette support are opt-in feature flags.
Quick start
[]
= "0.3"
Builder API
use ;
use validate;
use layer;
use Duration;
Derive API
[]
= { = "0.3", = ["derive"] }
use ;
let cfg = from_env?;
Generated constructors:
| Constructor | Description |
|---|---|
Config::from_env() |
Loads from the process environment. |
Config::from_map(values) |
Uses an in-memory map as a fallback. Useful for tests. Real environment variables still take precedence. |
Field attributes:
| Attribute | Description |
|---|---|
#[env(default = "value")] |
Parse and use this fallback when the variable is absent. |
#[env(secret)] |
Wrap the parsed value in Secret<T>. |
#[env(parse_with = path)] |
Use a custom parser fn(&str) -> Result<T, String>. |
#[env(rename = "VAR_NAME")] |
Use exactly this environment variable name. The struct-level prefix is not applied. |
#[env(validate(range(1..=128)))] |
Add a validator. Bare built-in validators resolve as envigil::validate::<validator>. |
#[env(skip)] |
Do not read from environment; initialize the field from Default::default(). |
Multiple validators can be attached:
email: String,
Layered sources
EnvSource accepts an ordered list of layers. The first layer returning a value wins:
use layer;
let cfg = new
.layer // highest priority
.layer // .env file
.layer
.declare
.load?;
Layer insertion order = priority order.
Built-in layers: layer::env(), layer::map(...), layer::dotenv(), layer::dotenv_path(path).
Custom layers — any closure Fn(&str) -> Option<String>:
.layer
When no layers are added, load() reads from std::env automatically (backward compat).
Testing without std::env
let cfg = from_map
.declare
.load?;
assert_eq!;
No unsafe { std::env::set_var(...) } in tests.
Error output
All errors are collected and reported together:
environment configuration failed (2 errors)
┌─ APP_PORT
│
│ value 99999 is out of range 1..=65535
┌─ APP_DATABASE_URL
│
│ environment variable 'APP_DATABASE_URL' is required but not set
│ hint: set APP_DATABASE_URL or provide a .env file
Miette diagnostics (feature = "miette")
[]
= { = "0.3", = ["miette"] }
if let Err = new.declare.load
Each error gets a code (envigil::missing, envigil::parse, envigil::validation), severity, and help text. Parse errors show the raw value with an underline. Multi-errors expand as related diagnostics.
Validation
Built-in validators:
| Validator | Description |
|---|---|
range(1..=65535) |
Number within an inclusive range |
not_empty() |
Non-empty string |
contains("@") |
Contains a substring |
starts_with("postgres://") |
Starts with a prefix |
ends_with(".rs") |
Ends with a suffix |
length(1..=255) |
String or collection length within a range |
ip() |
Valid IP address (v4 or v6) |
hostname() |
Valid hostname per RFC 1123 |
host() |
Valid IP or hostname |
email() |
Basic email validation (zero-dep, practical checks) |
file_exists() |
Path exists on the filesystem |
url() |
Basic URL validation (scheme, authority, no whitespace) |
strict_url() (feature url) |
Strict RFC 3986 validation |
one_of(["a", "b"]) |
Value matches one of the allowed strings |
Custom validators — any closure via validate_with, or a Validator<T> impl:
new
.validate_with
Parse helpers
| Function | Input | Output |
|---|---|---|
parse::secs("30") |
Seconds | Duration |
parse::millis("500") |
Milliseconds | Duration |
parse::duration("5m 30s") |
Units: ms, s, m, h |
Duration |
parse::bytes("10MB") |
B/KB/MB/GB, KiB/MiB/GiB |
u64 |
parse::bool("yes") |
true/1/yes/on, false/0/no/of | bool |
parse::flag("yes") |
(deprecated, use bool) |
bool |
parse::list("a, b") |
Comma-separated | Vec<String> |
parse::list_sep(';') |
Custom separator | Vec<String> |
parse::socket_addr("0.0.0.0:8080") |
Socket address (IPv4/IPv6) | SocketAddr |
parse::url("https://...") |
URL string | String (normalized) |
parse::strict_url("...") (feature url) |
URL string | url::Url (RFC 3986) |
Secret handling
Variables marked with .secret() are stored as Secret<T>:
Debug/Display→[REDACTED]- Access the value only via
.expose()or.into_inner() get::<String>()on a secret variable returns an error (type mismatch protection).map(f)— transform without exposing:Secret<T> → Secret<U>.as_ref()— borrow the inner value by reference without consuming
let db_url: = cfg.get?.clone;
// Safe transformation — intermediate value never leaves the closure
let host: = db_url.map;
println!; // [REDACTED]
// Borrow without consuming
assert_eq!;
.env file support
[]
= { = "0.3", = ["dotenv"] }
let cfg = new
.layer // .env from CWD
.layer // or a specific path
.declare
.load?;
Real environment variables take priority when layer::env() is added first. Missing files are silently ignored. std::env is never mutated.
Feature flags
| Feature | Default | Adds |
|---|---|---|
derive |
❌ | #[derive(EnvConfig)] (pulls envigil-derive) |
dotenv |
❌ | .env file loading (own parser, no external deps) |
miette |
❌ | miette::Diagnostic for rich error rendering |
url |
❌ | parse::strict_url, validate::strict_url (pulls url crate) |
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
Licensed under either of Apache License, Version 2.0 or MIT license at your option.