> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pikopod.com/llms.txt
> Use this file to discover all available pages before exploring further.

# pikopod spec-diff

> Diff two API spec versions. Declared drift, severity derived by law.

```text theme={null}
pikopod spec-diff <old> <new> [flags]
```

Sources: a local file, an `http(s)` URL, or `git:<ref>:<path>`, read via `git show` with no checkout. Both sides are normalized first, so OpenAPI 3.x, Swagger 2.0 and Postman collections all diff, even against each other. A spec split across files works when the source is a file or a git ref. Remote and absolute `$ref`s are always refused. Needs no config file.

| Flag               | Default | Meaning                                                                     |
| ------------------ | ------- | --------------------------------------------------------------------------- |
| `--fail-on`        | `ERR`   | Exit 1 when findings at or above this level exist: `ERR`, `WARN` or `INFO`. |
| `--format`         | `text`  | `text`, `json`, `markdown` or `githubactions`.                              |
| `--handoff <path>` |         | Also write the JSON report here, for `pikopod pr comment`.                  |

## Exit codes

| Exit | When                                                                                                             |
| ---- | ---------------------------------------------------------------------------------------------------------------- |
| `0`  | Nothing at or above `--fail-on`.                                                                                 |
| `1`  | Something at or above `--fail-on` exists.                                                                        |
| `2`  | A document could not be loaded or normalized. Never `1`: a spec that fails to load is a tool problem, not drift. |

## Example

```bash theme={null}
pikopod spec-diff git:origin/main:openapi.yaml openapi.yaml --fail-on ERR
```

```text theme={null}
1 change(s): 1 ERR, 0 WARN, 0 INFO

ERR  GET    /charges/{id}                            endpoint-removed
     endpoint removed from the spec  [fp_bcc85ba9a094]

breaking declared drift at/above ERR — failing the gate (exit 1)
```

See [Spec diff](/gate/spec-diff), [Severity](/gate/severity), [Multi-file specs](/gate/multi-file-specs) and [CI integration](/gate/ci-integration).