evnx diff — Command Reference

Compare .env and .env.example files to identify missing, extra, and mismatched variables with security-first defaults and predictable output.

Command signature

evnx diff [OPTIONS]

Options reference

Format values

Exit codes

evnx diff && echo "✅ Env files in sync" || echo "❌ Drift detected"

Output structure by format

pretty format (default)

Human-readable output with colored status indicators:

┌─ Comparing .env ↔ .env.example ─────────────────────┐
└──────────────────────────────────────────────────────┘

Missing from .env (present in .env.example):
  + NEW_FEATURE_FLAG

Extra in .env (not in .env.example):
  - DEPRECATED_VAR

Different values:
  ~ DATABASE_URL
    .env.example: postgresql://localhost:5432/dev
    .env: postgresql://prod-server:5432/prod

Summary:
  + 1 missing (add to .env)
  - 1 extra (consider removing or adding to .env.example)
  ~ 1 different values

json format

Machine-readable output for programmatic consumption:

{
  "missing": ["NEW_FEATURE_FLAG"],
  "extra": ["DEPRECATED_VAR"],
  "different": [
    {
      "key": "DATABASE_URL",
      "example_value": "postgresql://localhost:5432/dev",
      "env_value": "postgresql://prod-server:5432/prod",
      "example_value_redacted": null,
      "env_value_redacted": null
    }
  ],
  "stats": {
    "total_keys_env": 12,
    "total_keys_example": 13,
    "overlap_count": 11,
    "similarity_percent": 84.62
  }
}

patch format

Unified diff-style output for automation:

# Add these to .env:
+ NEW_FEATURE_FLAG=placeholder

# Remove these from .env:
- DEPRECATED_VAR=old_value

# Update these in .env:
- DATABASE_URL=postgresql://prod-server:5432/prod
+ DATABASE_URL=postgresql://localhost:5432/dev

Sensitive key auto-redaction

Keys matching these patterns (case-insensitive) have values auto-redacted in output:

Redaction behavior:

• ›Default mode (--show-values not set): All values shown as ***
• ›With --show-values: Non-sensitive keys show full values; sensitive keys show first 2 chars + ***
• ›JSON output: Includes both original (example_value) and redacted (example_value_redacted) fields when applicable

Key order preservation

Output order matches insertion order from the source files (not hash order):

# .env.example contents (insertion order):
Z_LAST=value
A_FIRST=value
M_MIDDLE=value

# Output shows missing/extra keys in file order:
Missing from .env:
  + Z_LAST
  + A_FIRST
  + M_MIDDLE

This ensures predictable, reproducible output for:

• ›✅ Code review diffs
• ›✅ CI/CD log comparison
• ›✅ Automated patch application

Interactive merge mode (--format patch --interactive)

When both --format patch and --interactive are specified, evnx prompts for selective change application:

🔧 Interactive Merge Mode
Prompts: (y)es, (n)o, (s)kip rest

➕ Add NEW_FEATURE_FLAG=placeholder? [y/n/s]: y
   ✓ Queued: + NEW_FEATURE_FLAG=placeholder

✏️  Update DATABASE_URL?
   - postgresql://prod-server:5432/prod
   + postgresql://localhost:5432/dev? [y/n/s]: n
   ✗ Skipped

📋 Applied changes:
  + NEW_FEATURE_FLAG=placeholder

💡 Tip: Save output and apply with: patch -p1 < changes.patch

Statistics reference (--with-stats)

When --with-stats is passed with --format json, the output includes a stats object:

Similarity interpretation:

• ›100.0: Files have identical key sets
• ›50.0: Half the keys overlap (e.g., 1 shared key out of 2 total each)
• ›0.0: No keys in common

Environment variables

Troubleshooting

"Failed to parse" error

✗ Failed to parse .env: Invalid format at line 5: missing '=' separator

Solution: Check the indicated line for malformed KEY=value syntax. Comments (#) and blank lines are allowed; export prefix is supported.

No output despite expected differences

✓ Files are identical

Check:

1. ›Are you comparing the correct files? Use --env and --example to specify paths explicitly
2. ›Are keys being filtered by --ignore-keys? Remove the flag or verify the key list
3. ›Is --reverse changing the comparison direction unexpectedly?

Sensitive values still visible in output

  + DB_PASSWORD = mysecretpassword123

Solution:

• ›Omit --show-values to hide all values: evnx diff
• ›Or ensure the key name contains a sensitive pattern: rename DB_PASSWORD → DATABASE_PASSWORD (still matches)

JSON output missing stats field

{
  "missing": [...],
  "extra": [...],
  "different": [...]
  // stats field absent
}

Solution: Add --with-stats flag: evnx diff --format json --with-stats

See also

• ›Diff Basics Tutorial — Step-by-step comparison workflows
• ›Security Best Practices — Managing secrets in environment files
• ›CI/CD Integration — Enforcing environment consistency in pipelines
• ›Configuration Reference — Advanced .env parsing options
• ›Sync Command — Automatically reconcile differences instead of just detecting them