> ## 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 changelog

> Generate a Keep a Changelog-formatted API changelog from schema snapshots

Generate a structured API changelog by diffing schema snapshots. Uses the same data as `dino diff` but outputs categorized entries in [Keep a Changelog](https://keepachangelog.com/) format: Added, Changed, Deprecated, Removed, and Breaking -- with migration hints.

## Usage

```bash theme={null}
dino changelog --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 present            |
| `--from`             | `string`               | Latest snapshot   | Snapshot ID to compare against (instead of the most recent) |

## 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 snapshot specified by `--from`, or the most recent
4. **Diff** -- Compares previous vs. current schema
5. **Generate changelog** -- Categorizes changes into Keep a Changelog sections
6. **Save** -- Writes the current snapshot as the new baseline

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

## Examples

### Generate a changelog

```bash theme={null}
dino changelog --tenant acme --env production
```

```text theme={null}
# API Changelog — acme / production

## Breaking
  - Removed field `User.legacyId`
    Migration: Use `User.id` instead

## Added
  - Query `searchUsers` — full-text search across user fields
  - Field `User.avatarUrl`

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

## Deprecated
  - Query `getUsers` — use `searchUsers` instead
```

### Compare against a specific snapshot

```bash theme={null}
dino changelog --tenant acme --from snap_2024-01-15T10-30-00Z
```

Compares the current schema against the named snapshot instead of the most recent one. Useful for generating changelogs across multiple releases.

<Warning>
  If the snapshot ID passed to `--from` does not exist, the command exits with code 1 and prints:
  `Snapshot not found: <id>`
</Warning>

### CI gate for breaking changes

```bash theme={null}
dino changelog --tenant acme --env production --fail-on-breaking --format json > changelog.json
```

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

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

<Tip>
  Use `--format json` to pipe changelog data into release automation tools, Slack notifications, or developer portal updates.
</Tip>

## Changelog Categories

| Category       | Counts as Breaking? | Description                                          |
| -------------- | ------------------- | ---------------------------------------------------- |
| **Breaking**   | Yes                 | Removed fields/operations, incompatible type changes |
| **Added**      | No                  | New operations, fields, or types                     |
| **Changed**    | No                  | Modified signatures, updated types                   |
| **Deprecated** | No                  | Operations or fields marked as deprecated            |
| **Removed**    | Yes                 | Operations or fields that were deleted               |

## Exit Codes

| Code | Meaning                                                                                            |
| ---- | -------------------------------------------------------------------------------------------------- |
| `0`  | Changelog generated, first run (baseline saved), or no breaking changes                            |
| `1`  | Breaking changes detected with `--fail-on-breaking`, `--from` snapshot not found, or command error |

## Related

* [`dino diff`](/cli/diff) -- Raw schema diff (same data, different output)
* [`dino scan`](/cli/scan) -- Full pipeline run (also saves snapshots)
* [`dino lint`](/cli/lint) -- SDL description coverage audit