evnx

A CLI tool for managing .env files — validation, secret scanning, format conversion, and migration to cloud secret managers.

Website | Getting Started | Changelog

Why evnx?

Accidentally committing secrets to version control is one of the most common and costly developer mistakes. evnx is a local-first tool that catches misconfigurations, detects credential leaks, and converts environment files to the format each deployment target expects — before anything reaches CI or production.

Testing & playground

→ urwithajit9/evnx-test — try evnx in your browser via GitHub Actions, no installation required.

Installation

Linux / macOS

curl -sSL https://raw.githubusercontent.com/urwithajit9/evnx/main/scripts/install.sh | bash

Homebrew (macOS and Linux)

brew install urwithajit9/evnx/evnx

npm

npm install -g @evnx/cli

pipx (recommended for Python environments)

pipx install evnx

pipx installs CLI tools into isolated environments and wires them to your system PATH automatically. It is the correct tool for installing Python- distributed CLI binaries like evnx.

Don't have pipx?

macOS

brew install pipx
pipx ensurepath

Ubuntu / Debian (Python 3.11+)

sudo apt install pipx
pipx ensurepath

On older Ubuntu (20.04 and below) where pipx is not in apt:

pip install --user pipx
python -m pipx ensurepath

Note: pip install evnx will fail on Ubuntu 22.04+ with an "externally managed environment" error (PEP 668). This is intentional — Ubuntu protects the system Python. Use pipx instead.

Windows

python -m pip install --user pipx
python -m pipx ensurepath

After running ensurepath, close and reopen your terminal (a full logout/login may be required for PATH changes to take effect), then:

pipx install evnx

After installing pipx on any platform, restart your terminal and run:

pipx install evnx
evnx --version

Cargo

cargo install evnx
# with all optional features
cargo install evnx --all-features

Windows

Scoop (user-local, no admin required)

scoop bucket add evnx https://github.com/urwithajit9/scoop-evnx
scoop install evnx

Winget (system-wide)

winget install urwithajit9.evnx

Cargo (Windows)

Install Rust first, then:

cargo install evnx
evnx --version

Verify

evnx --version
evnx --help

Commands

evnx init

Interactive project setup. Creates .env and .env.example files for your project through a guided TUI.

evnx init

Running evnx init launches an interactive menu with three modes:

How do you want to start?
  Blank      — create empty .env files
  Blueprint  — use a pre-configured stack (Python, Node.js, Rust, Go, PHP, and more)
  Architect  — build a custom stack by selecting services interactively

There are no flags required. The interactive flow handles stack and service selection inside the TUI.

evnx add

Add variables to an existing .env file interactively. Supports custom input, service blueprints, and variable templates.

evnx add

evnx validate

Validates your .env file for common misconfigurations before deployment.

evnx validate                            # pretty output
evnx validate --strict                   # exit non-zero on warnings
evnx validate --format json              # machine-readable output
evnx validate --format github-actions    # inline GitHub annotations

Detects: missing required variables, placeholder values (YOUR_KEY_HERE, CHANGE_ME), the boolean string trap (DEBUG="False" is truthy in most runtimes), weak secret keys, localhost in production, and suspicious port numbers.

evnx scan

Scans files for accidentally committed credentials using pattern matching and entropy analysis.

evnx scan                         # scan current directory
evnx scan --path src/             # specific path
evnx scan --format sarif          # SARIF output for GitHub Security tab
evnx scan --exit-zero             # warn but do not fail CI

Detects: AWS Access Keys, Stripe keys (live and test), GitHub tokens, OpenAI and Anthropic API keys, RSA/EC/OpenSSH private keys, high-entropy strings, and generic API key patterns.

evnx diff

Compares .env and .env.example and shows what is missing, extra, or mismatched.

evnx diff                     # compare .env vs .env.example
evnx diff --show-values       # include actual values
evnx diff --reverse           # swap comparison direction
evnx diff --format json       # JSON output

evnx convert

Converts your .env file to 14+ output formats for various deployment targets.

evnx convert --to json
evnx convert --to yaml
evnx convert --to shell
evnx convert --to docker-compose
evnx convert --to kubernetes
evnx convert --to terraform
evnx convert --to github-actions
evnx convert --to aws-secrets
evnx convert --to gcp-secrets
evnx convert --to azure-keyvault
evnx convert --to heroku
evnx convert --to vercel
evnx convert --to railway
evnx convert --to doppler

Advanced filtering and transformation:

evnx convert --to json \
  --output secrets.json \
  --include "AWS_*" \
  --exclude "*_LOCAL" \
  --prefix "APP_" \
  --transform uppercase \
  --base64

Pipe directly to AWS Secrets Manager:

evnx convert --to aws-secrets | \
  aws secretsmanager create-secret \
    --name prod/myapp/config \
    --secret-string file:///dev/stdin

