---
title: Quickstart
description: Install Specdiff and Envlock, run a first comparison and a first environment check, and verify the results.
url: https://pr-1-b9e16090e83d.thally.app/quickstart
---

# Quickstart

Install Specdiff and Envlock, run a first comparison and a first environment check, and verify the results.

This page walks through a minimal example for each Seamline product. You need Node.js 22 or later.

## Specdiff

Detect breaking changes between two versions of a JSON Schema or OpenAPI document.

#### Install the core library

    ```bash
    npm install @specdiff/core
    ```

#### Compare two schemas in code

    Create a file called `compare.mjs` and paste the following:

    ```js
    import { diffDocuments, formatText } from "@specdiff/core";

    const before = {
      type: "object",
      properties: {
        name: { type: "string" },
        age: { type: "integer" },
      },
      required: ["name"],
    };

    const after = {
      type: "object",
      properties: {
        name: { type: "string" },
      },
      required: ["name", "age"],
    };

    const result = diffDocuments(before, after);
    console.log(formatText(result));
    ```

    Run it with `node compare.mjs`. The output lists every change with its severity, rule code, and JSON-pointer path. In this example, `age` was removed as a property and added to `required` -- both breaking changes.

#### Use the CLI instead

    Install the CLI and point it at two files:

    ```bash
    npm install -D @specdiff/cli
    npx specdiff before.yaml after.yaml
    ```

    The command exits with code 0 when no breaking changes are found and code 1 when they are. Add `--format markdown` to produce a report suitable for pull-request comments, or `--format json` for machine-readable output.

#### Verify the result

    A successful run prints a summary line such as `"2 changes: 2 breaking, 0 warning, 0 info"`. If the exit code is 1, at least one change met or exceeded the `--fail-on` threshold (which defaults to `breaking`).

## Envlock

Validate environment variables against a typed contract at startup.

#### Install the core library

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

#### Define a contract and load the environment

    Create `envlock.config.mjs`:

    ```js
    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 it in your application code:

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

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

    `loadEnv` reads from `process.env` by default. If any required variable is missing or fails its type check, it throws an `EnvValidationError` listing every issue at once.

#### Check with the CLI

    Install the CLI and run the check command:

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

    The CLI discovers `envlock.config.mjs` in the current directory, validates `process.env` against it, and prints a table of issues. Exit code 0 means all variables pass; exit code 1 means at least one issue was found.

#### Verify the result

    Set the required variables and run the check again:

    ```bash
    DATABASE_URL=postgres://user:pass@localhost:5432/app npx envlock check
    ```

    The output should confirm that all variables pass. You can also run `npx envlock example` to render a `.env.example` file directly from the contract.