envcheck

envcheck is a secure-by-default CLI for checking .env files against a template (usually .env.example) and linting .env files for structural issues.

It reports:

• missing keys
• extra keys
• duplicate keys
• malformed lines

It is designed for local developer workflows and CI pipelines.

Install and Run

One-off with npx

npx envcheck compare .env .env.example

Local project usage

npm install
npm run build
node dist/cli.js compare .env .env.example

Global-like local testing via npm link

npm link
envcheck --help

Typical Workflow

1. Keep required variables in .env.example.
2. Create your local .env.
3. Run envcheck compare .env .env.example.
4. Fix missing or extra keys and malformed lines.
5. Use --strict in CI for enforcement.

Commands

envcheck compare <targetFile> <templateFile>

Compares target vs template and reports:

• missing keys (in template but not target)
• extra keys (in target but not template)
• duplicate keys (with line numbers)
• malformed lines (with line numbers)

Options:

• --json: output machine-readable JSON
• --strict: fail on warnings (malformed lines; and extras if --warn-extra is set)
• --warn-extra: treat extra keys as warnings (and failures in strict mode)
• --show-values: explicit opt-in to print real values
• --max-bytes <bytes>: file size cap per input (default 1048576)
• --no-follow-symlinks: reject symlink inputs

Behavior notes:

• missing keys and duplicates are validation failures
• malformed lines are warnings unless --strict
• extra keys are informational unless --warn-extra

envcheck lint <file>

Single-file checks:

• duplicate keys
• malformed lines
• empty key names
• invalid key names
• optional whitespace normalization warnings

Options:

• --json
• --strict
• --show-values
• --max-bytes <bytes>
• --no-follow-symlinks

envcheck doctor [file]

Checks git hygiene for secrets:

• whether file exists
• whether it is ignored by git (git check-ignore)
• whether it appears tracked by git (git ls-files)
• warns when .env exists but is not ignored

Notes:

• graceful warnings if git is unavailable or not initialized
• does not print file contents or values

envcheck --help and envcheck --version

Supported directly from CLI.

Parser Rules (Deterministic)

envcheck parses .env files as plain text only:

• ignores blank lines
• ignores full-line comments starting with #
• supports KEY=value
• supports export KEY=value
• supports quoted values ("..." and '...') as literals
• supports inline comments only for unquoted values (KEY=abc # comment)
• tracks duplicate keys by line number
• key pattern: ^[A-Za-z_][A-Za-z0-9_]*$
• does not perform variable expansion or interpolation
• rejects multiline quoted values with line-numbered parser errors

JSON Output

For compare and lint, JSON output includes a stable shape with at least:

• ok
• missing
• extra
• duplicates (with file, key, line numbers)
• malformed
• counts
• warnings

Example (compare --json):

{
  "ok": false,
  "missing": ["DB_PASS"],
  "extra": ["LOCAL_ONLY"],
  "duplicates": [
    {
      "file": "/workspace/.env",
      "key": "API_URL",
      "lines": [2, 7]
    }
  ],
  "malformed": [
    {
      "file": "/workspace/.env",
      "line": 10,
      "reason": "Missing '=' separator."
    }
  ],
  "counts": {
    "missing": 1,
    "extra": 1,
    "duplicates": 1,
    "malformed": 1,
    "warnings": 1
  },
  "warnings": [
    "1 malformed line(s) were ignored. Use --strict to fail on malformed lines."
  ]
}

Exit Codes

| Code | Meaning | | --- | --- | | 0 | Success / no blocking issues | | 1 | Validation issues found | | 2 | Usage error / invalid arguments | | 3 | File I/O error (missing file, permissions, symlink rejection, size limit) | | 4 | Internal unexpected error |

Strict mode behavior:

• compare --strict: malformed lines become failures; extras fail only with --warn-extra
• lint --strict: warnings fail

CI Example (GitHub Actions)

name: envcheck

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate-env:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - run: node dist/cli.js compare .env .env.example --strict --warn-extra

Security Notes

• Parses .env as text only; it does not execute shell syntax.
• Values are redacted by default.
• No telemetry or network calls.
• --show-values is explicit opt-in and prints a warning.
• Parsed values are never loaded into process.env.
• If a secret was committed, rotate/revoke it.

Development

npm install
npm run build
npm test

Fixtures are available in fixtures/ for manual checks.