env-manager

Environment Variable Manager

Overview

Manage environment variables systematically across local development, CI/CD pipelines, and deployment platforms. Prevent common issues like missing variables, exposed secrets, platform misconfigurations, and framework-specific gotchas.

Core capabilities:

• Validation: Check structure, completeness, naming conventions
• Security: Scan for exposed secrets, validate .gitignore coverage
• Synchronization: Sync with deployment platforms and secret managers
• Framework Support: Next.js, Express, Flask, Django patterns
• Documentation: Auto-generate .env.example and setup guides

When to Use This Skill

Activate when:

• Setting up new project environment configuration
• Deploying to Vercel, Railway, Heroku, or other platforms
• Troubleshooting "works locally but not in production"
• Managing secrets across multiple environments
• Syncing variables with 1Password, AWS Secrets Manager
• Creating .env.example documentation
• Onboarding new developers (environment setup)
• Migrating between deployment platforms
• Framework-specific env configuration (Next.js NEXT_PUBLIC_ prefix)

Core Principles

1. Never Log Secrets: All operations must NEVER display actual secret values
2. Validate Before Deploy: Catch env issues locally, not in production
3. Framework-Aware: Respect framework conventions (Next.js, Express, Flask)
4. Platform-Specific: Generate correct configs for each deployment platform
5. Security First: Scan for exposed secrets, validate .gitignore

Quick Start

Validation Workflow

# 1. Check local .env structure
python scripts/validate_env.py .env

# 2. Check for missing variables
python scripts/validate_env.py .env --compare .env.example

# 3. Validate naming conventions
python scripts/validate_env.py .env --framework nextjs

# 4. Check for duplicates
python scripts/validate_env.py .env --check-duplicates

Security Workflow

# 1. Scan for exposed secrets in code
python scripts/scan_exposed.py --scan-code

# 2. Check .gitignore coverage
python scripts/scan_exposed.py --check-gitignore

# 3. Validate secret formats
python scripts/scan_exposed.py --validate-formats .env

Synchronization Workflow

# 1. Compare local vs platform
python scripts/sync_secrets.py --platform vercel --compare

# 2. Generate platform config
python scripts/sync_secrets.py --platform vercel --generate

# 3. Sync to platform (dry-run first)
python scripts/sync_secrets.py --platform vercel --sync --dry-run

# 4. Actual sync
python scripts/sync_secrets.py --platform vercel --sync

Documentation Workflow

# Generate .env.example from .env
python scripts/validate_env.py .env --generate-example

# Generate setup documentation
python scripts/validate_env.py .env --generate-docs

Navigation

For detailed workflows and patterns:

• Validation: Complete validation workflows and checks
• Security: Secret scanning and security patterns
• Synchronization: Platform sync and secret manager integration
• Frameworks: Framework-specific patterns (Next.js, Express, Flask)
• Troubleshooting: Common issues and solutions

Framework-Specific Quick Reference

Next.js

# Validate Next.js env structure
# - NEXT_PUBLIC_* for client-side vars
# - Check .env.local, .env.production precedence
python scripts/validate_env.py .env --framework nextjs

# Files to manage:
# - .env.local (local development, gitignored)
# - .env.production (production, usually from platform)
# - .env (shared defaults, committed)
# - .env.example (documentation, committed)

Express/Node.js

# Validate Node.js env structure
python scripts/validate_env.py .env --framework nodejs

# Standard structure:
# - process.env.NODE_ENV
# - process.env.PORT
# - process.env.DATABASE_URL

Python/Flask

# Validate Python env structure
python scripts/validate_env.py .env --framework python

# Standard structure:
# - FLASK_APP
# - FLASK_ENV
# - DATABASE_URL (SQLAlchemy format)

Platform-Specific Quick Reference

Vercel

# Generate vercel.json env config
python scripts/sync_secrets.py --platform vercel --generate

# Sync to Vercel project
python scripts/sync_secrets.py --platform vercel --sync

# Respects NEXT_PUBLIC_ prefix for client-side vars

Railway

# Generate Railway config
python scripts/sync_secrets.py --platform railway --generate

# Sync to Railway project
python scripts/sync_secrets.py --platform railway --sync

Heroku

# Generate Heroku config
python scripts/sync_secrets.py --platform heroku --generate

# Sync via Heroku CLI
python scripts/sync_secrets.py --platform heroku --sync

Key Reminders

• NEVER log actual secret values - Always mask/redact in output
• Validate before every deployment - Catch issues locally
• Use .env.example for documentation - Keep it updated
• Framework conventions matter - Next.js NEXT_PUBLIC_, Django DJANGO_SETTINGS_MODULE
• Platform-specific quirks exist - Vercel auto-exposes NEXT_PUBLIC_*, Railway uses exact syntax
• Secret managers are your friend - 1Password, AWS Secrets Manager for team sync
• .gitignore is critical - NEVER commit .env files with secrets
• Environment precedence can be tricky - Know your framework's loading order

Common Validation Checks

Structure Validation

• No empty values (except explicitly allowed)
• No inline comments (some parsers don't support)
• Proper quoting for values with spaces
• No duplicate keys
• Valid key naming (UPPERCASE_WITH_UNDERSCORES)

Security Validation

• No exposed secrets in code
• .env files in .gitignore
• No secrets in git history
• API keys match expected format
• No hardcoded URLs with credentials

Framework Validation (Next.js)

• NEXT_PUBLIC_* for client-side vars only
• No secrets in NEXT_PUBLIC_* vars
• .env.local exists for local secrets
• .env.example documents all vars

Platform Validation (Vercel)

• All required vars defined
• No conflicts between environments
• Correct variable names (Vercel conventions)
• Build-time vs runtime vars separated

Integration with Other Skills

Related Skills

• docker-containerization - Environment variables in containers
• security-scanning - Broader security checks including secrets
• nextjs-local-dev - Next.js specific development patterns
• systematic-debugging - Debug env-related issues

Workflow Integration

1. Developer creates .env.local
2. env-manager validates structure
3. env-manager scans for security issues
4. Developer generates .env.example
5. Before deploy: env-manager compares local vs platform
6. env-manager generates platform config
7. Developer reviews and confirms sync
8. env-manager syncs to platform
9. Deployment proceeds with verified configuration

Lines: 197 (including frontmatter) ✓ <200