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.exe 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 only. 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 (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.

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 — 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 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 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 this means the run finished — not that the tests passed; read the test results from the output or from an output 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 and 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). run --noOutputs skips them.
← CAT Pilot
Installation →