---
title: Envlock Overview
description: Declare environment variable contracts once, then validate, type, document, and diff them everywhere
url: https://pr-1-8289d63b6330.thally.app/envlock/overview
---

# Envlock Overview

Declare environment variable contracts once, then validate, type, document, and diff them everywhere

Envlock is a typed environment contracts library for Node.js. It lets you declare what environment variables your application needs once, then validate, type, document, and diff them everywhere—in your code, CLI, or AI agents via MCP.

## What It Solves

Managing environment variables across development, testing, and production is error-prone:
- Developers don't know which variables are required or what format they should have
- Type information is lost—everything is a string until you parse it
- Documentation drifts from code
- CI can't validate `.env` files before deployment
- Secrets risk being logged or committed to version control

Envlock fixes all of these by treating environment contracts as first-class data. You declare your schema once, and Envlock handles validation, typing, documentation, and security.

## Three Packages

Envlock is split into three focused packages:

| Package | npm name | Purpose |
|---|---|---|
| **Core** | `@envlock/core` | Schema builders, validation, typing via `Infer`, dotenv parsing, example generation, diffing, redaction |
| **CLI** | `@envlock/cli` | `envlock` command for local checks and CI; config file loading |
| **MCP** | `@envlock/mcp` | `envlock-mcp` stdio MCP server for Claude and other AI agents |

## Installation

Install the core library for runtime validation:

```sh
npm install @envlock/core
```

Install the CLI as a dev dependency for local checks and CI pipelines:

```sh
npm install -D @envlock/cli
```

Optionally install the MCP server for AI agent integration:

```sh
npm install -D @envlock/mcp
```

## Requirements

- **Node.js**: >=22
- **Module format**: ESM only
- **License**: MIT
- **Part of**: Seamline toolkit

## Key Features

### 10 Field Types

Envlock provides ready-built validators for the most common environment variable patterns:

- **`string`** — any value
- **`number`** — finite numbers
- **`integer`** — whole numbers only
- **`boolean`** — true/false, 1/0, yes/no, on/off (case-insensitive)
- **`port`** — integers 1–65535
- **`url`** — absolute URLs with optional protocol constraints
- **`enum`** — fixed set of literal values
- **`json`** — parsed JSON documents
- **`duration`** — time durations like `30s`, `5m`, `2h` (stored as milliseconds)
- **`list`** — comma-separated strings (trimmed, empties dropped)

### Immutable Chainable Builders

Fields are immutable; chain methods return new frozen fields:

```ts
env.port()
  .default(3000)
  .describe("HTTP listen port")
  .secret()
```

### Typed Output via `Infer`

The `Infer` type maps your schema to a fully typed values object. Required and defaulted fields become required properties; `.optional()` fields become optional:

```ts
type Config = Infer<typeof schema>;
// Config.PORT is number (required, has default)
// Config.DEBUG is boolean | undefined (optional)
```

### Dotenv Parsing

Parse `.env` files without external dependencies. Supports comments, quotes, multi-line values, escape sequences, and inline comments:

```ts
const env = parseDotenv(fileContents);
```

### `.env.example` Generation

Generate example files automatically from your schema. Secrets show as `KEY=` with no value; documented fields include type, constraints, and default:

```ts
const example = renderExample(schema);
```

### Schema Diffing

Compare a `.env` file against your contract and get structured results:

```ts
const diff = diffEnv(schema, process.env);
// { ok: boolean, missing: string[], unknown: string[], invalid: EnvIssue[] }
```

### Secret Redaction

Automatically redact secret fields before logging or passing data to external services:

```ts
const safe = redact(config, schema);
// DATABASE_URL is now "••••••"
```

## Quick Start

Define your schema once in a config file:

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

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

Then load and use it in your code:

```ts
import { loadEnv } from "@envlock/core";
import schema from "./envlock.config.mjs";

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

Use the CLI to validate:

```sh
envlock check
envlock example --out .env.example
envlock inspect
```

Or integrate with AI agents:

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

## Explore Further

- [**Core API Reference**](./core-api) — Full API for `@envlock/core`
- [**Field Types**](./field-types) — All 10 builders with examples
- [**Configuration**](./configuration) — Config file setup and best practices
- [**CLI Reference**](./cli) — All commands and flags
- [**MCP Server**](./mcp) — Using Envlock with AI agents