Env Config Validator#

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

Quick Start#

bash

# 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:

CheckSeverityWhat it catchesTrailing whitespacewarningInvisible chars causing bugsUnquoted spaceswarningValues with spaces not wrapped in quotesPlaceholderserrorchange_me, TODO, xxx, your_* valuesEmpty valuesinfoDefined but blank variablesDouble-nested quoteswarning""value"" quoting errorsURL missing protocolwarningURL vars without http(s)://Port out of rangeerrorPort > 65535 or < 1Short secretswarningSECRET/PASSWORD/KEY < 8 charsInconsistent booleansinfoyes/ 1 instead of true/ falseMixed case keysinfosome_Var instead of SOME_VARInline commentswarningvalue # comment (not all parsers support)Duplicate keyswarningSame variable defined twice

Options#

FlagDefaultDescription--schema—JSON schema file for type/required validation--diff FILE FILE—Compare two env files--generate-schema—Auto-generate schema from .env file--outputtextOutput format: text, json, markdown-ostdoutOutput file path--ignore—Skip specific check IDs (repeatable)--severityinfoMinimum 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#

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

Audit Existing Project#

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

References#

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