bobmatnyc/env-manager

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 <file> [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 <repo>
cd <project>

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

1. Never Logs Secrets: env-manager NEVER displays actual secret values in output
2. Client-Exposure Detection: Warns when secrets are in NEXT_PUBLIC_, VITE_, REACT_APP_ variables
3. Secret Sanitization: When generating .env.example, replaces secrets with safe placeholders
4. 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:

1. Line endings (CRLF vs LF)
2. File encoding (UTF-8 expected)
3. File permissions
4. 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:

1. Move secret to server-side variable (remove NEXT_PUBLIC_ prefix)
2. Use public/publishable keys only in client-exposed variables
3. If truly not a secret, ignore the warning

.env.example generation replaces too much

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

1. Manually edit .env.example after generation
2. 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:

1. Run make lint-fix during development
2. Run make quality before commits
3. Add tests for new features (85%+ coverage required)
4. 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