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

# dino diff

> Detect breaking and non-breaking schema changes between snapshots

Compare your current API schema against the last saved snapshot. Reports added, removed, modified, and breaking changes. Use `--fail-on-breaking` to gate CI pipelines.

## Usage

```bash theme={null}
dino diff --tenant <id> [flags]
```

## Flags

| Flag                 | Type                   | Default           | Description                                       |
| -------------------- | ---------------------- | ----------------- | ------------------------------------------------- |
| `--tenant`           | `string`               | —                 | **Required.** Tenant ID (or set in `.dino.yml`)   |
| `--env`              | `string`               | Tenant default    | Target environment                                |
| `--format`           | `"markdown" \| "json"` | `"markdown"`      | Output format                                     |
| `--quiet`            | `boolean`              | `false`           | Suppress stdout output                            |
| `--snapshot-dir`     | `string`               | `.dino/snapshots` | Directory for reading and writing snapshots       |
| `--fail-on-breaking` | `boolean`              | `false`           | Exit with code 1 if breaking changes are detected |

## How It Works

1. **Discover** -- Introspects the live API schema
2. **Build snapshot** -- Creates a snapshot of the current schema
3. **Load previous** -- Reads the most recent snapshot from disk
4. **Diff** -- Compares previous vs. current and categorizes changes
5. **Save** -- Writes the current snapshot as the new baseline

On the **first run** (no previous snapshot exists), the current schema is saved as the baseline. No diff is produced.

```text theme={null}
First snapshot saved.
```

## Examples

### Check for schema changes

```bash theme={null}
dino diff --tenant acme --env staging
```

```text theme={null}
# Schema Diff — acme / staging

## Summary
  Added: 3 | Removed: 1 | Modified: 2 | Breaking: 1

## Breaking Changes
  - Removed field `User.legacyId`

## Added
  - Field `User.avatarUrl`
  - Field `User.preferences`
  - Query `searchUsers`

## Modified
  - Field `User.email` — type changed (String → String!)
```

### CI gate for breaking changes

```bash theme={null}
dino diff --tenant acme --env production --fail-on-breaking
```

Returns exit code `1` if any breaking changes are detected. Use this in CI to block deployments that introduce breaking API changes.

<CodeGroup>
  ```yaml GitHub Actions theme={null}
  - name: Schema compatibility check
    run: dino diff --tenant acme --env production --fail-on-breaking
  ```

  ```yaml GitLab CI theme={null}
  schema-check:
    script:
      - dino diff --tenant acme --env production --fail-on-breaking
  ```
</CodeGroup>

### JSON output for tooling

```bash theme={null}
dino diff --tenant acme --format json > diff.json
```

<Tip>
  Commit your `.dino/snapshots` directory to version control so that `dino diff` always has a baseline to compare against, even in fresh CI environments.
</Tip>

## Exit Codes

| Code | Meaning                                                               |
| ---- | --------------------------------------------------------------------- |
| `0`  | No breaking changes (or `--fail-on-breaking` not set)                 |
| `1`  | Breaking changes detected with `--fail-on-breaking`, or command error |

## Related

* [`dino scan`](/cli/scan) -- Full pipeline run (also saves snapshots)
* [`dino changelog`](/cli/changelog) -- Changelog from the same diff data
* [`dino lint`](/cli/lint) -- Audit SDL description coverage