envcheck


> Static environment validation for CI/CD and monorepos. Validate .env files against .env.example, detect secrets, check types - all before your app runs.

The Problem

You've seen this before:
- "It works on my machine" → missing env var in production
- Deployment fails → forgot to add new API key
- Secret leaked → accidentally committed real credentials
- Monorepo chaos → different apps have inconsistent env configs

envcheck catches these issues in CI/CD, before they reach production.

Key Features

- Shift-left validation - Catch missing vars before deployment, not at runtime
- Monorepo support - Scan all apps/packages with one command (envcheck monorepo)
- Secret detection - Warns about AWS keys, GitHub tokens, Stripe keys in your .env
- Type validation - Validate URLs, ports, emails, JSON without running your app
- GitHub Action - Drop-in CI/CD integration
- Zero dependencies - Fast install, minimal footprint

Built autonomously by Claude - an AI assistant by Anthropic.

Installation

``bash
npm install -g @claude-agent/envcheck
`

Or use directly with npx:

`bash
npx @claude-agent/envcheck
`

Quick Start

`bash


Check .env against .env.example (auto-detected)

envcheck

Check specific file

envcheck .env.production

Require specific variables

envcheck -r "DATABASE_URL,API_KEY"

Scan entire monorepo

envcheck monorepo

Compare two files

envcheck compare .env .env.staging

List variables

envcheck list .env

Get specific value

envcheck get .env API_KEY
`

CLI Usage

$3

`bash


Auto-detect .env.example in same directory

envcheck

Specify example file

envcheck -e .env.example.prod .env.production

Require specific variables

envcheck -r "DB_HOST,DB_USER,DB_PASS"

Warn on empty values

envcheck --no-empty

Error on extra variables not in example

envcheck --no-extra

Treat warnings as errors

envcheck --strict

JSON output

envcheck -j

Quiet mode (only errors)

envcheck -q
`

$3

`bash


Compare two env files

envcheck compare .env .env.example

JSON output

envcheck compare .env .env.prod -j
`

$3

`bash


List all variable names

envcheck list .env

JSON output

envcheck list .env -j
`

$3

`bash


Get a specific variable value


envcheck get .env DATABASE_URL
`

$3

Scan all apps and packages in a monorepo with a single command:

`bash


Scan from current directory

envcheck monorepo

Scan specific directory

envcheck monorepo ./my-monorepo

With verbose output (shows all issues per app)

envcheck monorepo --verbose

JSON output for CI/CD

envcheck monorepo --json

Enable secret detection

envcheck monorepo --secrets
`

Monorepo Support

envcheck can scan entire monorepos, validating environment variables across all apps and packages.

$3

envcheck automatically detects these common monorepo patterns:

`
my-monorepo/
├── apps/
│ ├── web/ # ✓ Scanned
│ │ ├── .env
│ │ └── .env.example
│ └── api/ # ✓ Scanned
│ ├── .env
│ └── .env.example
├── packages/
│ ├── shared/ # ○ Skipped (no .env.example)
│ └── utils/ # ✓ Scanned
│ ├── .env
│ └── .env.example
└── .env.example # ✓ Root included if exists
`

Supported directories: apps/, packages/, workspaces/, services/, libs/

$3

`
$ envcheck monorepo

Monorepo Environment Check
Root: /path/to/monorepo

✓ apps/web: passed
✗ apps/api: 1 error(s)
○ packages/shared: skipped (No .env.example found)
✓ packages/utils: passed

Summary: 4 apps scanned
✓ 2 passed
✗ 1 failed
○ 1 skipped

✗ 1 error(s), 0 warning(s)
`

$3

envcheck can detect inconsistencies across apps:

- Shared variables - Track which variables appear in multiple apps
- Type mismatches - Detect when the same variable has different type hints in different apps

`javascript
const { scanMonorepo } = require('@claude-agent/envcheck');

const result = scanMonorepo('.', { checkConsistency: true });

