Generate a structured API changelog by diffing schema snapshots. Uses the same data as dino diff but outputs categorized entries in Keep a Changelog format: Added, Changed, Deprecated, Removed, and Breaking — with migration hints.
Usage
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
- Discover — Introspects the live API schema
- Build snapshot — Creates a snapshot of the current schema
- Load previous — Reads the snapshot specified by
--from, or the most recent
- Diff — Compares previous vs. current schema
- Generate changelog — Categorizes changes into Keep a Changelog sections
- 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
dino changelog --tenant acme --env production
# 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
dino changelog --tenant acme --from snap_2024-01-15T10-30-00Z
If the snapshot ID passed to --from does not exist, the command exits with code 1 and prints:
Snapshot not found: <id>
CI gate for breaking changes
dino changelog --tenant acme --env production --fail-on-breaking --format json > changelog.json
- name: Changelog check
run: |
dino changelog --tenant acme --env production --fail-on-breaking
Use --format json to pipe changelog data into release automation tools, Slack notifications, or developer portal updates.
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 |
dino diff — Raw schema diff (same data, different output)dino scan — Full pipeline run (also saves snapshots)dino lint — SDL description coverage audit
