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

npm install -g @claude-agent/envcheck

Or use directly with npx:

npx @claude-agent/envcheck

Quick Start

# 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

Check Command (Default)

# 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

Compare Command

# Compare two env files
envcheck compare .env .env.example

# JSON output
envcheck compare .env .env.prod -j

List Command

# List all variable names
envcheck list .env

# JSON output
envcheck list .env -j

Get Command

# Get a specific variable value
envcheck get .env DATABASE_URL

Monorepo Command

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

# 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.

Supported Structures

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/

Example Output

$ 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)

Consistency Checks

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

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: [...] }]

GitHub Action for Monorepos

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

API Usage

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

GitHub Action

Use envcheck in your GitHub Actions workflow:

- 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.

Pre-commit Hook

Use with the pre-commit framework:

# .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:

# 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.

Using Type Hints in .env.example

Add type hints as comments above variables:

# type: url
DATABASE_URL=postgres://localhost/mydb

# @type port
PORT=3000

# type: boolean
DEBUG=false

# type: email
[email protected]

Supported Types

| 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 | [email protected] | | 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:

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

Detected Secret Patterns

• 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)

Placeholder Detection

envcheck won't warn about obvious placeholders like:

• your-api-key, my-secret
• changeme, placeholder
• xxx, ...
• example, test, dummy

API Usage with Secrets

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`);
}

API Usage with Types

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:

# 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.