zorath-env

Open Sourcev0.3.13

Package: zorath-env | Binary: zenv

AI-native .env validation in any language

Single-binary .env validation with a local stdio MCP server, typed JSON/YAML schemas, hash-pinned remote inheritance, and 22 secret-detection patterns. 14 commands, 14 validation types, 7 export formats, 9-language code scanning, and a Claude Code skill. Language-agnostic, no hosting or telemetry, and no language runtime to install.

14 types7 export formats9 language scan22 secret patterns6 framework presets841+ tests

cargo +stable install zorath-env --locked

View on crates.io

Get Started View on GitHub

Features

AI-Native: MCP Server

Run zenv mcp as a local subprocess of an MCP client. Uses JSON-RPC 2.0 over stdio and advertises protocol version 2025-11-25. Exposes 5 tools (check, scan, diff, doctor, docs), 3 resources (schema, masked env, docs), and 3 prompts (audit_env, new_var_workflow, diagnose_missing). No hosted service or telemetry. Client lifecycle and cancellation compatibility still require client-specific testing.

Claude Code Skill

Plain-markdown Claude Code skill at integrations/claude-code/SKILL.md teaches Claude to drive zenv against .env files in any project. Drops into ~/.claude/skills/zenv/ with a single curl. Auto-triggers on .env / schema / env-var-management tasks. Covers all 14 subcommands, structured exit codes, schema authoring, remote schema security flags, and the anti-patterns the agent must avoid (never fix without --dry-run, never commit raw .env, never include actual secret values in output).

Secret Detection

22 built-in regex patterns plus value-aware URL-password and webhook-URL detection. Catches AWS, OpenAI, Anthropic, Stripe, GitHub, GitLab, Discord webhooks, Slack webhooks, HuggingFace, Datadog, Google, Heroku, SendGrid, Twilio, Mailchimp, npm tokens, private keys, JWT, and more. Value-aware detection catches embedded secrets like postgres://user:credential@host regardless of the variable name. Runs INSIDE the env-validation pass -- not a separate codebase scan.

Env File Comparison

Compare two .env files to find differences between environments. Catch config drift between dev, staging, and production.

Type Validation

Support for 14 types: string, int, float, bool, url, enum, uuid, email, ipv4, ipv6, semver, port, date, hostname. Catch type mismatches before runtime.

Language Agnostic

Works with any tech stack - Node.js, Python, Go, Ruby, Rust, Java, PHP, and more. Your schema is the source of truth.

CI/CD Ready

Structured exit codes: 0 success, 1 validation failed, 2 file error, 3 schema error. JSON output for machine parsing. Integrate into any CI/CD pipeline or pre-commit hook.

Privacy Focused

Validation runs locally without telemetry or uploading .env values. HTTPS requests occur when you select remote schemas or their inherited parents, and when you run version --check-update. Use local schemas for offline validation.

No Language Runtime

A prebuilt binary needs no Node.js or Python runtime. Install a binary for your supported OS and architecture; Linux release binaries target Ubuntu 24.04/glibc. Use latest stable Rust 1.99.0 for builds; the supported minimum is Rust 1.85 with locked dependencies.

Auto Documentation

Generate markdown or JSON documentation from your schema. Keep your env docs always in sync.

Variable Interpolation

Reference other variables with ${VAR} syntax. Build complex configurations from simple building blocks.

Schema Inheritance

Extend base schemas for environment-specific configurations. DRY principle for your env schemas.

Smart Initialization

Initialize schemas from existing .env.example files with intelligent type inference.

GitHub Action

Official GitHub Action for CI/CD. Validates .env files in your pipeline with prebuilt binaries for fast execution.

Shell Completions

Generate shell completions for bash, zsh, fish, and PowerShell. Tab-complete commands and options.

Validation Rules

Add constraints with min/max for integers, min_value/max_value for floats, min_length/max_length and regex patterns for strings.

Remote Schemas

Fetch schemas from HTTPS URLs for shared team configurations. Automatic caching with 1-hour TTL, --no-cache flag to bypass. Security features: hash verification with --verify-hash, custom CA certificates with --ca-cert, and rate limiting (60s default).

Watch Mode

Continuous validation with --watch. Tracks the .env file and local schema inheritance, handles repeated atomic saves, and reports changes and current validation status.

Type-Aware Placeholders

Generate smart placeholder values based on key names. PORT becomes 3000, DATABASE_URL becomes postgres://..., API_KEY becomes your_api_key_here.

Duplicate Key Detection

Warns about duplicate keys in .env files with line numbers. Catches copy-paste errors before they cause issues.

YAML Schema Support

