---
title: "Introduction"
description: "How CAT CLI is invoked: verbs, options, project resolution, logging, sign-in and plans, exit codes, environment variables and files."
url: "https://docs.justcat.it/reference/cat-cli/introduction/"
---
# Introduction


CAT CLI is the command-line tool of CAT: a single self-contained `catcli` executable with no dependency on PowerShell or on a separately installed .NET runtime. It works with the same project file (`.cat.yaml`) and runs tests with the same engine as CAT Studio, the PowerShell module and the Python module — which tool you use is a matter of environment and taste, not of capability. It runs on Windows, Linux and macOS. For a hands-on first contact, follow the [Get started with CAT CLI](https://docs.justcat.it/get-started/cat-cli/ "Get started with CAT CLI") tutorial; this section is the reference.

## Invocation

```
catcli <verb> [options]
```

| Verb | What it does | Needs sign-in or key |
|------|--------------|----------------------|
| [`run`](https://docs.justcat.it/reference/cat-cli/run/ "run") | Runs the tests of a project and prints the results. | yes |
| [`show`](https://docs.justcat.it/reference/cat-cli/show/ "show") | Prints what CAT sees in a project — its summary or its test list — without running anything. | yes |
| [`open`](https://docs.justcat.it/reference/cat-cli/open/ "open") | Opens a project for an interactive session: run, rerun, step through failed tests. | yes |
| [`exec`](https://docs.justcat.it/reference/cat-cli/exec/ "exec") | Runs one command (typically a SQL query) against a data source of the project and prints the result. | yes |
| [`new`](https://docs.justcat.it/reference/cat-cli/new/ "new") | Creates a new project from a template, or lists the templates. | yes |
| [`instance`](https://docs.justcat.it/reference/cat-cli/instance/ "instance") | Shows this CAT installation, or sets/removes the license key. | no |
| [`docs`](https://docs.justcat.it/reference/cat-cli/docs/ "docs") | Opens this documentation in the default browser. | no |
| `help` | `catcli help` lists the verbs; `catcli help <verb>` (or `catcli <verb> --help`) lists the options of one verb. | no |
| `version` | `catcli version` or `catcli --version` prints the installed version. | no |

A verb must come first. An unknown verb, an unknown option or a missing required option prints the relevant help and exits with code 1.

## Options

Every option has a long name (`--project`) and most have a one-letter short name (`-p`). The value follows after a space or, for the long form, after `=`; quote a value that contains spaces:

```
catcli show --tests --project "D:\Testing\Aero.cat.yaml"
catcli show -t -p "D:\Testing\Aero.cat.yaml"
catcli show -t --project="D:\Testing\Aero.cat.yaml"
```

Switches (options without a value, such as `--summary` or `--progress`) are on when present. Several short switches can be grouped into one token, optionally ending with one option that takes a value:

```
catcli show --summary --progress --project "D:\Testing\Aero.cat.yaml"
catcli show -sgp "D:\Testing\Aero.cat.yaml"
```

Option names are case-sensitive: `--loggingLevel` and `-p` work, `--logginglevel` and `-P` do not. Option *values* (logging levels, template codes, tags, filters) are not case-sensitive. Options can be given in any order, before or after each other; there are no positional arguments — a bare path after the verb is ignored.

## Which project file

Verbs that work with a project (`run`, `show`, `open`, `exec`) find it through `--project` / `-p`, which accepts either a path to a `.cat.yaml` file or a path to a directory; a relative path is resolved against the current directory. Without `--project`, the current directory is used. A directory must contain **exactly one** `*.cat.yaml` file — none or more than one is an error that names the files found. The usual way of working is therefore to `cd` into the project's folder and call the verbs bare:

```
cd "D:\DWH\Testing\Metadata"
catcli show --summary
catcli run
```

Relative paths *inside* the project file (test lists, outputs, CSV files, …) are resolved against the project file's folder, not against the directory `catcli` was started from.

## Logging

`--loggingLevel` / `-l` sets how much CAT logs while it works. Levels, from silent to most talkative: `None`, `Fatal`, `Error`, `Warning`, `Information`, `Debug`, `Verbose`. The default is `None` for `run`, `show`, `open`, `exec` and `instance`, and `Error` for `new`. Any other value is rejected with a message that lists the valid levels.

With any level other than `None`, log lines go to the console and to `Documents\CAT\Logs\cat-log.log` (the same file for every run). `Information` shows what CAT is doing step by step — which project it opened, how many data sources and tests it loaded from where, each test as it finishes. It is the first thing to turn on when a project does not behave as expected:

```
catcli run -l Information
catcli show -s -l Debug
```

`--progress` / `-g` replaces the log with live progress bars for loading the project and is honoured only when logging is `None`; with logging on, `-g` has no effect.

## Output streams

Results — test lines, summaries, tables — go to standard output. Refusals from the sign-in and plan check (below) and the "working offline" notice go to standard error. `--quiet` / `-q` suppresses only the "working offline" notice; refusals are never suppressed.

## Sign-in, plans and the license key

The command-line tools are available in the **Team** and **Enterprise** plans; **Starter** and **Professional** cover CAT Studio only — `catcli` refuses to work under them (exit code 3). See [Compare plans](https://docs.justcat.it/compare-plans/ "Compare plans").

**Team** signs in to [CAT Portal](https://portal.justcat.it) with a personal access token. Create one in the portal under **Developer → Personal access tokens** and put it into the `CAT_PORTAL_TOKEN` environment variable; every verb that needs sign-in reads it at start. The Team plan is for interactive use only: when CAT detects that it was started by a CI/CD platform (GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, TeamCity and others, through their environment variables) or by a scheduler (Windows Task Scheduler, SQL Server Agent, cron, launchd — through the parent process), it refuses with exit code 6. Nothing detected means allowed.

Once signed in, CAT caches the authorisation and keeps working without the portal for a limited time; during that time it prints `Working offline; authorised until <date>. Reconnect before then.` to standard error (`-q` hides it). When the portal is unreachable and no usable cache exists, it refuses with exit code 4.

**Enterprise** needs no sign-in and no network at all: set the license key once with [`catcli instance --setLicenseKey`](https://docs.justcat.it/reference/cat-cli/instance/ "instance") and every verb is unlocked, also behind a firewall. A valid Enterprise key takes precedence over `CAT_PORTAL_TOKEN` — with the key in place the token is not read. See [Get CAT license](https://docs.justcat.it/how-to-guides/licensing-and-admin/get-license/ "Get CAT license") and [Apply a license key](https://docs.justcat.it/how-to-guides/licensing-and-admin/apply-license-key/ "Apply a license key").

The check runs before any verb work, so a refused run does nothing — no project is opened, no test runs, no output is written. `instance`, `docs`, `help` and `version` skip the check: you can always inspect the installation or set a key on a machine that has no portal access.

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | The verb completed. **For `run` this means the run finished — not that the tests passed;** read the test results from the output or from an [output](https://docs.justcat.it/reference/outputs/ "Outputs") of the project. |
| `1` | Unknown verb, unknown or missing option, or an error while working (the project file does not parse, a test list or data-source list cannot be loaded, a directory does not exist, …). The message is printed. |
| `2` | No usable `CAT_PORTAL_TOKEN` — the variable is not set, or the token is invalid or expired. |
| `3` | The plan does not include CAT CLI (Starter, Professional). |
| `4` | The portal is unreachable and no cached authorisation can be used. |
| `5` | The plan or version has expired. |
| `6` | Interactive-only plan (Team) started by a CI/CD platform or a scheduler. |
| `7` | The project exceeds a per-project limit of the plan (number of tests, data sources or technologies); the message states the count, the cap and the ways out. |

Codes 2–7 come from the sign-in and plan check and are the same for every verb that runs it.

## Environment variables

| Variable | Purpose |
|----------|---------|
| `CAT_PORTAL_TOKEN` | Personal access token used to sign in (Team plan). Not read when a valid Enterprise key is set. |

Project files can reference environment variables of their own (connection strings, paths, passwords) — see [Environment variables](https://docs.justcat.it/reference/project-file/environment-variables/ "Environment variables in project files") and [Use environment variables](https://docs.justcat.it/how-to-guides/organize-and-run-tests/use-environment-variables/ "Use environment variables").

## Files CAT CLI touches

| Location | Content |
|----------|---------|
| `%APPDATA%\CAT\.catconfig` | Instance identity and the license key (`catcli instance` reads and writes it). |
| `%APPDATA%\CAT\Templates\Projects\` | Project templates downloaded by `catcli new --online`. |
| `Documents\CAT\Logs\cat-log.log` | Log file, written when logging is not `None`. |
| Next to the project file | Whatever the project's `Output` settings say — Excel, JSON, JUnit, database tables, … (see [Outputs](https://docs.justcat.it/reference/outputs/ "Outputs")). `run --noOutputs` skips them. |

## Related

- [Installation](https://docs.justcat.it/reference/cat-cli/installation/ "Install CAT CLI") — WinGet and the installer on Windows, the archive on Linux, Homebrew on macOS; update and uninstall.
- [Get started with CAT CLI](https://docs.justcat.it/get-started/cat-cli/ "Get started with CAT CLI") — the tutorial.
- [Run your tests](https://docs.justcat.it/how-to-guides/organize-and-run-tests/run-your-tests/ "Run your tests") and [SQL Server Agent](https://docs.justcat.it/how-to-guides/pipelines-and-schedulers/sql-agent-cat-cli/ "Use CAT CLI in SQL Server Agent") — how-to guides.
- [Project file](https://docs.justcat.it/reference/project-file/ "Project file") — what the verbs operate on.