Skip to content
Raw Markdown

Install and configure the CLI

The CLI is the bridge between a repository checkout and Cassis. Use it to pull context files, keep them consistent, test changes, and publish from CI.

Install

The CLI requires Python 3.10 or newer.

python -m pip install "cassis-cli~=3.1"
cassis version

~=3.1 takes every 3.x release from 3.1 on, but never 4.0: a change that breaks validation or publishing comes with a new major version, so it reaches CI only through a reviewed repository change. To review every upgrade, pin an exact version instead, such as cassis-cli==3.1.0.

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. For a pipeline, scope the key to the one project it works on.

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 context pull puts the current context in your checkout.
Format and validate
cassis context fmt keeps files canonical; cassis context check catches invalid or unsafe changes.
Test
cassis context test tries a question against local changes; cassis eval run runs the project’s regression suite.
Publish
cassis context upload publishes the full tree. Use it from the default-branch pipeline when the GitHub App is not handling imports. From cassis-cli 3.0.0 it runs only from a git checkout with the context files committed, and the published version records that commit.

The modeling guide

cassis context pull and cassis context fmt generate cassis/AGENTS.md. This is the context design guide: the instructions people and coding agents follow to structure the context 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 context files 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 context fmt when you want the current guide.

Commands that validate, test, or publish send the context 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.