---
title: Envlock Overview
description: Typed environment-variable contracts for Node.js: declare, validate, type, document, and diff env vars from a single schema.
url: https://pr-1-b9e16090e83d.thally.app/envlock/overview
---

# Envlock Overview

Typed environment-variable contracts for Node.js: declare, validate, type, document, and diff env vars from a single schema.

Envlock is a typed environment-contract system for Node.js. You declare the
environment variables your application needs once with `defineEnv` and a set of
type-safe builders, then validate, type, document, and diff them everywhere --
at startup, in CI, and from coding agents over MCP.

A single `defineEnv` schema drives every projection: runtime parsing,
`.env.example` rendering, diff reports, schema descriptions, and secret
redaction. `loadEnv` returns a fully typed object, and
`Infer<typeof schema>` gives you the static type without running any code.

## Packages

Envlock ships as three packages in a monorepo, all at version 0.1.0.

### `@envlock/core`

The runtime library. Schema builders, parser and validator, a dependency-free
dotenv reader and writer, and projection functions (`renderExample`, `diffEnv`,
`redact`, `describeSchema`). Zero runtime dependencies.

### `@envlock/cli`

A command-line interface that reads your contract and runs five subcommands:
`check`, `example`, `diff`, `inspect`, and `init`. Depends only on
`@envlock/core`.

### `@envlock/mcp`

A Model Context Protocol server that exposes Envlock contract checks to coding
agents over stdio. Provides five tools (`envlock_check`, `envlock_inspect`,
`envlock_render_example`, `envlock_diff`, `envlock_explain_issue`) and a
resource template.

## Installation

```sh
npm install @envlock/core          # runtime validation
npm install -D @envlock/cli        # CLI for local checks and CI
npm install -D @envlock/mcp        # MCP server (optional)
```

To configure the MCP server for Claude Desktop, Claude Code, or Cursor, add the
following to your MCP configuration file:

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

If `@envlock/mcp` is already installed locally, you can use
`"args": ["envlock-mcp"]` instead to skip the download step.

## Requirements

- **Node.js 22 or later**
- **ESM only** -- all three packages use `"type": "module"`

## Basic usage

Define a schema with `defineEnv` and the `env` builders, then call `loadEnv` to
validate and parse environment variables at startup:

```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 from `process.env` by default. When every declared variable
passes validation, it returns a typed object. When any variable is missing or
invalid, it throws an `EnvValidationError` listing every issue at once.

## Next steps

- [Field Types](/envlock/field-types) -- all ten builder functions and their chain methods
- [Validation](/envlock/validation) -- how `parseEnv` and `loadEnv` collect and report issues
- [CLI](/envlock/cli) -- the `envlock` command and its subcommands
- [MCP Server](/envlock/mcp) -- tools and resources for coding agents
- [Configuration](/envlock/configuration) -- config file discovery and validation semantics