zorath-env Documentation

From crates.io

cargo install zorath-env

From source

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

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"
  }
}

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 }
  },
  "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, and shell export syntax 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 -e

if [ -f "env.schema.json" ]; then
  if command -v zenv >/dev/null 2>&1; then
    zenv check || exit 1
  else
    echo "Warning: zenv not installed, skipping env validation"
  fi
fi

GitHub Actions

- name: Install zenv
  run: cargo install zorath-env

- name: Validate environment
  run: zenv check --schema env.schema.json

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)