console.log(result.consistency.sharedVars);
// { API_URL: ['apps/web', 'apps/api'] }

console.log(result.consistency.mismatches);
// [{ variable: 'API_URL', issue: 'type_mismatch', details: [...] }]
`

$3

`yaml
- name: Validate all environment files
uses: claude-agent-tools/envcheck@v1
with:
monorepo: 'true'
strict: 'true'
`

API Usage

`javascript
const { check, compare, validate, parse, list, get, generate } = require('@claude-agent/envcheck');

// Full check against example
const result = check('.env', {
examplePath: '.env.example',
required: ['DATABASE_URL'],
noEmpty: true,
strict: false
});

console.log(result.valid); // true/false
console.log(result.issues); // Array of issues
console.log(result.summary); // { errors: 0, warnings: 0 }

// Compare two files
const diff = compare('.env', '.env.example');
console.log(diff.missing); // Variables in example but not in env
console.log(diff.extra); // Variables in env but not in example
console.log(diff.empty); // Variables that are empty in env

// Validate a single file
const validation = validate('.env', {
required: ['API_KEY', 'SECRET'],
noEmpty: true
});

// Parse env content directly
const parsed = parse('FOO=bar\nBAZ=qux');
console.log(parsed.variables); // { FOO: 'bar', BAZ: 'qux' }

// List variables
const vars = list('.env'); // ['FOO', 'BAZ', ...]

// Get specific variable
const value = get('.env', 'API_KEY');

// Generate .env from example with defaults
const content = generate('.env.example', {
DATABASE_URL: 'postgres://localhost/mydb',
API_KEY: 'dev-key'
});
`

Exit Codes

| Code | Meaning |
|------|---------|
| 0 | All checks passed |
| 1 | Errors found (missing vars, invalid syntax, etc.) |

Example Output

`
$ envcheck
Checking .env against .env.example...

✗ Missing variable 'DATABASE_URL' (defined in example at line 3)
✗ Missing variable 'REDIS_URL' (defined in example at line 5)
! Variable 'API_KEY' is empty (line 7)

2 error(s), 1 warning(s)
`

`
$ envcheck compare .env .env.prod
Comparing .env with .env.prod...

.env: 12 variables
.env.prod: 15 variables

Missing (in example but not in env):
- NEW_RELIC_KEY
- SENTRY_DSN
- CDN_URL

Extra (in env but not in example):
- DEBUG
`

Use Cases

- CI/CD Pipelines: Validate env before deployment
- Onboarding: Check if developer has all required env vars
- Documentation: List required variables from example file
- Debugging: Compare env files across environments

CI/CD Integration

$3

Use envcheck in your GitHub Actions workflow:

`yaml
- name: Validate environment
uses: claude-agent-tools/envcheck@v1
with:
env-file: '.env'
example-file: '.env.example'
required: 'DATABASE_URL,API_KEY'
strict: 'true'
`

See action/README.md for full documentation.

$3

Use with the pre-commit framework:

`yaml


.pre-commit-config.yaml


repos:
- repo: local
hooks:
- id: envcheck
name: Validate environment variables
entry: npx @claude-agent/envcheck
language: system
files: '\.env.*'
pass_filenames: false
`

Or install the hook directly:

`bash


Copy hook to git hooks directory


curl -o .git/hooks/pre-commit https://raw.githubusercontent.com/claude-agent-tools/envcheck/master/pre-commit-hook.sh
chmod +x .git/hooks/pre-commit
`

Type Validation

envcheck supports static type validation - validate variable formats without running your app.

$3

Add type hints as comments above variables:

`bash


type: url

DATABASE_URL=postgres://localhost/mydb

@type port

PORT=3000

type: boolean

DEBUG=false

type: email

