Context commands

Install and configuration (the API key, --base-path, project resolution, exit codes) are in Install and configure the CLI. The cassis context commands need cassis-cli 3.1.0 or newer; scripts that still call cassis ontology keep working.

context 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 context directory
cassis context check

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

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

Context 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 context 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.

context 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 context fmt

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

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

context pull

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

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

# Skip pruning entirely
cassis context 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.

context upload

Replaces a project’s entire context 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.

It runs from a git checkout whose context files are committed, and the version it publishes records that commit. Commit your changes under cassis/ first.

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

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

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

Two places it fits

Bootstrapping, while building a first context before any pull request or merge exists; a local repository with one commit is enough. And publishing from CI on any provider other than GitHub, where this is how a merge goes live.

Committed files only

The context files under the base path must match HEAD. A file that is modified, staged, deleted, or untracked stops the upload with exit 2 before anything is sent, and the CLI lists it. So does a directory that is not a git checkout with a commit, or a machine without git. Line endings do not count, so a file committed with CRLF uploads. Needs cassis-cli 3.0.0 or newer.

Records the commit

The published version carries the commit as its git SHA, so cassis status and get_project_status show whether a checkout matches what is 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 creates no new version, so re-running a CI job on unchanged files is a no-op. The published version still records the upload’s commit. From cassis-cli 3.1.1, the upload prints No change: vN stays published, and now records commit <sha> and cassis status shows that checkout in sync. With --json, the response carries "unchanged": true.

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.

context test

Runs individual questions through the text-to-SQL agent using your local context 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 context 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.