zorath-env Documentation

From crates.io

cargo +stable install zorath-env --locked

From source

git clone https://github.com/zorl-engine/zorath-env.git
cd zorath-env
cargo +stable install --path . --locked

Option A: Start from scratch

Create an env.schema.json file in your project root:

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

Create a matching .env file

DATABASE_URL=postgres://localhost:5432/example
PORT=3000

Use local values for your application and keep real env files out of Git. Defaults do not populate your application process.

Option B: Generate from existing .env.example

If you already have a .env.example file, generate a schema from it:

zenv init

This creates an env.schema.json with intelligent type inference (detects bool, int, float, url). Edit the file to add descriptions and refine types.

Validate your .env

Once you have both .env and env.schema.json, run:

$ zenv check

zenv: OK

Web Application

{
  "NODE_ENV": {
    "type": "enum",
    "values": ["development", "production", "test"],
    "required": true,
    "description": "Application environment"
  },
  "PORT": {
    "type": "int",
    "required": false,
    "default": 3000,
    "description": "HTTP server port",
    "validate": { "min": 1024, "max": 65535 }
  },
  "DATABASE_URL": {
    "type": "url",
    "required": true,
    "description": "PostgreSQL connection string"
  },
  "JWT_SECRET": {
    "type": "string",
    "required": true,
    "description": "Secret key for JWT signing",
    "validate": { "min_length": 32, "max_length": 128 }
  },
  "DEBUG": {
    "type": "bool",
    "required": false,
    "default": false,
    "description": "Enable debug logging"
  }
}

API Service

{
  "API_HOST": {
    "type": "string",
    "required": false,
    "default": "0.0.0.0",
    "description": "Host to bind the API server"
  },
  "API_PORT": {
    "type": "int",
    "required": false,
    "default": 8080,
    "description": "Port for the API server",
    "validate": { "min": 1, "max": 65535 }
  },
  "LOG_LEVEL": {
    "type": "enum",
    "values": ["debug", "info", "warn", "error"],
    "required": false,
    "default": "info",
    "description": "Logging verbosity level"
  },
  "RATE_LIMIT": {
    "type": "float",
    "required": false,
    "default": 100.0,
    "description": "Requests per second limit",
    "validate": { "min_value": 0.0, "max_value": 10000.0 }
  },
  "CORS_ORIGIN": {
    "type": "url",
    "required": false,
    "description": "Allowed CORS origin"
  }
}

Variable Interpolation

Reference other variables using ${VAR} or $VAR syntax:

BASE_URL=https://api.example.com
API_ENDPOINT=${BASE_URL}/v2
PORT=3000
SERVER_URL=http://localhost:${PORT}

Circular references are detected and will cause a validation error.

Multiline Values

Double-quoted strings can span multiple lines:

SSH_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA...
-----END RSA PRIVATE KEY-----"

Escape Sequences

Double-quoted strings support escape sequences:

Comments and Export Syntax

Full-line comments, inline comments, shell export syntax, and blank lines are supported:

# This is a full-line comment
DATABASE_URL=postgres://localhost/db  # inline comment

# Shell export syntax works too
export NODE_ENV=production
export DEBUG=false

.env Fallback Chain

If .env is not found, zenv automatically checks these fallbacks in order:

• .env.local
• .env.development
• .env.development.local

Base Schema (base.schema.json)

{
  "DATABASE_URL": {
    "type": "url",
    "required": true,
    "description": "Database connection string"
  },
  "LOG_LEVEL": {
    "type": "enum",
    "values": ["debug", "info", "warn", "error"],
    "default": "info"
  }
}

Production Schema (prod.schema.json)

{
  "extends": "base.schema.json",
  "SENTRY_DSN": {
    "type": "url",
    "required": true,
    "description": "Sentry error tracking DSN"
  },
  "LOG_LEVEL": {
    "type": "enum",
    "values": ["info", "warn", "error"],
    "default": "warn"
  }
}

The production schema inherits all variables from base.schema.json, adds SENTRY_DSN, and overrides LOG_LEVEL to exclude debug level.

Inheritance supports up to 10 levels of depth. Circular references are detected and will cause an error.

Exit Codes

Pre-commit Hook

Add to .git/hooks/pre-commit or use with pre-commit framework:

#!/usr/bin/env bash
set -euo pipefail
command -v zenv >/dev/null 2>&1 || { echo "Install zenv before committing." >&2; exit 1; }
zenv check --env .env.example --schema env.schema.json --detect-secrets

GitHub Actions

- name: Validate environment
  uses: zorl-engine/zorath-env/.github/actions/[email protected]
  with:
    version: '0.3.13'
    schema: env.schema.json
    env-file: .env.example

Validation Failure Output

When validation fails, zenv provides clear error messages:

$ zenv check
zenv check failed:

- DATABASE_URL: expected url, got 'not-a-url'
- NODE_ENV: expected one of ["development", "staging", "production"], got 'dev'
- API_KEY: missing (required)
- UNKNOWN_VAR: not in schema (unknown key)

Usage

zenv check --detect-secrets

Detected Patterns

zenv scans for the following secret patterns:

Example Output

$ zenv check --detect-secrets

Warning: Potential secrets detected:

- AWS_SECRET_KEY (line 12): AWS Secret Access Key
- DATABASE_URL (line 15): URL contains embedded password
- API_TOKEN (line 22): High-entropy string (possible secret)

These values may be real secrets. Consider using placeholders in committed files.