---
title: Quickstart
description: Install Specdiff and Envlock, run your first comparison and validation, and verify the results.
url: https://pr-1-7cfcfe393d12.thally.app/quickstart
---

# Quickstart

Install Specdiff and Envlock, run your first comparison and validation, and verify the results.

## Before you begin

- **Node.js 22 or later** is required by both tools.
- A terminal with `npm` (or another Node.js package manager).

---

## Specdiff — detect breaking API changes

#### Install the CLI

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

#### Compare two documents

    Pass a before and after OpenAPI or JSON Schema file. Specdiff auto-detects
    the document kind.

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

    The default output is a human-readable text report. Every change shows a
    severity (`breaking`, `warning`, or `info`), a JSON-pointer path, and a
    stable rule code.

#### Verify the result

    The exit code tells you whether the threshold was exceeded:

    | Exit code | Meaning |
    |-----------|---------|
    | 0 | No change at or above the threshold |
    | 1 | Threshold exceeded |

    The default threshold is `breaking`. Override it with `--fail-on`:

    ```bash
    npx specdiff before.yaml after.yaml --fail-on warning
    ```

### Use as a library

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

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

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

---

## Envlock — enforce environment contracts

#### Install the packages

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

#### Create a schema

    Create `envlock.config.mjs` at the project root:

    ```js
    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(),
    });
    ```

#### Validate your environment

    Run the `check` command against a `.env` file or `process.env`:

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

    A passing check prints `ok` and exits 0. A failing check lists every issue
    with the variable name, issue code, and a human-readable message.

#### Load in your app

    Replace scattered `process.env` reads with a single validated call:

    ```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 }
    ```

    `loadEnv` throws an `EnvValidationError` if any required variable is missing
    or invalid, so the app fails fast at startup instead of at runtime.

## What to read next

- [Specdiff overview](/specdiff-overview) — installation options, output formats, and CI integration
- [Envlock overview](/envlock-overview) — field types, schema options, and the `.env.example` workflow