Install and configure the CLI

Install

The CLI requires Python 3.10 or newer.

python -m pip install "cassis-cli==1.6.0"
cassis version

Pin the version in CI so a dependency update cannot change validation or publishing behavior without a reviewed repository change.

Authenticate

Create an API key from API keys in your Cassis account menu, then store it in your shell or CI secret store as CASSIS_API_KEY. Never commit the key.

read -rsp "Cassis API key: " CASSIS_API_KEY
export CASSIS_API_KEY
cassis projects list

Most commands learn the project ID from cassis/project.yml after the first pull. Until then, pass --project <project-id> or set CASSIS_PROJECT_ID.

What you use it for

Pull: cassis ontology pull puts the current ontology in your checkout.
Format and validate: cassis ontology fmt keeps files canonical; cassis ontology check catches invalid or unsafe changes.
Test: cassis ontology test tries a question against local changes; cassis eval run runs the project’s regression suite.
Publish: cassis ontology upload publishes the full tree. Use it from the default-branch pipeline when the GitHub App is not handling imports.

The modeling guide

cassis ontology pull and cassis ontology fmt generate cassis/AGENTS.md. This is the modeling guide: the instructions people and coding agents follow to structure the ontology consistently and make good modeling decisions.

It matters because valid YAML is not necessarily useful context. The guide explains how to write domains, descriptions, metrics, joins, and provenance so agents can answer business questions reliably. Commit it with the ontology so everyone works from the same rules.

The file is managed by the CLI. Do not edit it by hand; upgrade the pinned CLI and run cassis ontology fmt when you want the current guide.

Commands that validate, test, or publish send the ontology tree to the Cassis API. pull and fmt can change files inside that tree, so review the resulting git diff.

For every flag, output format, and exit code, use the CLI reference.