zorath-env v0.3.4: Watch Mode for Continuous Environment Validation

zorath-env v0.3.4 is now available. This release introduces Watch Mode for continuous environment validation during development, plus a suite of developer experience improvements that make working with .env files faster and safer.

What is zorath-env?

zorath-env (command: zenv) is a fast, open-source CLI tool that validates .env files against JSON schemas. It catches configuration errors, type mismatches, and leaked secrets before they reach production. Written in Rust, it runs entirely locally with zero dependencies and no telemetry.

Release Highlights

• Watch Mode - Continuous validation with zenv check --watch
• Delta detection - Only shows changed variables, not full re-validation
• Schema watching - Revalidates when your schema changes
• Type-aware placeholders - Smart defaults in zenv example output
• Smart description inference - Auto-generated descriptions from key names
• Duplicate key warnings - Catch copy-paste errors with line numbers
• JSON diff output - Machine-readable output for automation
• Validation rules in docs - Show min/max/pattern constraints
• 205 tests - 16 new tests for comprehensive coverage

Watch Mode

Watch Mode is the headline feature of v0.3.4. Instead of running zenv check manually after every change, Watch Mode monitors your .env file and validates automatically.

How to Use Watch Mode

# Start watching your .env file
zenv check --watch

# Watch a specific file
zenv check --env .env.development --watch

# Watch with secret detection enabled
zenv check --watch --detect-secrets

What Watch Mode Does

1. Initial validation - Runs a full check when you start
2. File monitoring - Watches your .env file for changes
3. Delta detection - Only reports changed variables, not the entire file
4. Schema watching - Detects schema changes and revalidates everything
5. Timestamped output - Shows when each change was detected
6. Terminal bell - Alerts you on errors (disable with terminal settings)

Delta Detection

When you change a variable, Watch Mode shows only what changed:

[14:32:15] Change detected in .env
  PORT: 3000 -> 8080 (valid)

[14:32:45] Change detected in .env
  DATABASE_URL: changed (valid)
  NEW_VAR: added (warning: unknown key)

No more scrolling through dozens of "OK" messages to find the one thing that changed.

Schema Change Detection

If you modify your schema while Watch Mode is running, it detects the change and revalidates your entire .env file against the new schema:

[14:35:00] Schema changed, revalidating...
  All 12 variables valid

This is useful when you're iterating on both your schema and .env file simultaneously.

Watch Mode Use Cases

During development: Keep Watch Mode running in a terminal while you work. Instant feedback when you add or change environment variables.

Testing schema changes: Edit your schema and see immediately which variables now fail validation.

Onboarding new team members: Run zenv check --watch and walk them through required variables. They see validation results as they fill in values.

Developer Experience Improvements

v0.3.4 includes several quality-of-life improvements that make zenv faster to use.

Smart Description Inference

The zenv init command now generates meaningful descriptions from variable names:

# Before v0.3.4
zenv init
# DATABASE_URL: { "type": "string" }

# v0.3.4
zenv init
# DATABASE_URL: { "type": "url", "description": "Database connection URL" }
# STRIPE_API_KEY: { "type": "string", "description": "Stripe API key" }
# AWS_SECRET_ACCESS_KEY: { "type": "string", "description": "AWS secret access key" }

The inference handles common patterns:

Key Pattern	Inferred Description
*_URL	"... URL"
*_API_KEY	"... API key"
*_SECRET	"... secret"
*_TOKEN	"... token"
STRIPE_*	"Stripe ..."
AWS_*	"AWS ..."
GITHUB_*	"GitHub ..."

Type-Aware Placeholders

The zenv example command now generates realistic placeholder values based on type:

zenv example --schema env.schema.json

Output:

# Database connection URL (required)
DATABASE_URL=postgres://user:password@localhost:5432/dbname

# Server port (default: 3000)
PORT=3000

# Enable debug mode
DEBUG=false

# Stripe API key (required)
STRIPE_API_KEY=sk_test_your_stripe_api_key_here

# Application URL
APP_URL=https://example.com

Placeholders are type-aware:

Type	Placeholder
int	3000 (for PORT), 0 otherwise
bool	false
url	https://example.com or protocol-specific
string + _API_KEY	your_*_api_key_here
string + _SECRET	your_*_secret_here

Duplicate Key Warnings

Copy-pasting .env sections can lead to duplicate keys. v0.3.4 detects them:

Warning: Duplicate key 'DATABASE_URL' found
  First occurrence: line 3
  Duplicate: line 15
  Using value from line 15

This catches a common source of "why isn't my config working?" confusion.

Validation Rules in Docs

The zenv docs command now includes validation constraints:

zenv docs --schema env.schema.json

Output:

## PORT

Server port number

- **Type:** int
- **Required:** No
- **Default:** 3000
- **Validation:** min=1024, max=65535

## API_KEY

Service API key

- **Type:** string
- **Required:** Yes
- **Validation:** min_length=32, pattern=^sk_

This makes generated documentation more useful for onboarding.

Actionable Tips for Unknown Keys

When validation finds unknown keys, v0.3.4 suggests what to do:

Warning: 3 unknown keys found: NEW_VAR, CUSTOM_FLAG, EXTRA_URL

Tip: To add them to your schema, run:
  zenv init --env .env --output env.schema.json

JSON Output for Diff

The zenv diff command now supports JSON output for scripting and automation:

zenv diff .env.development .env.production --format json

Output:

{
  "only_in_first": ["DEBUG", "DEV_API_URL"],
  "only_in_second": ["PRODUCTION_KEY"],
  "different_values": [
    {
      "key": "DATABASE_URL",
      "first": "postgres://localhost/dev",
      "second": "postgres://prod-db/main"
    }
  ],
  "identical": ["PORT", "APP_NAME"]
}

