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
ping Tests that one data source, or all of them, answer, without running any test. yes
new Creates a new project from a template, or lists the templates. yes
checks On the Starter plan, shows how many of today’s checks are used and left, without running anything. yes
instance Shows this CAT installation, or sets/removes the license key. no
signin Signs you in to CAT Portal with a code sent to your email, or shows who is signed in. no
signout Removes the sign-in stored by signin and ends it on CAT Portal. 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, ping) 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, ping, instance, signin and signout, 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

CAT CLI is available in every plan. See Compare plans.

Starter and Team sign in to CAT Portal, in one of two ways.

  • With a code from your email (from CAT CLI 3.2.1): catcli signin --email you@example.com mails you a 6-digit code, and catcli signin --email you@example.com --code <the code> finishes the sign-in. A new email gets a CAT Portal account. The sign-in is kept in .catportaltoken for 90 days, until you run catcli signout. See signin.
  • 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 looks for the token at start: CAT_PORTAL_TOKEN first, then the sign-in stored by catcli signin. The first one found is used. When CAT Portal rejects it, the verb is refused with exit code 2 and the message says which one was rejected; CAT does not try the other. Both plans are for interactive runs only: an autonomous run (inside a CI/CD pipeline, a scheduler, an orchestrator or a container) needs the Enterprise plan, and CAT refuses the ones it recognises with exit code 6.

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 any sign-in — with the key in place no token is read, and catcli signin is refused. 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.

A license key that ran out no longer unlocks CAT. When nobody is signed in, CAT says that the stored key expired and names the renewal first: set the renewed key with catcli instance --setLicenseKey, and where renewing is explained. Only then does it name catcli signin as the way to continue on the Starter or Team plan, which changes what CAT may do. See When a plan ends.

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, signin, signout, docs, help and version skip the check: you can always inspect the installation, set a key or sign in, also on a machine whose sign-in is missing or refused.

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 Nobody is signed in, or the token was rejected (invalid, expired or revoked).
3 The plan does not include CAT CLI.
4 The portal is unreachable and no cached authorisation can be used.
5 The plan or version has expired.
6 An autonomous run (CI/CD, scheduler, orchestrator or container) on Starter or Team — it needs Enterprise.
7 A plan limit refused the operation: the project has outputs and the plan is Starter, which writes none (the message lists them and the two ways out), or, on the Starter plan, no checks are left today or CAT can reach neither CAT Portal nor its count of checks on this computer (see Checks per day).
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.
12 ping: at least one tested data source failed its connection test.
13 signin: the 6-digit sign-in code from the email was not accepted (wrong, expired or already used).
14 signin: too many sign-in requests — ten codes were already sent to this email in the last 24 hours, or too many requests came from this address in a short time.

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; 12 applies only to ping — see ping; 13 and 14 apply only to signin — see signin.

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 (Starter and Team plans). Wins over a sign-in stored by catcli signin. 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\.catportaltoken ~/.config/CAT/.catportaltoken The sign-in stored by catcli signin: a personal access token, its expiry and your email. Readable by your user only on Linux and macOS; catcli signout deletes it.
%APPDATA%\CAT\Templates\Projects\ ~/.config/CAT/Templates/Projects/ Project templates downloaded by catcli new --online.
%APPDATA%\CAT\.checks\ ~/.config/CAT/.checks/ Starter plan only: the count of checks CAT uses on this computer while CAT Portal cannot be reached, one file per account.
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 →