evnx sync — Command Reference

Keep .env and .env.example in perfect synchronization with bidirectional sync, smart placeholder generation, and built-in security guards.

Command signature

evnx sync [OPTIONS]

Options reference

Direction values

Naming policy values

Placeholder generation rules

When adding variables with placeholders, evnx uses these built-in heuristics (customizable via --template-config):

Exit codes

Basic usage examples

Forward sync (default)

# Update .env.example with new variables from .env
# Interactive: choose placeholder vs actual values
evnx sync

Reverse sync

# Pull new variables from .env.example to .env
# Interactive: choose placeholder vs prompt for real values
evnx sync --direction reverse

Preview without changes

# See what would change before applying
# Shows 🔒 for placeholders, ⚠️ for actual values
evnx sync --dry-run

CI/CD mode (safe defaults)

# Skip prompts, always use placeholders, fail on naming issues
# Actual values option is disabled for security
evnx sync --force --naming-policy error

Custom placeholder config

# Use team-specific placeholder patterns with regex
# Example placeholders.json:
# {
#   "patterns": {
#     "AWS_.*": "aws_placeholder",
#     "STRIPE_.*": "sk_test_xxx"
#   },
#   "default": "TEAM_DEFAULT_VALUE"
# }
evnx sync --template-config .evnx/placeholders.json

Strict naming validation

# Fail if any variable doesn't match UPPERCASE_WITH_UNDERSCORES
evnx sync --naming-policy error

Interactive mode behavior

Forward sync prompts

When new variables are found in .env but not .env.example:

┌─ Variables to Add ─────────────────────────────────────┐
│ Found 2 variable(s) in .env missing from .env.example:│
│   • NEW_API_KEY                                       │
│   • DATABASE_URL                                      │
└────────────────────────────────────────────────────────┘

Add these to .env.example?
❯ Yes, add with placeholder values (recommended)
  Yes, add with actual values ⚠️ SECURITY RISK
  Let me choose individually
  No, skip

Reverse sync prompts

When new variables are found in .env.example but not .env:

┌─ Missing Variables ────────────────────────────────────┐
│ Found 2 variable(s) in .env.example missing from .env:│
│   • NEW_FEATURE_FLAG                                  │
│   • OPTIONAL_CONFIG                                   │
└────────────────────────────────────────────────────────┘

Add to .env?
❯ Yes, with placeholder values
  Yes, prompt me for real values
  Let me choose individually
  No, skip

Security features

File permissions check

On Unix systems, evnx warns if .env has overly permissive permissions:

⚠️ .env has permissive permissions (0o664). Consider: chmod 600 .env
ℹ️ Overly permissive .env files may expose secrets to other users

Recommendation: Always use chmod 600 .env to restrict access to owner only.

Atomic file writes

All file modifications use atomic write operations:

1. ›Write to temporary file in same directory
2. ›Sync to disk with fsync
3. ›Atomic rename to target path

This prevents file corruption from interrupted operations or power loss.

Force mode safety

When --force is used:

• ›Interactive prompts are skipped entirely
• ›Placeholder values are always used (actual values option disabled)
• ›Suitable for CI/CD pipelines where non-interactive execution is required

Audit logging

When actual values are added to .env.example (interactive mode only), a security audit message is logged to stderr in verbose mode:

[AUDIT] User added actual values to .env.example for keys: ["SECRET_KEY", "API_TOKEN"]

Environment variables

Troubleshooting

".env file not found" error

✗ File not found: .env

┌─ 💡 Getting Started ─────────────────────────────────┐
│ It looks like this project hasn't been initialized   │
│ yet. To create .env and .env.example files, run:     │
│                                                      │
│ $ evnx init                                          │
└──────────────────────────────────────────────────────┘

Solution: Run evnx init to create template files, or copy your existing .env to the project directory.

".env.example not found" in reverse sync

✗ File not found: .env.example

┌─ 💡 Getting Started ─────────────────────────────────┐
│ The template file .env.example is missing.           │
│ To create it, either:                                │
│ 1. Run 'evnx init' to generate from a blueprint, OR │
│ 2. Create .env.example manually with your variables │
└──────────────────────────────────────────────────────┘

Solution: Run evnx init or create .env.example manually with variable names (values can be placeholders).

Non-standard variable name warnings

⚠️ Variable 'myCamelCaseVar' doesn't follow convention (UPPERCASE_WITH_UNDERSCORES)

Solution: Rename to MY_CAMEL_CASE_VAR, or use --naming-policy ignore for legacy projects.

Placeholder not matching expected pattern

If a variable like DATABASE_URL gets YOUR_URL_HERE instead of a PostgreSQL template:

Check: The original value in .env must start with postgresql:// (not just postgres://) to trigger the specialized template.

Fix: Update the value format, or use --template-config to define custom patterns:

{
  "patterns": {
    "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
  }
}

See also

• ›Sync Basics Tutorial — Learn sync step-by-step with examples
• ›Team Collaboration — Multi-developer workflows and merge strategies
• ›CI/CD Integration — Automation setup for GitHub Actions, GitLab CI, etc.
• ›Configuration Reference — Advanced placeholder config and pattern syntax
• ›Security Best Practices — Protecting secrets in environment files