env-key-diff

env-key-diff is a tiny CLI that compares two dotenv-style files and reports key drift between them.

It is stack-agnostic, compares keys only, and is useful anywhere .env files are part of your development workflow (Node.js, PHP, Python, etc.).

Requirements

• Node.js 18 or newer

Installation

You can run env-key-diff immediately without installing it permanently via npx, or you can add it to your project as a dev dependency.

Using npx (Recommended)

npx env-key-diff

By default, this compares .env.example against .env. You can specify custom paths:

npx env-key-diff .env.example .env.local

Install as a Dev Dependency

To enforce environment configuration checks during your continuous integration (CI) pipelines or as a pre-commit hook:

npm install --save-dev env-key-diff

Then you can add it to your package.json scripts:

{
  "scripts": {
    "env:check": "env-key-diff"
  }
}

Usage

env-key-diff [source] [target] [options]

If no arguments are given, source defaults to .env.example and target defaults to .env.

Options

• --json Output machine-readable JSON instead of human-readable text
• --strict Fail on extra keys as well (by default, it only fails on missing keys and typos)
• --ignore <keys> Comma-separated list of keys to ignore (e.g., --ignore=API_KEY,SECRET)
• -h, --help Show usage information

What It Checks

• Missing keys: Keys that exist in the source file but not the target file.
• Extra keys: Keys present in the target file but not in the source file.
• Possible typos: Likely typos (e.g., matching DBHOST instead of DB_HOST).

env-key-diff compares keys only. It does not evaluate, parse, or compare environment values, ensuring your secrets remain completely safe and never leak into logs or the CLI.

Example Output

Text output (Default)

Command:

npx env-key-diff .env.example .env.local

Output:

Missing Keys:
  - DB_HOST
  - STRIPE_SECRET

Extra Keys:
  - DBHOST
  - EXTRA_FLAG

Possible Typos:
  - DBHOST -> DB_HOST

JSON output

Command:

npx env-key-diff .env.example .env.local --json

Output:

{
  "ok": false,
  "hasDifferences": true,
  "strict": false,
  "sourcePath": ".env.example",
  "targetPath": ".env.local",
  "ignoredKeys": [],
  "missingKeys": [
    "DB_HOST",
    "STRIPE_SECRET"
  ],
  "extraKeys": [
    "DBHOST",
    "EXTRA_FLAG"
  ],
  "possibleTypos": [
    {
      "sourceKey": "DB_HOST",
      "targetKey": "DBHOST"
    }
  ]
}

If the files match, the CLI prints:

Success: source and target contain the same keys.

Exit Codes

• 0: Validation passed, no blocking issues found.
• 1: Runtime or CLI usage error (e.g., incorrect path or missing arguments).
• 2: Validation failed.

By default, validation fails (code 2) on missing keys or typos. With --strict enabled, validation will also fail if extra keys are present in the target file.

Parsing Notes

• Blank lines and comment lines (starting with #) are ignored.
• export KEY=value syntax is inherently supported.
• Duplicate keys are gracefully de-duplicated.
• Keys are sorted internally for stable outputs.

The internal parser is intentionally simple: it reads keys directly from assignment lines without attempting to fully load the .env values into memory.

CI/CD Pipeline

Add env-key-diff to your CI/CD pipeline to catch missing environment variables before deployment. The CLI exits with code 2 when keys are missing, which will fail the pipeline step.

GitHub Actions

Add the following step to any workflow file (e.g., .github/workflows/ci.yml):

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  env-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Check environment variables
        run: npx env-key-diff

This will compare .env.example against .env by default. You can customize the source and target files:

      - name: Check environment variables
        run: npx env-key-diff .env.example .env.staging --strict

GitLab CI

env-check:
  image: node:20-alpine
  script:
    - npx env-key-diff

Generic (Any CI)

npx env-key-diff

The exit code (0 = pass, 2 = fail) integrates naturally with any CI system.