Use this in CI/CD pipelines to programmatically detect configuration drift.

Complete Feature Reference

zorath-env includes everything you need for environment variable management. Here's the full feature set as of v0.3.4:

Type Validation

Validate variables against specific types:

{
  "PORT": { "type": "int" },
  "DEBUG": { "type": "bool" },
  "API_URL": { "type": "url" },
  "RATE": { "type": "float" },
  "NAME": { "type": "string" },
  "ENV": { "type": "enum", "values": ["development", "staging", "production"] }
}

Validation Rules

Add constraints beyond basic types:

{
  "PORT": {
    "type": "int",
    "validate": { "min": 1024, "max": 65535 }
  },
  "API_KEY": {
    "type": "string",
    "validate": { "min_length": 32, "pattern": "^sk_" }
  }
}

Available rules:

• min / max - Numeric range
• min_length / max_length - String length
• pattern - Regex pattern matching

Secret Detection

Scan for accidentally committed credentials:

zenv check --detect-secrets

Detects:

• AWS access keys and secret keys
• Stripe API keys (live and test)
• GitHub and GitLab tokens
• Slack tokens
• Google, Heroku, SendGrid, Twilio, Mailchimp API keys
• npm tokens
• Private key headers (RSA, SSH, PGP)
• JWT tokens
• URLs with embedded passwords
• High-entropy strings (potential secrets)

Remote Schemas

Fetch schemas from HTTPS URLs for team-wide configuration:

zenv check --schema https://raw.githubusercontent.com/your-org/config/main/env.schema.json

Features:

• Automatic caching with 1-hour TTL
• --no-cache flag for fresh fetch
• HTTPS-only for security
• Works with all commands

Schema Inheritance

Extend base schemas for environment-specific configs:

{
  "extends": "./base.schema.json",
  "ENVIRONMENT_SPECIFIC_VAR": {
    "type": "string",
    "required": true
  }
}

• Up to 10 levels of inheritance
• Circular reference detection
• Works with remote URLs

Variable Interpolation

Reference other variables in your .env file:

BASE_URL=https://api.example.com
API_ENDPOINT=${BASE_URL}/v1
FULL_URL=$BASE_URL/users

Both ${VAR} and $VAR syntax supported.

Multiline Values

Use quoted strings for multiline content:

PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----"

Escape Sequences

Double-quoted strings support escape sequences:

MESSAGE="Line 1\nLine 2\tTabbed"

Supported: \n, \t, \r, \\, \"

Env File Diff

Compare two .env files to detect drift:

zenv diff .env.development .env.production

Shows:

• Variables only in first file
• Variables only in second file
• Variables with different values
• Compliance check with --schema flag

Documentation Generation

Generate markdown or JSON docs from your schema:

# Markdown (default)
zenv docs > ENVIRONMENT.md

# JSON
zenv docs --format json > env-docs.json

Example Generation

Create .env.example from your schema:

# Basic example
zenv example > .env.example

# Include default values
zenv example --include-defaults > .env.example

Shell Completions

Tab completion for bash, zsh, fish, and PowerShell:

# Bash
zenv completions bash >> ~/.bashrc

# Zsh
zenv completions zsh >> ~/.zshrc

# Fish
zenv completions fish > ~/.config/fish/completions/zenv.fish

# PowerShell
zenv completions powershell >> $PROFILE

CI/CD Integration

Official GitHub Action for pipeline validation:

- name: Validate environment
  uses: zorl-engine/zorath-env/.github/actions/zenv-action@main
  with:
    schema: env.schema.json
    env-file: .env.example

Exit codes: 0 for success, 1 for failure.

Update Checking

Check for new versions:

zenv version --check-update

v0.3.4 now shows changelog and release links when updates are available.

Installation

First-Time Install

Via Cargo (recommended):

cargo install zorath-env

Pre-built binaries:

Download from GitHub Releases:

• Linux: zenv-linux
• macOS Intel: zenv-macos-intel
• macOS Apple Silicon: zenv-macos-arm
• Windows: zenv.exe

Upgrade

cargo install zorath-env --force

Verify

zenv version
# zenv v0.3.4

Full Changelog

v0.3.4 (2026-01-18)

Added:

• Watch mode: zenv check --watch for continuous validation
• Delta detection: only shows changed variables
• Schema change detection: revalidates on schema updates
• Timestamped output with terminal bell on errors
• --format json for diff command
• Smart description inference in zenv init
• Type-aware placeholders in zenv example
• Duplicate key warnings with line numbers
• Validation rules shown in zenv docs output
• Actionable tips for unknown keys
• Changelog and releases links on update available
• 16 new tests (205 total)

Previous Releases

v0.3.3 - Remote schema support via HTTPS URLs with caching

v0.3.2 - Secret detection and zenv diff command

v0.3.1 - Windows support in GitHub Action

v0.3.0 - Shell completions and zenv example command

v0.2.x - Variable interpolation, multiline values, validation rules, schema inheritance

v0.1.x - Initial release with check, docs, and init commands

Resources

• Website: zorl.cloud/zenv
• Documentation: zorl.cloud/zenv/docs
• GitHub: github.com/zorl-engine/zorath-env
• Wiki: GitHub Wiki
• Package: crates.io/crates/zorath-env
• Changelog: CHANGELOG.md
• Community: r/zorath_env

---

Ready for continuous validation? Run cargo install zorath-env and try zenv check --watch in your next development session.