# Install and configure the CLI

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

## Install

The CLI requires Python 3.10 or newer.

```bash
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.

```bash
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](/reference/cli/).