envward 0.1.0

Validate your .env against a typed schema (required, int, url, enum, …) before the app boots — catch bad config up front. Zero dependencies.

envward

Validate your .env against a typed schema before the app boots. A missing DATABASE_URL, a PORT=abc, a NODE_ENV=prodd typo — these don't fail loudly, they fail deep in startup with a cryptic stack trace, or worse, silently in production. envward checks the whole environment against a small schema up front and tells you exactly what's wrong, in one place. Zero dependencies, no network.

pip install envward

$ envward

.env — checked against env.schema.json

  ✗ API_KEY   missing — required string
  ✗ NODE_ENV  "prodd" is not one of: development, production, test
  ✗ PORT      70000 is above max 65535

3 problem(s), 3 key(s) valid

Exits non-zero when anything is invalid, so it drops straight into a boot script or CI step. Unlike a drift checker (which finds missing keys), envward validates the values: types, ranges, formats, and allowed sets.

This is the Python build. A behavior-equivalent Node build is on npm: npx envward (https://github.com/jjdoor/envward).

Get started in one command

# Infer a starter schema from your existing .env, then edit it:
envward --init > env.schema.json

--init guesses a type for each key from its current value (8080 → int, https://… → url, true → bool, …) and marks them all required. Tighten it from there.

The schema

A plain JSON file (env.schema.json by default), one rule per key:

{
  "PORT":         { "type": "int", "required": true, "min": 1, "max": 65535 },
  "DATABASE_URL": { "type": "url", "required": true },
  "NODE_ENV":     { "type": "enum", "values": ["development", "production", "test"] },
  "DEBUG":        { "type": "bool" },
  "API_KEY":      { "type": "string", "required": true, "minLength": 16 },
  "ADMIN_EMAIL":  { "type": "email" }
}

Type	Accepts
string	anything; constraints: minLength, maxLength, pattern (regex)
int	integer; constraints: min, max
number	integer or float; constraints: min, max
bool	true / false / 1 / 0 (case-insensitive)
url	scheme://…
email	[e-mail]
enum	one of values (required array)

required defaults to false. An empty value (KEY=) counts as missing.

Usage

envward                              # validate .env against env.schema.json
envward --env .env.prod --schema prod.schema.json
envward --strict                     # also flag keys in .env not declared in the schema
envward --json                       # machine-readable
envward --init > env.schema.json     # scaffold a schema from the current .env

Options

Flag	Effect
--env <file>	.env file to check (default .env)
--schema <file>	JSON schema file (default env.schema.json)
--strict	Keys present in .env but absent from the schema are problems
--init	Print a schema scaffold inferred from the .env
--json	Emit { valid, problems, summary } as JSON
--quiet	Print only the one-line summary
-v, --version · -h, --help

Use it as a gate

# refuse to boot with a broken .env, or fail CI:
envward && python -m myapp
envward --env .env.ci --strict

Exit codes

Code	Meaning
0	every key valid
1	one or more validation problems
2	error (missing/invalid schema, unreadable file)

A validator should fail when validation fails, so envward exits 1 on problems by default — no flag needed.

Notes

• Same tool, two builds. A behavior-equivalent Node build is on npm (npx envward); use whichever your stack already has.
• .env parsing strips a single pair of surrounding quotes and an optional export prefix. Inline comments after a value are not stripped — quote values that contain #.
• pattern is a regex matched in ASCII mode (\d = [0-9]) and as an unanchored search — wrap it in ^…$ to match the whole value. For identical results across both builds keep to a portable subset (avoid inline (?i) flags, lookbehind, and named groups, which differ between the JS and Python engines; a malformed pattern is reported as a schema error, exit 2).
• Numeric min/max are compared at 64-bit float precision — ample for config; keep bounds within ±2^53.

License

MIT