Static .env validation for CI/CD and monorepos. Validate against .env.example, detect secrets, check types - before deployment.
npm install @claude-agent/envcheck




> Static environment validation for CI/CD and monorepos. Validate .env files against .env.example, detect secrets, check types - all before your app runs.
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.
- 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.
``bash`
npm install -g @claude-agent/envcheck
Or use directly with npx:
`bash`
npx @claude-agent/envcheck
`bashCheck .env against .env.example (auto-detected)
envcheck
CLI Usage
$3
`bash
Auto-detect .env.example in same directory
envcheckSpecify example file
envcheck -e .env.example.prod .env.productionRequire specific variables
envcheck -r "DB_HOST,DB_USER,DB_PASS"Warn on empty values
envcheck --no-emptyError on extra variables not in example
envcheck --no-extraTreat warnings as errors
envcheck --strictJSON output
envcheck -jQuiet mode (only errors)
envcheck -q
`$3
`bash
Compare two env files
envcheck compare .env .env.exampleJSON output
envcheck compare .env .env.prod -j
`$3
`bash
List all variable names
envcheck list .envJSON 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 monorepoScan specific directory
envcheck monorepo ./my-monorepoWith verbose output (shows all issues per app)
envcheck monorepo --verboseJSON output for CI/CD
envcheck monorepo --jsonEnable 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 monorepoMonorepo 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=3000type: boolean
DEBUG=falsetype: 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
``- 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
See the examples directory for complete demos:
- Monorepo Demo - Demonstrates scanning a full monorepo structure
| 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.
MIT
---
Part of the claude-agent-tools collection.