Define schemas in YAML format (.yaml/.yml) for better readability. JSON and YAML schemas are interchangeable.

Severity Levels

Mark variables with severity: warning to continue validation on failure. Warnings are reported but don't fail CI.

JSON Output

Get machine-readable JSON output with --format json for CI/CD integration and automated processing.

Multi-Format Export

Export .env files to 7 formats: shell scripts, Dockerfile ENV, Kubernetes ConfigMap, JSON, systemd, dotenv, and GitHub Secrets (gh CLI).

Health Diagnostics

Run zenv doctor to inspect the selected schema, .env file, config, cache, and validation results, including interpolation and warning severity.

Auto-Fix

Add missing required variables using defaults or placeholders, and optionally remove unknown keys with --remove-unknown. Preview with --dry-run; applying changes creates a backup. Review placeholders and reported type errors manually.

Code Scanning

Scan source code for environment variable usage with zenv scan. Supports 9 languages and finds unused/missing variables.

Cache Management

Manage remote schema cache with zenv cache: view path, list cached schemas, clear specific URLs or all cache.

CI/CD Templates

Generate ready-to-use CI/CD configurations with zenv template. Supports GitHub Actions, GitLab CI, and CircleCI.

How It Works

Define Your Schema

Create an env.schema.json file that describes your environment variables.

{
  "DATABASE_URL": {
    "type": "url",
    "required": true,
    "description": "PostgreSQL connection string"
  },
  "PORT": {
    "type": "int",
    "required": false,
    "default": 3000,
    "description": "Server port"
  },
  "DEBUG": {
    "type": "bool",
    "required": false,
    "default": false
  }
}

Create Your .env File

Add your environment variables as usual.

DATABASE_URL=postgresql://localhost:5432/mydb
PORT=8080
DEBUG=true

Validate

Run zenv to validate your .env against the schema.

$ zenv check

zenv: OK

Quick Reference

Commands

zenv check

Validates your .env file against the schema. Optionally scan for leaked secrets. Returns exit code 0 on success, 1 on failure.

zenv diff

Compare two .env files and show differences. Find variables only in one file, or with different values.

zenv init

Generates a schema file from an existing .env.example file with intelligent type inference and smart description generation based on key names.

zenv docs

Generates documentation from your schema. Outputs to stdout.

zenv example

Generate .env.example from schema (reverse of init).

zenv version

Displays the current version of zenv with optional update check and changelog links.

zenv completions

Generate shell completions for bash, zsh, fish, or PowerShell.

zenv export

Export .env files to various deployment formats. Supports 7 output formats for different platforms.

zenv doctor

Run comprehensive health diagnostics. Checks schema validity, .env parsing, config file, remote cache, and validation.

zenv fix

Automatically fix common .env issues. Creates a backup before making changes. Adds missing required variables with schema defaults.

zenv scan

Scan source code for environment variable usage. Finds unused schema variables and undeclared env references.

zenv cache

Manage the remote schema cache. View cache location, list entries, clear cached schemas, or view statistics.

zenv template

Generate CI/CD configuration templates for environment validation. Supports GitHub Actions, GitLab CI, and CircleCI.

zenv mcp

Run the local JSON-RPC server over stdin/stdout for an MCP client. Exposes check, scan, diff, doctor, and docs tools plus schema, masked env, and docs resources. Four tools return JSON serialized in text content; doctor returns plain text. Review masked output and schema defaults before sharing with an AI provider.

Supported Types

stringAny string value

intInteger numbers

floatFloating point numbers

booltrue, false, 1, 0, yes, no

urlValid URL format

enumOne of specified values

uuidUUID v4 format

emailValid email address

ipv4IPv4 address

ipv6IPv6 address

semverSemantic versioning

portValid port (1-65535)

dateISO 8601 date

hostnameValid hostname

Why zenv?

The only .env tool that validates, documents, scans, exports, and fixes -- in a single binary.

Feature	zenv	dotenv-linter	envalid	dotenvx
Schema validation	14 types	--	8 types	--
Secret detection	22 patterns	--	--	scan
Code scanning	9 languages	--	--	--
Export formats	7	--	--	--
Docs generation	MD + JSON	--	--	--
Auto-fix	Yes	Yes	--	--
Watch mode	Delta	--	--	--
Remote schemas	HTTPS + hash	--	--	--
Standalone binary	Yes	Yes	No (Node)	No (Node)
Encryption	--	--	--	AES-256

dotenv-linter checks syntax. envalid validates at runtime in Node.js. dotenvx encrypts secrets. zenv validates semantics at build time -- and does everything else too.

Ready to get started?

Install zorath-env and start validating your environment variables today.

Read the Docs Star on GitHub