Environment Variable Manager (env-manager)

Comprehensive environment variable validation, security scanning, and management for modern web applications.

Overview

The env-manager skill provides systematic environment variable management across local development, CI/CD pipelines, and deployment platforms. It prevents common issues like missing variables, exposed secrets, and framework-specific configuration errors.

Key Features:

Framework-Aware Validation: Next.js, Vite, React, Node.js, Flask support Security-First: Never logs secrets, detects exposed credentials Platform Integration: Ready for Vercel, Railway, Heroku, and CI/CD Fast: Validates 1000 variables in 0.025s (80x faster than 2s target) Zero Dependencies: Pure Python, works anywhere Why Use env-manager?

Common problems this solves:

"Works on my machine, but not in production" (missing env vars) Accidentally exposing API keys in client-side code (NEXT_PUBLIC_ with secrets) Missing required variables during deployment Inconsistent .env files across team members No documentation of required environment variables Security vulnerabilities from exposed secrets Quick Start Installation

No installation needed! env-manager is a bundled skill in Claude MPM.

Requirements:

Python 3.7+ No external dependencies 5-Minute Quick Start

1. Validate your .env file

python3 scripts/validate_env.py .env

2. Check for framework-specific issues (Next.js example)

python3 scripts/validate_env.py .env --framework nextjs

3. Compare with .env.example to find missing vars

python3 scripts/validate_env.py .env --compare-with .env.example

4. Generate .env.example for documentation

python3 scripts/validate_env.py .env --generate-example .env.example

5. Get JSON output for CI/CD integration

python3 scripts/validate_env.py .env --json

That's it! Environment variables are now validated professionally.

Usage Examples Basic Validation

Validate a .env file for structural issues:

python3 scripts/validate_env.py .env

What it checks:

Valid key=value format No duplicate keys Proper naming conventions (UPPERCASE_WITH_UNDERSCORES) No empty values (unless explicitly allowed) Proper quoting for values with spaces

Example output:

✅ Validation successful! - 15 variables validated - 0 errors - 0 warnings

Framework-Specific Validation Next.js

Validate Next.js environment variables:

python3 scripts/validate_env.py .env.local --framework nextjs

Next.js-specific checks:

NEXT_PUBLIC_* variables are client-exposed (warns if secrets detected) .env.local, .env.production, .env file hierarchy Detects secrets in client-side variables

Example:

.env.local

NEXT_PUBLIC_API_URL=https://api.example.com NEXT_PUBLIC_API_KEY=secret123 # ⚠️ WARNING: Secret in client-exposed variable! DATABASE_URL=postgresql://... # ✅ Server-side only

Vite python3 scripts/validate_env.py .env --framework vite

Vite-specific checks:

VITE_* variables are client-exposed Warns if secrets detected in VITE_ prefixed vars React (Create React App) python3 scripts/validate_env.py .env --framework react

React-specific checks:

REACT_APP_* variables are client-exposed Warns if secrets in REACT_APP_ prefixed vars Node.js/Express python3 scripts/validate_env.py .env --framework nodejs

Node.js-specific checks:

Common NODE_ENV, PORT, DATABASE_URL patterns Standard Node.js conventions Flask/Python python3 scripts/validate_env.py .env --framework flask

Flask-specific checks:

FLASK_APP, FLASK_ENV variables SQLAlchemy DATABASE_URL format Comparing with .env.example

Ensure your .env has all required variables:

python3 scripts/validate_env.py .env --compare-with .env.example

What it checks:

All variables in .env.example exist in .env No extra undocumented variables in .env

Example output:

❌ Missing variables: - DATABASE_URL (required in .env.example) - STRIPE_SECRET_KEY (required in .env.example)

⚠️ Extra variables not in .env.example: - DEBUG_MODE (consider adding to .env.example)

Perfect for:

Onboarding new team members CI/CD validation Deployment pre-checks Generating .env.example

Create documentation for your environment variables:

python3 scripts/validate_env.py .env --generate-example .env.example

What it does:

Reads your .env file Sanitizes secret values (replaces with placeholders) Generates .env.example with safe defaults

Example:

Input: .env

