Metadata-Version: 2.4
Name: evnx
Version: 0.3.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
License-File: LICENSE
Summary: evnx — blazing-fast environment variable manager and inspector built in Rust
Keywords: cli,devtools,environment,env,dotenv,evnx
Home-Page: https://evnx.dev
Author-email: Ajit Kumar <ajitkumar.pu@gmail.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/urwithajit9/evnx/issues
Project-URL: Changelog, https://github.com/urwithajit9/evnx/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/urwithajit9/evnx#readme
Project-URL: Homepage, https://github.com/urwithajit9/evnx
Project-URL: Repository, https://github.com/urwithajit9/evnx

# evnx

[![CI](https://github.com/urwithajit9/evnx/workflows/CI/badge.svg)](https://github.com/urwithajit9/evnx/actions)
[![Release](https://img.shields.io/github/v/release/urwithajit9/evnx)](https://github.com/urwithajit9/evnx/releases)
[![crates.io](https://img.shields.io/crates/v/evnx.svg)](https://crates.io/crates/evnx)
[![PyPI](https://img.shields.io/pypi/v/evnx.svg)](https://pypi.org/project/evnx/)
[![npm](https://img.shields.io/npm/v/@evnx/cli.svg)](https://www.npmjs.com/package/@evnx/cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

[Website](https://www.evnx.dev) | [Getting Started](./docs/GETTING_STARTED.md) | [Changelog](./CHANGELOG.md)

---

## 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.

---

## Installation

### Linux / macOS

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

### npm

```bash
npm install -g @evnx/cli
```

### pipx (recommended for Python environments)

```bash
pipx install evnx
```

> `pip install evnx` also works but places the binary inside the active virtualenv's `bin/` directory.
> Use `pipx` to make `evnx` available system-wide without managing a virtualenv manually.

### Cargo

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

### Windows

Install [Rust](https://rustup.rs/) first, then:

```powershell
cargo install evnx
evnx --version
```

### Verify

```bash
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.

```bash
evnx add
```

---

### `evnx validate`

Validates your `.env` file for common misconfigurations before deployment.

```bash
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.

```bash
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.

```bash
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.

```bash
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:

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

Pipe directly to AWS Secrets Manager:

```bash
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.

```bash
# 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.

```bash
# 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.

```bash
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.

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

Supported inline filters:

```yaml
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.

```bash
evnx backup .env --output .env.backup
evnx restore .env.backup --output .env
```

---

## CI/CD Integration

### GitHub Actions

```yaml
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

```yaml
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 hook

```yaml
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: evnx-validate
        name: Validate .env files
        entry: evnx validate --strict
        language: system
        pass_filenames: false

      - id: evnx-scan
        name: Scan for secrets
        entry: evnx scan --exit-zero
        language: system
        pass_filenames: false
```

---

## Configuration

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

```toml
[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:

```bash
# 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](https://github.com/urwithajit9/evnx/issues).

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

---

## Development

```bash
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:

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

---

## Contributing

See [CONTRIBUTING.md](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](LICENSE).

---

## Credits

Built by [Ajit Kumar](https://github.com/urwithajit9).

Related projects: [python-dotenv](https://github.com/theskumar/python-dotenv), [dotenvy](https://github.com/allan2/dotenvy), [direnv](https://direnv.net/), [git-secrets](https://github.com/awslabs/git-secrets).

---

[Website](https://www.evnx.dev) | [Issues](https://github.com/urwithajit9/evnx/issues) | [Discussions](https://github.com/urwithajit9/evnx/discussions) | [Email](mailto:support@evnx.dev)