evnx sync

Keeps .env and .env.example aligned, in either direction.

# Forward: .env → .env.example (document what you have)
evnx sync --direction forward --placeholder

# Reverse: .env.example → .env (generate env from template)
evnx sync --direction reverse

evnx migrate (requires --features migrate)

Migrates secrets directly to cloud secret managers.

# GitHub Actions secrets
evnx migrate --from env-file --to github-actions \
  --repo owner/repo --github-token $GITHUB_TOKEN

# AWS Secrets Manager
evnx migrate --to aws-secrets-manager --secret-name prod/myapp/config

# Doppler (with dry run)
evnx migrate --to doppler --dry-run

evnx doctor

Runs a health check on your environment configuration setup.

evnx doctor                          # check current directory
evnx doctor --path /path/to/project

Checks: .env exists and has secure permissions, .env is in .gitignore, .env.example is tracked by Git, and project structure detection.

evnx template

Generates configuration files from templates using .env variable substitution.

evnx template \
  --input config.template.yml \
  --output config.yml \
  --env .env

Supported inline filters:

database:
  host: {{DB_HOST}}
  port: {{DB_PORT|int}}
  ssl:  {{DB_SSL|bool}}
  name: {{DB_NAME|upper}}

evnx backup / evnx restore (requires --features backup)

Creates and restores AES-256-GCM encrypted backups using Argon2 key derivation.

evnx backup .env --output .env.backup
evnx restore .env.backup --output .env

CI/CD Integration

GitHub Actions

name: Validate environment

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install evnx
        run: |
          curl -sSL https://raw.githubusercontent.com/urwithajit9/evnx/main/scripts/install.sh | bash

      - name: Validate configuration
        run: evnx validate --strict --format github-actions

      - name: Scan for secrets
        run: evnx scan --format sarif > scan-results.sarif

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: scan-results.sarif

GitLab CI

validate-env:
  stage: validate
  image: alpine:latest
  before_script:
    - apk add --no-cache curl bash
    - curl -sSL https://raw.githubusercontent.com/urwithajit9/evnx/main/scripts/install.sh | bash
  script:
    - evnx validate --strict --format json
    - evnx scan --format sarif > scan.sarif
  artifacts:
    reports:
      sast: scan.sarif

pre-commit / prek Integration

Use evnx as automatic git hooks via pre-commit or prek — no manual evnx install needed. The binary is compiled and cached automatically on first run.

Add to .pre-commit-config.yaml:

default_install_hook_types: [pre-commit, pre-push]

repos:
  - repo: https://github.com/urwithajit9/evnx
    rev: v0.3.6
    hooks:
      - id: evnx-scan        # blocks commit if secrets found
      - id: evnx-validate    # blocks commit if .env misconfigured
      - id: evnx-diff        # warns on .env/.env.example drift
      - id: evnx-scan-push   # strict scan on push

Then install:

pre-commit install   # or: prek install

That's it. On your next commit, hooks will auto-compile and run.

Configuration

Store defaults in .evnx.toml at the project root:

[defaults]
env_file = ".env"
example_file = ".env.example"
verbose = false

[validate]
strict = true
auto_fix = false
format = "pretty"

[scan]
ignore_placeholders = true
exclude_patterns = ["*.example", "*.sample", "*.template"]
format = "pretty"

[convert]
default_format = "json"
base64 = false

[aliases]
gh = "github-actions"
k8s = "kubernetes"
tf = "terraform"

Known Limitations

Array and multiline values — evnx follows the strict .env spec where values are simple strings. The following will not parse correctly:

# Not supported
CORS_ALLOWED=["https://example.com", "https://admin.example.com"]
CONFIG={"key": "value"}
DATABASE_HOSTS="""
host1.example.com
host2.example.com
"""

Use comma-separated strings and parse them in application code. A --lenient flag for extended syntax is under consideration — see open issues.

Windows — file permissions checking is limited (no Unix permission model). Terminal color support requires PowerShell or Windows Terminal on older systems.

Development

git clone https://github.com/urwithajit9/evnx.git
cd evnx

cargo build                          # core features only
cargo build --all-features
cargo test
cargo clippy --all-features -- -D warnings
cargo fmt

Feature flags:

[features]
default = []
migrate = ["reqwest", "base64", "indicatif"]
backup  = ["aes-gcm", "argon2", "rand"]
full    = ["migrate", "backup"]

Contributing

See CONTRIBUTING.md. Contributions are welcome in: additional format converters, secret pattern improvements, Windows enhancements, extended .env format support, and integration examples.

License

MIT — see LICENSE.

Credits

Built by Ajit Kumar.

Related projects: python-dotenv, dotenvy, direnv, git-secrets.

Website | Issues | Discussions | Email