EnvLock CLI

A comprehensive CLI tool for .env file health checks. Scan your environment variables for missing values, security risks, syntax issues, Git history problems, logging detection, naming consistency, and more.

Installation

npm install -g @envlock/cli

Requirements

• Node.js >= 18.0.0
• Dependencies: chalk (~5), commander (~14), dotenv (~17), glob (~13), ora (~9), simple-git (~3)

Usage

# Scan current directory
envlock health

# Scan specific directory
envlock health /path/to/project

# Auto-fix missing variables with placeholders in all .env files
envlock health --fix

# Auto-create .env files if missing
envlock health --fix --yes

# Enable experimental auto-discovery of env vars from node_modules
envlock health --discover-deps

# Compare two env files
envlock compare .env .env.production

# Control output
envlock health --no-show-unused --no-show-stats

# Show detailed dependency tree
envlock health --details

# Strict mode (warnings as errors)
envlock health --strict

# Custom file patterns
envlock health --include-files "shared/**/*.js" --exclude-files "node_modules/**"

Example Output

[SCAN] EnvLock Health Check - my-project
- Phase 1: Loading environment files and scanning code...
✔ Loaded 5 variables from .env files, 3 from examples; found 6 variables referenced in code
- Phase 2: Analyzing dependencies and checking variables...
✔ Analyzed dependencies (2 required by 1 packages); found 2 missing, 1 unused variables; identified 1 security risks
- Phase 3: Detecting issues and reviewing history...
✔ Detected 0 logged variables, 1 syntax issues; found 0 Git history flags
- Phase 4: Validating metadata and consistency...
✔ Validated metadata (found 0 expired variables); checked naming (0 inconsistencies) and frameworks (0 warnings)
- Phase 5: Finalizing analysis...
✔ Analysis complete

- Missing Variables
API_KEY
DATABASE_URL (Required by: prisma@^5.0.0)

! Security Risks
AWS_SECRET_KEY - potential secret based on naming pattern

- Syntax Issues
.env:5 - Unquoted value with spaces

- Unused Variables
DEBUG

Actions needed: 4 fixes

✓ Health check completed!

For repos with many issues, sections show up to 10 items with "... and X more" indicators to prevent overwhelming output. The clean UI uses minimal, meaningful symbols for scannability while maintaining professional appearance.

Features

• Missing Variables: Detects env vars used in code but not defined in .env/.env.example files
• Unused Variables: Finds env vars defined in .env but not referenced in code or examples
• Security Risks: Flags potential secrets based on naming patterns and actual secret values in examples
• Logging Detection: Identifies when sensitive env vars are logged in code
• Naming Consistency: Warns about inconsistent naming conventions (snake_case vs camelCase)
• Expiration Metadata: Parses @expire comments and warns about expired variables
• Framework Warnings: Enforces prefix conventions for Vite, React, Vue, etc.
• Dependency Tracking: Detects env vars required by 3rd-party packages (87+ packages, Node.js/Python)
• Auto-Discovery: Experimental mode to scan node_modules for undocumented env vars
• File Comparison: Compare two .env files with detailed diffs
• Syntax Validation: Checks for .env file syntax errors (invalid lines, unquoted spaces)
• Git History: Scans commits for AI-generated changes and flags commits that modified .env files
• Action Summary: Shows total number of fixes needed
• Auto-Fix: Adds placeholder values to all .env files (.env, .env.local, .env.example, .env.example.local)
• Output Controls: Hide unused vars or stats, strict mode for CI/CD
• Monorepo Support: Custom include/exclude patterns for shared configs
• Ignores: Automatically skips common directories with customizable patterns

Dependency Tracking

EnvLock automatically detects environment variables required by your 3rd-party packages:

• Node.js: Parses package.json dependencies (ignores devDependencies)
• Python: Parses requirements.txt or Pipfile
• Monorepos: Supports workspaces in package.json
• Built-in Map: 87+ popular packages mapped to required env vars (e.g., DATABASE_URL for Prisma)
• Auto-Discovery: Experimental --discover-deps flag scans node_modules READMEs for undocumented env vars
• Output Integration: Missing/unused vars show "Required by: package@version"
• Priority: Missing dep-required vars are highlighted prominently in output
• Details View: Use --details to see full dependency tree table

License

MIT