---
title: Envlock Overview
description: Declare the environment variables your app needs once, then validate, type-infer, document, diff, and redact them everywhere.
url: https://pr-1-7cfcfe393d12.thally.app/envlock-overview
---

# Envlock Overview

Declare the environment variables your app needs once, then validate, type-infer, document, diff, and redact them everywhere.

Envlock lets you declare the environment variables an application needs once
using a schema DSL, then validate, type-infer, document (`.env.example`), diff,
and redact them everywhere — at startup, in CI, and from coding agents over
MCP.

## Installation

Envlock ships as three packages. Install the ones you need:

```bash
# Core library (runtime dependency)
npm install @envlock/core

# CLI (development / CI dependency)
npm install -D @envlock/cli

# MCP server (for AI-assisted workflows)
npm install -D @envlock/mcp
```

**Requirements:**

- Node.js 22 or later
- ESM only — no CommonJS entry point
- TypeScript declarations included
- MIT license, copyright 2026 Seamline

## Field types

Envlock provides ten built-in field types:

| Type | Description |
| --- | --- |
| `string` | Any string value |
| `number` | Finite number |
| `integer` | Whole number |
| `boolean` | Boolean — accepts `true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off` (case-insensitive) |
| `port` | Integer 1–65535 |
| `url` | Absolute URL, optionally restricted by protocol |
| `enum` | One of a set of literal values |
| `json` | Valid JSON document |
| `duration` | Duration string such as `30s`, `5m`, `2h`; parsed to milliseconds |
| `list` | Comma-separated list of strings (custom separator supported) |

Every field supports the following modifier chain:

| Modifier | Effect |
| --- | --- |
| `.optional()` | Mark the variable as not required |
| `.default(value)` | Provide a fallback value (makes the field required in the output type) |
| `.secret()` | Mask the value in error messages and redacted output |
| `.describe(text)` | Attach a human-readable description |
| `.example(text)` | Provide an example value for `.env.example` rendering |

## Quick usage

```ts
import { defineEnv, env, loadEnv } from "@envlock/core";

const schema = defineEnv({
  PORT: env.port().default(3000),
  DATABASE_URL: env.url({ protocols: ["postgres:"] }).secret(),
  DEBUG: env.boolean().optional(),
});

const config = loadEnv(schema);
// config: { PORT: number; DATABASE_URL: string; DEBUG?: boolean }
```

`loadEnv` reads `process.env` by default and throws an `EnvValidationError` if
any required variable is missing or invalid, so the app fails fast at startup.

## Configuration file

Create an `envlock.config.mjs` (or `envlock.config.js`) file at the project
root. The file must use a default export or a named `schema` export:

```js
// envlock.config.mjs
import { defineEnv, env } from "@envlock/core";

export default defineEnv({
  PORT: env.port().default(3000),
  DATABASE_URL: env.url({ protocols: ["postgres:"] }).secret(),
  DEBUG: env.boolean().optional(),
});
```

The CLI and MCP server load this file via dynamic `import()`.

## CLI

Run the `envlock` binary to validate, generate `.env.example` files, diff, or
inspect your schema from the command line or CI:

```bash
npx envlock check --env-file .env
npx envlock example --out .env.example
npx envlock diff --env-file .env
npx envlock inspect
```

See the [@envlock/cli reference](/envlock-cli) for the full command and flag
list.

## MCP server

Connect `@envlock/mcp` to any MCP-compatible coding agent so it can validate
environment variables, inspect schemas, and explain issues interactively:

```json
{
  "mcpServers": {
    "envlock": {
      "command": "npx",
      "args": ["-y", "@envlock/mcp"]
    }
  }
}
```

See the [@envlock/mcp server reference](/envlock-mcp-server) for available
tools and the resource template.

## What to read next

- [@envlock/core API](/envlock-core-api) — every public export, type, and
  function
- [@envlock/cli reference](/envlock-cli) — commands, flags, exit codes, and
  programmatic API
- [@envlock/mcp server](/envlock-mcp-server) — MCP tools, resource template,
  and programmatic API