Ontology commands

Install and configuration (the API key, --base-path, project resolution, exit codes) are in Install and configure the CLI.

ontology check

Validates the files with the exact same three stages as the cassis / ontology validation check Cassis posts on pull requests: every YAML file must parse, no file may lose data in a canonical round-trip, and the tree must pass the validation the post-merge import runs. A clean run means a green check and a clean import.

# From the root of a checkout containing the ontology directory
cassis ontology check

# Or point at the checkout explicitly
cassis ontology check /path/to/checkout

This is the pass/fail gate. It also prints two advisory layers the pull-request check does not run.

Ontology quality warnings

For any tree that parses: tables not assigned to a domain, joins or metrics pointing at unknown tables or columns, missing table and column descriptions. The same findings ontology test reports, computed without an agent run. Validation answers “would this import cleanly”; these answer “is the result any good to query”.

Schema reference warnings

In a checkout bound to a project, every table and column the tree references, including join equi-pairs, is cross-checked against the project’s last-introspected source schema. An unbound checkout falls back to the tree-only checks and says so.

Neither changes the exit code

A referenced object may legitimately not be built or synced yet, so warnings are never failures.

Success prints the file count. Failures print one finding per line as cassis/<path>: <message> (<stage>), reporting every problem in one run rather than stopping at the first. Round-trip failures name the unknown fields that would be dropped. The reference stage always states whether it ran, so silence can never be read as verification.

ontology fmt

Rewrites the files in canonical form, the way black or gofmt rewrites code, using the exact serializer the validation round-trip compares against. A formatted tree cannot fail that stage. It also writes the modeling guide to cassis/AGENTS.md.

# Rewrite the files in place
cassis ontology fmt

# CI mode: exit 1 if any file is not canonical, write nothing
cassis ontology fmt --check

Formatting does not run import validation. check remains the gate for semantic problems like dangling references and incomplete metrics.

ontology pull

Downloads the project’s current ontology into your checkout. Use it to add the ontology files to a repository, including one Cassis does not sync itself.

cassis ontology pull --project 019f0000-0000-7000-8000-000000000000

# Skip pruning entirely
cassis ontology pull --project ... --no-prune

It is a full sync, so local files the project no longer has are pruned, but only when git can restore them, meaning tracked and unmodified. Anything untracked or locally modified is kept and listed with the reason it was spared, and every path it does delete is printed first. Outside a git repository nothing is pruned at all. --json reports what survived under kept. Review the result with git diff. Pull also writes cassis/AGENTS.md and cassis/project.yml, which is what binds the checkout to the project afterwards.

ontology upload

Replaces a project’s entire ontology with your local tree and, by default, publishes it immediately as a new version. It runs the same validation as check first, so a failing tree is rejected with the reason and the project is untouched.

# Replace and publish
cassis ontology upload --project 019f0000-0000-7000-8000-000000000000

# Replace the unpublished ontology only, to review in Cassis
cassis ontology upload --project ... --no-publish

# Label the published version
cassis ontology upload --project ... --label "release 1.2"

Two places it fits

Bootstrapping, while building a first ontology without a repository, a pull request, or a merge. And publishing from CI on any provider other than GitHub, where this is how a merge goes live.

First upload always goes live

A never-published project publishes on its first upload even with --no-publish, matching how imports from the app behave.

Publishing is idempotent

Re-uploading content identical to the published version reports that version instead of creating a new one, so re-running a CI job on unchanged files is a no-op.

Not against a GitHub-synced project

When Cassis syncs the repository itself, it stays the source of truth and the next import replaces whatever you uploaded. Do not point both at one project.

ontology test

Runs individual questions through the text-to-SQL agent using your local ontology files, so you can confirm a change works: that a new column gets picked, that a metric routes correctly. Where eval run tells you nothing regressed, test tells you the thing you just built does what you meant.

cassis ontology test --project ... \
  -q "How much was refunded last month?" \
  -q "Net revenue in Q1?"

One full agent run per question, so expect roughly 30 to 90 seconds each. Repeat -q for several. Nothing is persisted. Probes are informational: the command exits 0 when every probe completed, whatever the outcome, so do not gate CI on them.