---
title: Specdiff CLI
description: Complete reference for the specdiff command-line tool for detecting breaking changes in JSON Schema and OpenAPI documents.
url: https://pr-1-ff84656b4b8a.thally.app/specdiff/cli
---

# Specdiff CLI

Complete reference for the specdiff command-line tool for detecting breaking changes in JSON Schema and OpenAPI documents.

The `@specdiff/cli` package provides the `specdiff` command for comparing JSON Schema and OpenAPI documents from the terminal or in CI pipelines.

## Installation

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

Or run without installing:

```sh
npx -y @specdiff/cli <before> <after>
```

## Commands

### compare (default)

Compare two documents and report the differences.

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

Both `<before>` and `<after>` are file paths to JSON or YAML documents. This is the default command, so no subcommand keyword is needed.

#### Flags

| Flag | Values | Default | Description |
|---|---|---|---|
| `--format` | `text`, `json`, `markdown` | `text` | Output format for the report |
| `--fail-on` | `breaking`, `warning`, `info`, `none` | `breaking` | Severity threshold for exit code 1 |
| `--ignore-rule` | rule code | -- | Exclude changes from a specific rule. Repeatable. An unknown code causes exit 2 |
| `--ignore-path` | JSON pointer prefix | -- | Exclude changes under a JSON pointer prefix. Repeatable. Leading `#` is optional |
| `--kind` | `auto`, `openapi`, `json-schema` | `auto` | Force the document kind instead of auto-detecting |
| `--direction` | `request`, `response`, `neutral` | `neutral` | Set the comparison direction for JSON Schema diffs. Ignored for OpenAPI documents |
| `--output` / `-o` | file path | -- | Write the report to a file. A confirmation message is printed to stderr |
| `--color` | -- | -- | Force ANSI color output on |
| `--no-color` | -- | -- | Disable ANSI color output |

Flags accept both `--flag value` and `--flag=value` syntax.

### rules

List every built-in rule with its default severity.

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

Pass `--json` to get machine-readable JSON output instead of a human-readable table.

### explain

Describe a single rule in detail, including its remediation guidance.

```sh
specdiff explain <code>
```

For example:

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

### help

Print usage information.

```sh
specdiff --help
specdiff -h
specdiff help
```

### version

Print the version number.

```sh
specdiff --version
specdiff -v
specdiff version
```

## Exit codes

| Code | Constant | Meaning |
|---|---|---|
| 0 | `ok` | No changes at or above the threshold. Also returned by `rules`, `explain`, `--help`, and `--version` |
| 1 | `thresholdExceeded` | At least one change meets or exceeds the `--fail-on` threshold |
| 2 | `usage` | Usage error such as an unknown flag, missing argument, or unknown rule code |
| 3 | `inputError` | An input document could not be read or parsed |

## File format support

The CLI determines parsing strategy from the file extension:

| Extension | Parser |
|---|---|
| `.json` | JSON |
| `.yaml`, `.yml` | YAML |
| Any other extension | Try JSON first, fall back to YAML |

A document that does not parse to an object causes exit code 3.

## Color behavior

ANSI color is enabled only when all three conditions are met:

1. The output format is `text`.
2. stdout is a TTY.
3. The `--no-color` flag is not given.

The `--color` flag forces color on regardless of TTY detection. Color never applies to `json` or `markdown` formats.

## Usage examples

Compare two OpenAPI documents and print a text report:

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

Generate a Markdown report without failing on any severity:

```sh
specdiff examples/petstore-v1.yaml examples/petstore-v2.yaml --format markdown --fail-on none
```

Compare two JSON Schema documents and output JSON:

```sh
specdiff examples/user-v1.json examples/user-v2.json --format json --fail-on none
```

Ignore specific rules and paths:

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

Write the report to a file:

```sh
specdiff before.yaml after.yaml --format markdown -o report.md
```

Look up a rule by code:

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

List all available rules as JSON:

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

## CI usage

Use `--fail-on` to control which severity levels cause a non-zero exit. In a CI pipeline, a non-zero exit fails the step:

```sh
npx -y @specdiff/cli /tmp/openapi-base.yaml openapi.yaml --fail-on breaking --format markdown
```

See the [CI integration guide](/specdiff/ci-integration) for a complete GitHub Actions workflow.