DATABASE_URL=postgresql://user:pass@localhost/db # pragma: allowlist secret STRIPE_SECRET_KEY=sk_live_abc123xyz NEXT_PUBLIC_API_URL=https://api.example.com

Output: .env.example

DATABASE_URL=postgresql://user:password@localhost/dbname # pragma: allowlist secret STRIPE_SECRET_KEY=your_stripe_secret_key_here NEXT_PUBLIC_API_URL=https://api.example.com

Security note: env-manager detects common secret patterns and replaces them with safe placeholders.

CI/CD Integration

Get machine-readable JSON output for automated workflows:

python3 scripts/validate_env.py .env.example --strict --json

JSON output format:

{ "valid": true, "errors": [], "warnings": [], "stats": { "total_vars": 15, "errors": 0, "warnings": 0 } }

Exit codes:

0: Validation passed 1: Validation errors found 2: Missing required file 3: Warnings found (only in --strict mode)

GitHub Actions example:

name: Validate Environment Variables

on: [push, pull_request]

jobs: validate-env: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3

  - name: Validate .env.example
    run: |
      python3 scripts/validate_env.py .env.example --strict --json
    working-directory: ./path/to/skill

  - name: Check for framework-specific issues
    run: |
      python3 scripts/validate_env.py .env.example --framework nextjs --json
    working-directory: ./path/to/skill

Strict Mode

Treat warnings as errors (useful for CI/CD):

python3 scripts/validate_env.py .env --strict

When to use:

Pre-deployment validation CI/CD pipelines Release gates Team standard enforcement Quiet Mode

Show only errors, suppress warnings:

python3 scripts/validate_env.py .env --quiet

When to use:

You've already reviewed warnings Automated scripts that only care about errors Noisy environments where warnings are distracting Supported Frameworks Framework Prefix Client-Exposed Notes Next.js NEXT_PUBLIC_ Yes Auto-exposed in browser Vite VITE_ Yes Bundled into client code React (CRA) REACT_APP_* Yes Embedded in production build Node.js N/A No Server-side only Flask N/A No Server-side only

Security warning: Never put secrets in client-exposed variables (NEXT_PUBLIC_, VITE_, REACT_APP_). env-manager will warn you if it detects common secret patterns.

CLI Reference Command Structure python3 scripts/validate_env.py [options]

Options Option Description Example --compare-with FILE Compare with .env.example --compare-with .env.example --framework {nextjs|vite|react|nodejs|flask|generic} Framework-specific validation --framework nextjs --strict Treat warnings as errors --strict --json JSON output for automation --json --quiet Only show errors --quiet --generate-example OUTPUT Generate .env.example --generate-example .env.example Exit Codes Code Meaning When 0 Success No errors (warnings OK unless --strict) 1 Validation errors Structural issues, duplicates, etc. 2 File not found Specified .env file doesn't exist 3 Warnings in strict mode Warnings exist and --strict enabled Common Use Cases Scenario 1: New Developer Onboarding

New developer clones repo

git clone cd

Copy example and fill in values

cp .env.example .env

Edit .env with actual values...

Validate setup

python3 scripts/validate_env.py .env --compare-with .env.example

If missing variables, fix them

Validation passes ✅

Scenario 2: Pre-Deployment Check

Before deploying to Vercel/Railway/Heroku

python3 scripts/validate_env.py .env.production --framework nextjs --strict

Fix any errors

Deploy with confidence ✅

Scenario 3: Security Audit

Check for accidentally exposed secrets

python3 scripts/validate_env.py .env.local --framework nextjs

Look for warnings like:

⚠️ NEXT_PUBLIC_STRIPE_SECRET: Contains potential secret in client-exposed variable

Scenario 4: Team Documentation

After adding new environment variable

echo "NEW_API_KEY=abc123" >> .env

Regenerate .env.example

python3 scripts/validate_env.py .env --generate-example .env.example

Commit updated .env.example

git add .env.example git commit -m "docs: add NEW_API_KEY to environment variables"

Scenario 5: CI/CD Quality Gate

In your CI pipeline

• name: Validate environment configuration run: | python3 scripts/validate_env.py .env.example --strict --json > validation.json

  Fail pipeline if validation fails

  if [ $? -ne 0 ]; then cat validation.json exit 1 fi

Performance

