---
title: CLI Reference
description: Command-line reference for Specdiff, the breaking-change detection tool for JSON Schema and OpenAPI.
url: https://pr-1-8289d63b6330.thally.app/specdiff/cli
---

# CLI Reference

Command-line reference for Specdiff, the breaking-change detection tool for JSON Schema and OpenAPI.

Specdiff provides a command-line interface for comparing documents in CI/CD pipelines, pre-commit hooks, and local development workflows.

## Installation

Install as a dev dependency:

```sh
npm install -D @specdiff/cli
npx specdiff --help
```

Or run without installation:

```sh
npx -y @specdiff/cli --help
```

## Commands

### Compare documents

```
specdiff <before> <after> [options]
```

Compares two JSON or YAML documents and reports changes. Automatically detects document kind (JSON Schema or OpenAPI) unless you specify `--kind`.

**Arguments:**
- `<before>` — path to the original document (`.json`, `.yaml`, `.yml`)
- `<after>` — path to the new document

### List rules

```
specdiff rules [--json]
```

Prints all available rules and their default severity. Add `--json` for machine-readable output.

### Explain a rule

```
specdiff explain <code>
```

Shows the description and remediation steps for one rule (e.g., `specdiff explain required-parameter-added`).

### Help and version

```
specdiff --help
specdiff --version
```

## Flags (compare command)

| Flag | Values | Default | Description |
| --- | --- | --- | --- |
| `--format` | `text`, `json`, `markdown` | `text` | Output format |
| `--fail-on` | `breaking`, `warning`, `info`, `none` | `breaking` | Exit 1 if change at/above this severity is found |
| `--ignore-rule` | rule code; repeatable | — | Suppress changes from this rule |
| `--ignore-path` | JSON pointer; repeatable | — | Suppress changes at/beneath this path |
| `--kind` | `auto`, `openapi`, `json-schema` | `auto` | Force document kind (auto-detects by default) |
| `--direction` | `request`, `response`, `neutral` | `neutral` | Direction for JSON Schema diffs; ignored for OpenAPI |
| `--output` / `-o` | file path | stdout | Write report to a file |
| `--color` | — | auto-detect | Force ANSI color on |
| `--no-color` | — | auto-detect | Disable ANSI color |

Flags accept both `--flag value` and `--flag=value` syntax. Repeatable flags can be used multiple times:

```sh
specdiff before.json after.json \
  --ignore-rule description-changed \
  --ignore-rule deprecated-added \
  --ignore-path '#/paths/~1internal'
```

## Exit codes

| Code | Constant | Meaning |
| --- | --- | --- |
| 0 | `ok` | No changes at/above threshold; or help/version/rules/explain command succeeded |
| 1 | `thresholdExceeded` | Changes found at/above `--fail-on` threshold |
| 2 | `usage` | Usage error: unknown flag, missing argument, or invalid rule code |
| 3 | `inputError` | Input document could not be read or parsed |

## Usage examples

### Basic comparison

Compare two OpenAPI files and show text output:

```sh
npx specdiff examples/petstore-v1.yaml examples/petstore-v2.yaml
```

### Markdown output for CI/CD

Generate a Markdown report and append to GitHub Actions summary:

```sh
npx specdiff openapi-main.yaml openapi.yaml \
  --format markdown \
  >> "$GITHUB_STEP_SUMMARY"
```

### Fail on warnings

Exit with code 1 if any warning or breaking change is detected:

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

### Ignore specific rules and paths

Compare while ignoring documentation changes and internal endpoints:

```sh
npx specdiff old.json new.json \
  --ignore-rule description-changed \
  --ignore-path '#/paths/~1internal'
```

### Direction-aware schema comparison

Compare JSON Schema as a response (outgoing) document:

```sh
npx specdiff event-v1.json event-v2.json --direction response
```

### JSON output for tooling

Get structured output for parsing or processing:

```sh
npx specdiff before.json after.json --format json --fail-on none
```

### List and explain rules

View all available rules:

```sh
npx specdiff rules
npx specdiff rules --json
```

Explain a specific rule:

```sh
npx specdiff explain required-parameter-added
```

## Programmatic embedding

You can embed the CLI in a Node.js script using the `runCli` function:

```ts
import { runCli, type CliIo } from "@specdiff/cli";

const io: CliIo = {
  stdout: (text) => process.stdout.write(text),
  stderr: (text) => process.stderr.write(text),
  cwd: process.cwd(),
  isTty: process.stdout.isTTY === true,
};

const exitCode = await runCli(
  ["before.yaml", "after.yaml", "--format", "json"],
  io
);

process.exitCode = exitCode;
```

The `runCli` function returns an exit code (0, 1, 2, or 3) and never calls `process.exit()`, allowing you to integrate Specdiff into custom tooling.

### Additional programmatic exports

`@specdiff/cli` also exports these for advanced use:

- `parseArgs(argv: readonly string[]): ParsedCommand` — parse CLI arguments into a command object. Throws an `Error` with `name: "UsageError"` on malformed input.
- `EXIT_CODES` — `{ ok: 0, thresholdExceeded: 1, usage: 2, inputError: 3 } as const`
- `HELP_TEXT` — the full help text string
- `loadDocument(filePath: string, cwd: string): Promise<unknown>` — read and parse a JSON or YAML file. Throws `DocumentLoadError` on failure.
- `parseDocumentText(text: string, fileName: string): unknown` — parse text using the file extension as a format hint (`.json` → JSON, `.yaml`/`.yml` → YAML, otherwise JSON-first then YAML).
- `createDocumentLoadError(filePath: string, message: string): DocumentLoadError` — create a `DocumentLoadError` instance.
- `isDocumentLoadError(error: unknown): error is DocumentLoadError` — type guard for `DocumentLoadError`.

**Types:** `ParsedCommand`, `CompareCommand`, `OutputFormat`, `KindOption`, `CliIo`, `DocumentLoadError`.