envguard

Declare machine-readable .env schemas, then validate them in one command.

• Avoid surprises like missing DATABASE_URL in staging.
• Reject BETA_TOGGLE=apples when a schema forbids it.
• Get one human-friendly table or one --json payload for GitHub Actions and other CI.
• Keep one source of truth inside JSON or YAML so reviewers don't have to run the app to trust the required variables.

About

envguard ships a small CLI that validates .env files against schemas instead of relying on ad-hoc shell scripts or one-off assertions in application code. A schema file declares each variable as JSON or YAML, and envguard check reports issues before code ships.

Installation

From source

git clone https://github.com/felixhartmannnn/envguard.git
cd envguard
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Via pip after publish

pip install envguard

Quick start

# Generate a starter schema in the current project.
envguard init --output envguard.schema.json

# Point it at the schema and your .env file.
envguard check envguard.schema.json

Usage

envguard init

Scaffold a starter JSON schema with common fields.

envguard init --output envguard.schema.yml

envguard check

Validate the env file declared in the schema.

# Pretty table output for local use
envguard check envguard.schema.json

# Machine-readable JSON output for scripts and CI
envguard check envguard.schema.json --json

# Override the env file path without changing the schema source.
envguard check envguard.schema.json --env-file .env.staging

Useful flags:

• --json returns a stable JSON payload and exits non-zero on issues, making it easy to gate CI.
• --env-file swaps the env source at runtime.
• --project-root points at a monorepo package instead of the current working directory.
• --help covers global and subcommand options.

Schema format

Use JSON or YAML. The top level can be an object with a fields map, or the map itself if source is left as .env.

fields:
  DATABASE_URL:
    required: true
    kind: string
    description: "SQLAlchemy-style database URL."

  PORT:
    required: true
    kind: int
    allowed: ["3000", "8080"]
    description: "HTTP port used by the API server."

  ENABLE_NEW_DASHBOARD:
    required: false
    kind: bool
    default: false
    description: "Toggle the new operator UI."

source: .env

Supported field attributes:

• required: bool
• kind: string | int | float | bool | json
• default: any
• min_length and max_length: int
• pattern: regex
• allowed: list[str]
• forbidden: list[str]
• description: string

Shorthand

Declare a field as a bare string for the common case.

{
  "API_KEY": "string"
}

Shorthand kind aliases map loosely: str, string, text become string; bool and boolean become bool; json, object, list, and array become json.

CI example

name: envguard

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install envguard
      - run: envguard check envguard.schema.json --json --env-file .env.example

Project structure

envguard/
  src/envguard/
    __init__.py
    cli.py
    schema.py
    checks.py
    report.py
  tests/
  docs/
  pyproject.toml

Topics

cli, python, dotenv, env-validation, developer-tools, envguard, ci

Contributing

Open an issue or pull request. Add tests alongside behavior changes, and keep the public API coverage in src/envguard/__init__.py.

License

MIT. See LICENSE for details.

Repository

Source and issues: https://github.com/felixhartmannnn/envguard