# Source-change commands

Read the Data source review queue from a checkout: what drifted in the source, what it breaks in the ontology, and what the suggested fix would be.

These commands read the same queue as the **Data source** feed under **Review** in the web app, described in [Review data-source changes](/curate/data-source-changes/), and as the [MCP source-change tools](/reference/mcp/source-changes/): the schema drift Cassis detected between your source and what the ontology tracks. They need cassis-cli 1.6.0 or newer. Like the other project-bound commands, the project id comes from `cassis/project.yml` in the checkout, `CASSIS_PROJECT_ID`, or `--project`, and `--path` points at a checkout other than the current directory.

**Reading only, on purpose.** Approving or dismissing a change stays in the web app, because approving edits the ontology and dismissing mutes the table. Headlessly, you act on a change the way you make any other ontology change: edit the files and open a pull request. What these commands add is the reading — so an agent working in a checkout can see that a breaking `column_removed` is pending on the very table it is about to touch.

## source-changes list

Lists the queue newest first, one line per change: id, type, severity, status, and target. The target is `schema.table` for a table change and `schema.table.column` for a column change. The id is what `source-changes show` takes.

```bash
# What is waiting for review
cassis source-changes list

# Another bucket
cassis source-changes list --status approved

# Page through a long queue
cassis source-changes list --limit 20 --offset 20

# Raw JSON
cassis source-changes list --json
```

- **Status** `--status` takes `pending`, `approved`, `rejected` (what dismissing in the app records), or `superseded` (a later detection found the change no longer holds, for instance after a corrected DDL upload). Omit it for the pending queue, which is the one you normally want. An unknown value is a usage error, exit 2.

- **Paging** `--limit` (100 by default, 500 maximum) and `--offset`. When more changes match than the page shows, the last line names the `--offset` for the next page. A queue can hold thousands of rows after a large schema refresh, so expect to page.

- **Types** `table_added`, `table_removed`, `table_renamed`, `column_added`, `column_removed`, `column_renamed`, `column_retyped`.

- **Severity** `breaking` means a curated ontology object — a join, metric, virtual table, or grain — references the changed source object, so something in the ontology is already wrong. `benign` means nothing references it yet. Spend your attention here rather than on queue order.

- **Machine-readable output** `--json` prints the page as `{items, total}`, so a script can size the queue without paging it. Feed rows carry the suggested edit’s summary line and its manual-review notes, not the full edit: that comes from `show`.

- **Exit codes** 0 on success, including an empty queue. 2 on a usage error, 3 on a transport or API error.

## source-changes show

Shows one change in full: its target, how many times detection has raised it and when it was last seen, the ontology objects it affects, and the edit Cassis suggests.

```bash
cassis source-changes show 019f0000-0000-7000-8000-0000000000a1

# The full record, suggested-edit operations included
cassis source-changes show 019f0000-0000-7000-8000-0000000000a1 --json
```

- **Impact** One line per referencing object: its kind (join, metric, virtual table, grain), the confidence, and the object itself. Confidence is `exact` for a structured match, `heuristic` for an unqualified column resolved through its home table, and `unverified` when the object’s SQL did not parse but the name appears in it as an identifier. Treat `unverified` as a lead to check, not a fact.

- **Suggested edit** A one-line summary of what approving in the app would do: the rename to apply, the type to correct. It is a description of the fix, not the fix — make the equivalent change in the ontology files. Anything the suggestion cannot decide for you is printed under `Manual review`.

- **Exit codes** 0 on success. 1 when the project has no change with that id, which is a real answer rather than a transport failure. 2 on a usage error, 3 on a transport or API error.

The headless loop from a checkout: `cassis status` tells you something is pending, `source-changes list` shows what and how bad, `source-changes show` gives you the impact and the suggested edit, then you edit the ontology files, prove the change with [`cassis verify`](/reference/cli/projects/), and open the pull request. A DDL-only project refreshes the source with [`cassis schema push`](/reference/cli/schema/), which is what fills this queue in the first place.