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:

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.

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

env-manager

Environment Variable Manager (env-manager)

Overview

Why Use env-manager?

Quick Start

Installation

5-Minute Quick Start

Usage Examples

Basic Validation

Framework-Specific Validation

Next.js

Vite

React (Create React App)

Node.js/Express

Flask/Python

Comparing with .env.example

Generating .env.example

CI/CD Integration

Strict Mode

Quiet Mode

Supported Frameworks

CLI Reference

Command Structure

Options

Exit Codes

Common Use Cases

Scenario 1: New Developer Onboarding

Scenario 2: Pre-Deployment Check

Scenario 3: Security Audit

Scenario 4: Team Documentation

Scenario 5: CI/CD Quality Gate

Performance

Security Notes

Common Issues

"Missing equals sign" error

"Duplicate key" error

"Invalid variable name" warning

"Potential secret in client-exposed variable" warning

"Empty value" warning

File not found error

Troubleshooting

Validation passes locally but fails in CI

Warnings about client-exposed variables

.env.example generation replaces too much

Advanced Usage

Custom Validation Patterns

Platform-Specific Deployment

Framework-Specific Guides

Related Documentation

Integration with Claude MPM

Contributing

License

Support