envschema-dsl 0.1.1

DSL for typed .env files — schema, validation, codegen

envschema

DSL for typed .env files — schema, validation, codegen.

Install

pip install envschema-dsl
# or
uv add envschema-dsl

Quick Start

Create a .env.schema file:

# Database
DB_HOST str @required
DB_PORT port = 5432
DB_PASSWORD str @secret @required
DB_NAME str = "myapp"

# App
NODE_ENV enum("development", "production", "test") = "development"
PORT int = 3000 : 0 < x < 65535
DEBUG bool = false
CORS_ORIGIN str[] = "http://localhost:3000"
API_KEY str @required : len(x) >= 32

Validate your .env file:

envschema validate .env.schema --env .env

  ✓ DB_HOST = db.example.com
  ✓ DB_PORT = 5432
  ✓ DB_PASSWORD = ***
  ✓ NODE_ENV = development
  ✓ PORT = 3000
  ✗ API_KEY — validation failed: len(x) >= 32 (x='short')
  ⚠ UNKNOWN_VAR — not defined in schema

Result: 5 OK, 1 errors, 1 warnings

Generate code:

envschema generate .env.schema -t ts          # TypeScript interface
envschema generate .env.schema -t zod         # Zod v4 schema
envschema generate .env.schema -t pydantic    # Pydantic BaseSettings
envschema generate .env.schema -t dataclasses # Python dataclass (no deps)
envschema generate .env.schema -t env-example # .env.example

Features

Types

HOST str = "localhost"            # string
PORT int = 3000                   # integer
RATIO float = 0.5                 # float
DEBUG bool = false                # boolean
API_PORT port = 8080              # port (int 1-65535)
BASE_URL url                      # URL (any scheme://)
ADMIN_EMAIL email                 # email
DATA_DIR path = "/var/data"       # filesystem path
NODE_ENV enum("dev", "prod")      # enum
HOSTS str[]                       # array (comma-separated)

Type inference from defaults — PORT = 3000 is inferred as int.

Decorators

DB_HOST str @required                      # must be set
DB_PASSWORD str @secret @required          # hidden in output
LOG_LEVEL str @description("Logging level") # description

Inline Validation

Python expressions with x as the value:

PORT int = 3000 : 0 < x < 65535
API_KEY str @required : len(x) >= 32
RATE_LIMIT int = 100 : 0 < x < 10000

Block Syntax

For complex variables:

DATABASE_URL {
    type = url
    description = "PostgreSQL connection string"
    @secret
    @required
    validate = "x.startswith('postgres://')"
}

Type Aliases

type LogLevel = enum("error", "warn", "info", "debug")
type ExtendedEnv = NodeEnv + enum("local")

LOG_LEVEL LogLevel = "warn"

Presets

#include <node.js>       # built-in preset (NODE_ENV, PORT, HOST)
#include <vite>          # VITE_* variables
#include "shared.schema" # local file

APP_NAME str = "myapp"

envschema presets list             # list available presets
envschema presets load directus    # download from registry

Wildcard Expansion

AUTH_PROVIDERS str[] = "google,github"

AUTH_{AUTH_PROVIDERS}_DRIVER str @required
AUTH_{AUTH_PROVIDERS}_CLIENT_ID str @secret @required
AUTH_{AUTH_PROVIDERS}_CLIENT_SECRET str @secret @required

Expands to AUTH_GOOGLE_DRIVER, AUTH_GITHUB_DRIVER, etc. Default filter: upper. Custom: {AUTH_PROVIDERS|lower}.

CLI

envschema parse <file>              # parse and display AST
envschema parse <file> --json       # output as JSON
envschema validate <schema> --env <env>  # validate .env against schema
envschema generate <schema> -t <target>  # generate code
envschema generators list           # list available targets
envschema presets list              # list presets
envschema presets load <name>       # download preset
envschema lsp                       # start LSP server (stdio)

VS Code Extension

cd editors/vscode/envschema
npx @vscode/vsce package --allow-missing-repository
cursor --install-extension envschema-0.1.0.vsix

Provides syntax highlighting for .env.schema files.

License

MIT