---
title: Quickstart
description: Install Specdiff and Envlock, run your first check, and see the result in under five minutes.
url: https://pr-1-7abef52380a8.thally.app/quickstart
---

# Quickstart

Install Specdiff and Envlock, run your first check, and see the result in under five minutes.

Both tools require **Node.js 22 or newer** and are **ESM only**.

## Specdiff — detect breaking API changes

#### Install the CLI

    ```bash
    npm install -D @specdiff/cli
    ```

#### Compare two documents

    Pass a before and after JSON Schema or OpenAPI file:

    ```bash
    npx specdiff before.yaml after.yaml
    ```

    Specdiff classifies every change as `breaking`, `warning`, or `info` and
    prints a summary:

    ```text
    Specdiff (OpenAPI): 3 changes: 1 breaking, 1 warning, 1 info

    Breaking changes (1)
      BREAKING endpoint-removed  #/paths/~1owners
               Endpoint /owners was removed.
    ```

#### Check the exit code

    The CLI exits `1` when a change at or above the `--fail-on` threshold
    exists (default: `breaking`). Wire it into CI to gate merges on API
    compatibility.

### Use the library directly

```ts
import { diffOpenApi, formatText } from "@specdiff/core";

const result = diffOpenApi(beforeDocument, afterDocument);
console.log(formatText(result));

if (result.maxSeverity === "breaking") process.exit(1);
```

## Envlock — validate environment contracts

#### Install the core package

    ```bash
    npm install @envlock/core
    ```

    For CLI checks, also install the CLI:

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

#### Define your contract

    Create `envlock.config.mjs` in your project root (or run `npx envlock init`):

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

    export default defineEnv({
      NODE_ENV: env.enum(["development", "test", "production"]).default("development"),
      PORT: env.port().default(3000).describe("HTTP listen port"),
      DATABASE_URL: env.url({ protocols: ["postgres:"] }).secret(),
    });
    ```

#### Validate your environment

    ```bash
    npx envlock check
    ```

    Or validate a dotenv file:

    ```bash
    npx envlock check --env-file .env --strict
    ```

    The CLI lists every issue at once — missing variables, invalid values, and
    (with `--strict`) undeclared keys:

    ```text
    error: 2 issues in .env

    KEY           CODE     MESSAGE
    DATABASE_URL  missing  required variable is not set
    PORT          invalid  expected a port number between 1 and 65535 (received "abc")
    ```

#### Load typed values in your app

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

    const config = loadEnv(schema);
    // config is fully typed: { NODE_ENV: "development" | "test" | "production"; PORT: number; DATABASE_URL: string }
    ```

    `loadEnv` throws `EnvValidationError` listing every problem, or returns
    the typed, validated values.

## Set up MCP servers for coding agents

Both tools ship an MCP server so coding agents (Claude Code, Cursor, and other
MCP clients) can run the same checks.

#### Specdiff MCP

    Add to `.mcp.json` or `claude_desktop_config.json`:

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

#### Envlock MCP

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

## What to explore next

#### [Specdiff rules catalogue](/specdiff-rules)

    45 rules covering JSON Schema and OpenAPI changes, with direction-aware
    severity.

#### [Envlock field types](/envlock-schema-definition)

    10 built-in field builders — string, number, boolean, port, url, enum, json,
    duration, list, and integer — with chain methods for defaults, secrets, and
    documentation.