Schema commands

schema pull

Downloads the project’s full source schema, as last introspected from the warehouse or uploaded as DDL, into cassis/.schema.json.

# In a checkout with cassis/project.yml, the project id is read from it
cassis schema pull

# Or name the project and checkout explicitly
cassis schema pull /path/to/checkout --project 019f0000-0000-7000-8000-000000000000

This is the bulk counterpart to the MCP server’s get_source_schema tool: instead of paging through 20 tables per call, an agent on a modeling pass greps one local file.

Observed state, not truth: The snapshot is stamped with pulled_at. The warehouse stays authoritative and the file is a local cache. Re-run to refresh.
Never committed: The command maintains a .gitignore entry for it in the ontology directory.
Exit codes: 0 on success, 2 on a usage error including a checkout it cannot write to, 3 on a transport or API error.

schema push

Uploads a DDL file to detect source-schema changes on a DDL-only project, the same effect as the web app’s “Update from DDL” button. Cassis diffs the DDL against the ontology, and added, dropped, and changed objects appear in the Data source review queue for approval. Read that queue from the terminal with cassis source-changes list.

A DDL file speaks only for the schemas it contains. A partial export — Snowflake’s per-schema GET_DDL, one schema out of many — adds and updates the schemas it covers and leaves the others as they were, instead of marking every table in them as removed. Pass --complete when the file is the project’s complete source schema, so schemas absent from it are treated as dropped. That was the behavior of every upload before, and it now takes --complete to get.

This scoping lives in Cassis, not in the CLI, so it applies to every upload from every client whatever its version, including older CLIs that cannot pass the flag. If a pipeline of yours relied on leaving a schema out of the file to signal that it was dropped, upgrade to cassis-cli 1.6.0 or newer and pass --complete, or those drops stop being detected.

# Upload and wait for the detection run to complete
cassis schema push schema.sql --project ...

# The file is the whole source schema: schemas missing from it were dropped
cassis schema push schema.sql --project ... --complete

# Machine-readable output
cassis schema push schema.sql --project ... --json

Scope of the file: Without --complete, only the schemas present in the file are compared, and the stored schema keeps carrying the rest. With --complete, a schema the file does not mention is a dropped schema.
DDL-only projects: Connected projects sync their schema from the warehouse directly, so this command does not apply to them.
Waiting: The command always waits for the detection run and exits 0 only when the run completed — the DDL parsed and the schema was applied. --poll-interval (5 seconds) and --timeout (10 minutes) control the polling; the run keeps going server-side if the CLI hits the timeout (exit 3).
What success prints: The number of changes the run queued for review, or that there were none.
Suspected partial export: When the file drops most of the tracked tables in a schema it does cover, Cassis flags it and the command prints a note. Removals of modeled tables wait for review rather than applying, so re-pushing a complete export undoes an unintended drop.
Parse errors: A DDL statement the parser cannot read fails the run: exit 1 with the parser’s message. Nothing is applied.
Conflict: Exit 1 when the project will not take the push: a detection run is already in flight, or the project is warehouse-connected rather than DDL-only. Wait for the run to finish or cancel it in the web app; a connected project refreshes with a warehouse sync instead.
Superseding: Re-uploading a corrected DDL supersedes the previous one.

Neither command changes the ontology. schema pull writes a local snapshot; schema push queues changes for a human to approve. Modeling a newly appeared table is still an edit in the repository or the app.