env-manager is designed for speed:

Benchmarks:

Validates 1000 variables in 0.025s 80x faster than 2s target Zero external dependencies Minimal memory footprint

Why it matters:

Fast feedback during development No CI/CD slowdown Works in resource-constrained environments Security Notes

Critical security features:

Never Logs Secrets: env-manager NEVER displays actual secret values in output Client-Exposure Detection: Warns when secrets are in NEXT_PUBLIC_, VITE_, REACT_APP_ variables Secret Sanitization: When generating .env.example, replaces secrets with safe placeholders No Network Calls: All validation is local, no data leaves your machine

Security-audited: This skill has undergone security review. See references/security.md for details.

Best practices:

Never commit .env files with secrets Always use .env.example for documentation Use platform secret managers (Vercel, Railway, etc.) for production Validate before every deployment Run security scan regularly Common Issues "Missing equals sign" error

Cause: Line in .env doesn't have = separator

Fix:

❌ Bad

API_KEY

✅ Good

API_KEY=your_key_here

"Duplicate key" error

Cause: Same variable defined multiple times

Fix:

❌ Bad

API_KEY=value1 API_KEY=value2

✅ Good

API_KEY=value2

"Invalid variable name" warning

Cause: Variable name doesn't follow UPPERCASE_WITH_UNDERSCORES convention

Fix:

❌ Bad

apiKey=value api-key=value

✅ Good

API_KEY=value

"Potential secret in client-exposed variable" warning

Cause: NEXT_PUBLIC_, VITE_, or REACT_APP_ variable contains secret-like value

Fix:

❌ Bad (secret exposed to client!)

NEXT_PUBLIC_STRIPE_SECRET=sk_live_abc123

✅ Good (server-side only)

STRIPE_SECRET_KEY=sk_live_abc123 NEXT_PUBLIC_STRIPE_PUBLISHABLE=pk_live_xyz789

"Empty value" warning

Cause: Variable has no value

Fix:

❌ Bad

DATABASE_URL=

✅ Good (if optional, document it)

DATABASE_URL= # Optional, uses SQLite if not set

✅ Better

DATABASE_URL=postgresql://localhost/mydb

File not found error

Cause: Specified .env file doesn't exist

Fix:

Check file exists

ls -la .env

Or create it

touch .env

Troubleshooting Validation passes locally but fails in CI

Check:

Line endings (CRLF vs LF) File encoding (UTF-8 expected) File permissions Python version (3.7+ required) Warnings about client-exposed variables

This is intentional! env-manager is warning you that variables like NEXT_PUBLIC_API_KEY will be visible in the browser.

Options:

Move secret to server-side variable (remove NEXT_PUBLIC_ prefix) Use public/publishable keys only in client-exposed variables If truly not a secret, ignore the warning .env.example generation replaces too much

env-manager is conservative about secrets. If it over-sanitizes:

Manually edit .env.example after generation Use specific placeholder values in .env that won't trigger sanitization Advanced Usage Custom Validation Patterns

See references/validation.md for advanced validation patterns.

Platform-Specific Deployment

See references/synchronization.md for Vercel, Railway, Heroku integration patterns.

Framework-Specific Guides

See references/frameworks.md for comprehensive framework guides.

Related Documentation Validation Reference: Complete validation workflows and checks Security Reference: Secret scanning and security patterns Synchronization Reference: Platform sync patterns (coming soon) Frameworks Reference: Framework-specific patterns and conventions Troubleshooting Guide: Common issues and solutions Integration with Claude MPM

env-manager is a bundled skill in Claude MPM. Agents can use it for:

Pre-deployment validation Security scanning Environment setup verification Documentation generation

See INTEGRATION.md for agent integration patterns.

Contributing

env-manager follows Claude MPM contribution guidelines:

Run make lint-fix during development Run make quality before commits Add tests for new features (85%+ coverage required) Update documentation

See CONTRIBUTING.md for details.

License

MIT License - Part of Claude MPM project

Support Issues: Report bugs via GitHub Issues Documentation: See references/ directory Examples: See examples/ directory Integration: See INTEGRATION.md

Version: 1.0.0 Status: Stable, Security-Audited Test Coverage: 85%+ Performance: 80x faster than target