ADMIN_EMAIL=admin@example.com
`

$3

| Type | Description | Examples |
|------|-------------|----------|
| url | Valid URL | https://example.com, postgres://host/db |
| port | Port number (1-65535) | 3000, 8080 |
| boolean/bool | Boolean values | true, false, 1, 0, yes, no |
| email | Email address | user@example.com |
| number | Any number | 42, 3.14, -10 |
| integer/int | Whole numbers | 42, -10 |
| json | Valid JSON | {"key":"value"}, [1,2,3] |
| uuid | UUID format | 550e8400-e29b-41d4-a716-446655440000 |
| string/str | Any string (no validation) | anything |

Secret Detection

envcheck can warn you if your .env file contains values that look like real secrets:

`javascript
const result = check('.env', {
examplePath: '.env.example',
detectSecrets: true // Warns about potential secrets
});
`

$3

- AWS Access Keys (AKIA...)
- GitHub Tokens (ghp_..., gho_..., etc.)
- Stripe Keys (sk_live_..., rk_live_...)
- Private Keys (-----BEGIN PRIVATE KEY-----)
- Slack Tokens (xox...)
- Twilio Credentials
- SendGrid API Keys
- Google API Keys
- High-entropy hex strings (with sensitive key names)

$3

envcheck won't warn about obvious placeholders like:
- your-api-key, my-secret
- changeme, placeholder
- xxx, ...
- example, test, dummy

$3

`javascript
const { check, validate, detectSecret } = require('@claude-agent/envcheck');

// Enable secret detection
const result = check('.env', {
examplePath: '.env.example',
detectSecrets: true // Warns about potential secrets
});

// Check a single value
const secret = detectSecret('API_KEY', 'sk_live_abc123...');
if (secret) {
console.log(Warning: ${secret.description} detected);
}
`

$3

`javascript
const { check, validate } = require('@claude-agent/envcheck');

// Explicit type validation
const result = validate('.env', {
types: {
DATABASE_URL: 'url',
PORT: 'port',
DEBUG: 'boolean'
}
});

// Types from example file are used automatically
const result2 = check('.env', {
examplePath: '.env.example' // Type hints in example are used
});
`

.env File Format

Supports standard .env syntax:

`bash


Comments


KEY=value
QUOTED="value with spaces"
MULTILINE="line1\nline2"
EMPTY=
WITH_EQUALS=postgres://user:pass@host/db?opt=val
``

Why This Tool?

- Zero dependencies - Fast install, no bloat
- Auto-detection - Finds .env.example automatically
- CI-friendly - Exit codes and JSON output
- Comprehensive - Parse, validate, compare, generate
- Monorepo support - Scan all apps/packages in one command
- TypeScript support - Full type definitions included
- Well-tested - 87 tests covering edge cases

Examples

See the examples directory for complete demos:
- Monorepo Demo - Demonstrates scanning a full monorepo structure

vs. dotenv-safe / envalid / dotenv-mono

| Feature | envcheck | dotenv-safe | envalid | dotenv-mono |
|---------|----------|-------------|---------|-------------|
| Validates presence | ✅ | ✅ | ✅ | ❌ |
| Based on .env.example | ✅ | ✅ | ❌ (schema) | ❌ |
| Static validation | ✅ | ❌ | ❌ | ❌ |
| CI/CD integration | ✅ GitHub Action | ❌ | ❌ | ❌ |
| Pre-commit hook | ✅ | ❌ | ❌ | ❌ |
| Type validation | ✅ (static) | ❌ | ✅ (runtime) | ❌ |
| Secret detection | ✅ | ❌ | ❌ | ❌ |
| Monorepo scan | ✅ | ❌ | ❌ | ❌ |
| Zero dependencies | ✅ | ❌ | ❌ | ❌ |

Key difference: envcheck validates before deployment (shift-left), while dotenv-safe and envalid validate at runtime when your app starts. dotenv-mono helps load env vars in monorepos but doesn't validate them. envcheck is the only tool that validates across entire monorepos with a single command.

License

MIT

---

Part of the claude-agent-tools collection.