@envguard/cli

ESLint for environment variables. Catches undocumented process.env references before they ship.

The problem

A developer adds process.env.PAYMENT_WEBHOOK_SECRET to the codebase. It works on their machine. It silently breaks in staging because nobody documented it, nobody added it to .env.example, and the next person to set up the project has no idea it exists.

EnvGuard makes this impossible to merge.

How it works

You commit a .env.schema file — one entry per environment variable your app uses:

# .env.schema
DATABASE_URL:
  description: PostgreSQL connection string
  required: true
  example: postgres://user:pass@host:5432/dbname

STRIPE_SECRET_KEY:
  description: Stripe secret key for payment processing
  required: true
  example: sk_test_...

REDIS_URL:
  description: Redis connection string for caching
  required: false
  example: redis://localhost:6379

EnvGuard scans your source code for process.env.VAR references and fails if any are missing from .env.schema.

Quickstart

# Step 1: scan your codebase and generate .env.schema
npx @envguard/cli init

# Step 2: fill in the descriptions, then check everything is documented
npx @envguard/cli check

init takes ~2 seconds. It scans every .js, .ts, .py, and .rb file and generates .env.schema with an entry for every variable it finds. You fill in the descriptions and commit the file.

From that point on, check exits with code 1 if any new reference appears without a schema entry — which means you can drop it directly into any CI pipeline.

CLI reference

npx @envguard/cli init

Scans the codebase. Generates or updates .env.schema. Existing entries are preserved — only new variables are added.

Options:
  -d, --dir <path>   Directory to scan (default: current directory)

npx @envguard/cli check

Reads .env.schema. Scans the codebase. Reports undocumented references. Exits 1 on violations.

Options:
  -d, --dir <path>   Directory to check (default: current directory)
  --strict           Also flag entries with missing descriptions or examples

Use in CI

GitHub Actions

# .github/workflows/envguard.yml
name: EnvGuard
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @envguard/cli check

Any other CI (GitLab, CircleCI, Bitbucket Pipelines...)

npx @envguard/cli check   # exit 0 = pass, exit 1 = violations

Supported languages

| Language | Patterns detected | |---|---| | JavaScript / TypeScript | process.env.VAR, process.env['VAR'], import.meta.env.VAR | | Python | os.environ['VAR'], os.environ.get('VAR'), os.getenv('VAR') | | Ruby | ENV['VAR'], ENV.fetch('VAR'), ENV.dig('VAR') |

What gets published to npm

Only the runtime files:

@envguard/cli
├── src/
│   ├── index.js          ← CLI entry point
│   ├── schema.js         ← .env.schema parser/writer
│   ├── colours.js        ← terminal output
│   ├── commands/
│   │   ├── init.js
│   │   └── check.js
│   └── scanner/
│       ├── index.js      ← orchestrator + diff scanner
│       ├── js.js         ← JavaScript/TypeScript
│       ├── python.js     ← Python
│       └── ruby.js       ← Ruby
└── README.md

Tests and fixtures are not included in the published package.

Links

• GitHub: https://github.com/alexdruk/envguard
• Issues: https://github.com/alexdruk/envguard/issues
• Changelog: https://github.com/alexdruk/envguard/blob/main/CHANGELOG.md

License

MIT