Get Help

Introduction

The conventions shared by every CAT CLI command. Read this page once; the verb pages assume it.

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 tutorial; this section is the reference.

Invocation 

catcli <verb> [options]
Verb What it does Needs sign-in or key
run Runs the tests of a project and prints the results. yes
show Prints what CAT sees in a project — its summary or its test list — without running anything. yes
open Opens a project for an interactive session: run, rerun, step through failed tests. yes
exec Runs one command (typically a SQL query) against a data source of the project and prints the result. yes
new Creates a new project from a template, or lists the templates. yes
instance Shows this CAT installation, or sets/removes the license key. no
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 on Windows, ~/.local/state/CAT/Logs/cat-log.log on Linux and macOS (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. Log lines go to standard output, the same stream as an exec CSV result — leave the level at None (the default) when the output is going to be parsed:

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.

Team signs in to CAT Portal 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: put the license key into the CAT_LICENSE_KEY environment variable, or set it once with catcli instance --setLicenseKey, 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. While CAT_LICENSE_KEY is set it is the key in effect, and a key CAT cannot use refuses the run with exit code 8 instead of falling back to the stored key or to the token. See Get CAT license and 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, every selected test passed (or --exitCode run was given).
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.
8 CAT_LICENSE_KEY is set but holds no key CAT can use — expired, mistyped, or not a key at all.
10 run: at least one selected test did not pass, or none was selected; not produced under --exitCode run.
11 Reserved for a future warnings-only result; not produced today.

Codes 2–8 come from the sign-in and plan check and are the same for every verb that runs it. 10 and 11 apply only to run — see run.

Environment variables

Variable Purpose
CAT_LICENSE_KEY The Enterprise license key. When set it is the key in effect, ahead of the stored one; a key CAT cannot use refuses the run (exit code 8).
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 and Use environment variables.

Files CAT CLI touches

Location (Windows) Location (Linux and macOS) Content
%APPDATA%\CAT\.catconfig ~/.config/CAT/.catconfig Instance identity and the license key (catcli instance reads and writes it).
%APPDATA%\CAT\Templates\Projects\ ~/.config/CAT/Templates/Projects/ Project templates downloaded by catcli new --online.
Documents\CAT\Logs\cat-log.log ~/.local/state/CAT/Logs/cat-log.log Log file, written when logging is not None.
Next to the project file Next to the project file Whatever the project’s Output settings say — Excel, JSON, JUnit, database tables, … (see Outputs). run --noOutputs skips them.
← CAT Pilot
Installation →