env-config-validator

Validate .env files against schemas, compare environments (dev vs prod), detect common mistakes (trailing spaces, placeholders, invalid ports, missing protocols, duplicate keys, unquoted spaces), auto-generate schemas, and type-check values. Supports text, JSON, and markdown output with CI-friendly exit codes. Use when asked to validate environment config, check .env files for errors, compare env files, diff environments, detect env misconfigurations, generate env schema, audit .env variables, check for missing env vars, or ensure env consistency across environments. Triggers on "validate env", "check .env", "compare environments", "env diff", "env schema", "env audit", "missing env vars", "environment config".

Env Config Validator

Validate .env files, compare environments, detect common mistakes, and enforce schemas.

Quick Start

# Validate with auto-detected common checks
python3 scripts/validate_env.py .env

# Validate against a schema
python3 scripts/validate_env.py .env --schema env-schema.json

# Compare dev vs prod
python3 scripts/validate_env.py --diff .env.development .env.production

# Generate schema from existing .env
python3 scripts/validate_env.py --generate-schema .env -o env-schema.json

# JSON output for CI
python3 scripts/validate_env.py .env --output json --severity error

Common Checks (Auto-Detected)

The validator automatically detects these issues without a schema:

Check	Severity	What it catches
Trailing whitespace	warning	Invisible chars causing bugs
Unquoted spaces	warning	Values with spaces not wrapped in quotes
Placeholders	error	`change_me`, `TODO`, `xxx`, `your_*` values
Empty values	info	Defined but blank variables
Double-nested quotes	warning	`""value""` quoting errors
URL missing protocol	warning	URL vars without http(s)://
Port out of range	error	Port > 65535 or < 1
Short secrets	warning	SECRET/PASSWORD/KEY < 8 chars
Inconsistent booleans	info	`yes`/`1` instead of `true`/`false`
Mixed case keys	info	`some_Var` instead of `SOME_VAR`
Inline comments	warning	`value # comment` (not all parsers support)
Duplicate keys	warning	Same variable defined twice

Options

Flag	Default	Description
`--schema`	—	JSON schema file for type/required validation
`--diff FILE FILE`	—	Compare two env files
`--generate-schema`	—	Auto-generate schema from .env file
`--output`	text	Output format: text, json, markdown
`-o`	stdout	Output file path
`--ignore`	—	Skip specific check IDs (repeatable)
`--severity`	info	Minimum severity: error, warning, info

Exit Codes

0 — No issues (or only info)
1 — Warnings found (or diff has differences)
2 — Errors found

Workflow

Pre-deploy Validation

Generate schema from working .env: --generate-schema .env -o schema.json
Add schema to repo, validate in CI: validate_env.py .env --schema schema.json --severity error
Diff staging vs prod: --diff .env.staging .env.production

Audit Existing Project

Run validate_env.py .env to find common mistakes
Fix errors and warnings
Generate schema for future validation

References

schema-format.md — Full JSON schema specification, supported types, field reference