---
title: "Introduction"
description: "How the CAT PowerShell module is used: import, the session model, paths, logging, objects on the pipeline, errors, sign-in and plans, environment variables and files."
url: "https://docs.justcat.it/reference/powershell-module/introduction/"
---
# Introduction


The CAT PowerShell module is the PowerShell face of CAT: 19 cmdlets that open a project file (`.cat.yaml`), run its tests, hand the results back as objects, and manage the installation. It works with the same project file and runs tests with the same engine as CAT Studio, CAT CLI and the Python module — which tool you use is a matter of environment and taste, not of capability. It requires PowerShell 7.6 or later and runs on Windows and on the Linux distributions where PowerShell 7 is supported. For a hands-on first contact, follow the [Get started with the PowerShell module](https://docs.justcat.it/get-started/powershell-module/ "Get started with the PowerShell module") tutorial; this section is the reference.

## Install and import

```powershell
Install-Module CAT -AcceptLicense -AllowClobber   # once, from the PowerShell Gallery
Import-Module CAT                                  # in every session, before the first cmdlet
```

`Import-Module CAT` is not optional. PowerShell's automatic module loading finds a cmdlet by name in the installed manifests, and the CAT manifest lists the names *without* the `Cat` prefix that the cmdlets actually carry — so `Get-CatInstance` is not found until the module is imported. Importing prints a banner with the documentation and feedback links and the module version; nothing else happens at import (no sign-in, no network). Installation options, pinning a version, upgrade and uninstall are on [Installation](https://docs.justcat.it/reference/powershell-module/installation/ "Installation").

## Cmdlets

Every cmdlet is `<Verb>-Cat<Noun>`; there are no aliases. By task:

| Task | Cmdlets |
|------|---------|
| Run tests in one go | [`Invoke-CatProject`](https://docs.justcat.it/reference/powershell-module/invoke-catproject/ "Invoke-CatProject") |
| Open a project and work with it | [`Open-CatProject`](https://docs.justcat.it/reference/powershell-module/open-catproject/ "Open-CatProject") · [`Invoke-CatTest`](https://docs.justcat.it/reference/powershell-module/invoke-cattest/ "Invoke-CatTest") · [`Close-CatProject`](https://docs.justcat.it/reference/powershell-module/close-catproject/ "Close-CatProject") |
| Inspect the open project | [`Get-CatProject`](https://docs.justcat.it/reference/powershell-module/get-catproject/ "Get-CatProject") · [`Show-CatProject`](https://docs.justcat.it/reference/powershell-module/show-catproject/ "Show-CatProject") · [`Get-CatDataSource`](https://docs.justcat.it/reference/powershell-module/get-catdatasource/ "Get-CatDataSource") · [`Get-CatDataSourceList`](https://docs.justcat.it/reference/powershell-module/get-catdatasourcelist/ "Get-CatDataSourceList") · [`Get-CatTest`](https://docs.justcat.it/reference/powershell-module/get-cattest/ "Get-CatTest") · [`Get-CatTestList`](https://docs.justcat.it/reference/powershell-module/get-cattestlist/ "Get-CatTestList") |
| Read the results of the last run | [`Get-CatTestResultSummary`](https://docs.justcat.it/reference/powershell-module/get-cattestresultsummary/ "Get-CatTestResultSummary") · [`Get-CatTestResult`](https://docs.justcat.it/reference/powershell-module/get-cattestresult/ "Get-CatTestResult") · [`Show-CatTestResultSummary`](https://docs.justcat.it/reference/powershell-module/show-cattestresultsummary/ "Show-CatTestResultSummary") |
| Query a data source directly | [`Invoke-CatCommand`](https://docs.justcat.it/reference/powershell-module/invoke-catcommand/ "Invoke-CatCommand") |
| Create a project | [`New-CatProject`](https://docs.justcat.it/reference/powershell-module/new-catproject/ "New-CatProject") · [`Get-CatProjectTemplate`](https://docs.justcat.it/reference/powershell-module/get-catprojecttemplate/ "Get-CatProjectTemplate") |
| The installation and the session | [`Get-CatInstance`](https://docs.justcat.it/reference/powershell-module/get-catinstance/ "Get-CatInstance") · [`Set-CatInstance`](https://docs.justcat.it/reference/powershell-module/set-catinstance/ "Set-CatInstance") · [`Get-CatSession`](https://docs.justcat.it/reference/powershell-module/get-catsession/ "Get-CatSession") |

`Get-Command -Module CAT` lists them; `Get-Help <cmdlet>` shows the syntax (the module ships no help texts beyond the syntax, so the pages here are the help). No cmdlet supports `-WhatIf`/`-Confirm` or pipeline input; the common parameters (`-Verbose`, `-ErrorAction`, `-WarningAction`, …) apply to all.

## The session model

The module keeps one **session** and at most one **open project** per PowerShell session, in private module state you never touch directly.

- `Open-CatProject` (and `Invoke-CatProject`, which opens internally) creates the session, signs in, opens the project and remembers it. Opening another project replaces the first; nothing has to be closed in between.
- Every cmdlet that works with "the project" — `Get-Cat*`, `Show-CatProject`, `Invoke-CatTest`, `Invoke-CatCommand` — uses that one open project and fails with `There is no CAT project open. Use Open-CatProject to open it.` (or `There is no CAT session active…`) when there is none.
- `Invoke-CatProject` is the one-liner: open → show → run → show summary. After it, the project stays open and `Get-CatTestResultSummary` / `Get-CatTestResult` still read its results.
- `Close-CatProject` forgets the project and ends the session. It is never required — ending the PowerShell session does the same — but it releases data-source connections.
- `New-CatProject` and `Get-CatProjectTemplate` need no open project; they sign in on their own (and reuse the session if one exists). `Get-CatInstance` and `Set-CatInstance` neither open nor sign in.

## Paths

`-Path` on `Open-CatProject`, `Invoke-CatProject` and `New-CatProject` accepts a path to a `.cat.yaml` file or to a directory; a relative path is resolved against PowerShell's current location (`Get-Location`), and an empty or omitted `-Path` means the current location. A directory must contain **exactly one** `*.cat.yaml` file — none or more than one is an error naming the files found. A path that does not exist is refused before anything else happens.

Relative paths *inside* the project file (test lists, outputs, CSV files, …) are resolved against the project file's folder.

## Logging

`-LoggingLevel` on the cmdlets that create the session sets how much CAT logs: `None`, `Fatal`, `Error`, `Warning`, `Information`, `Debug`, `Verbose`. The level lives with the session, so it is fixed by the cmdlet that created it and inherited by everything that follows until the next `Open-CatProject` / `Invoke-CatProject`.

| Cmdlet | Default `-LoggingLevel` | Default log file |
|--------|-------------------------|------------------|
| `Invoke-CatProject` | `Information` | `<project folder>\Logs\cat-log.log` |
| `Open-CatProject` | `None` | `<project folder>\Logs\cat-log.log` |
| `Get-CatInstance`, `Set-CatInstance` | `None` | `Documents\CAT\Logs\cat-log.log` |
| `New-CatProject` | none (the parameter exists but is ignored — the session is created at `Information`) | `Documents\CAT\Logs\cat-log.log` |
| `Get-CatProjectTemplate` | `Error` | `Documents\CAT\Logs\cat-log.log` |

With any level other than `None`, log lines go to the console and to the log file; the file rolls hourly (`cat-log<yyyyMMddHH>.log`). `-LoggingPath` redirects the file. `Information` shows what CAT does step by step and prints one line per test as it finishes (`✅  Passed  [Suite].[0].[Name]`, `❌  Failed …`, `❓  Inconclusive …`, `🔥 Error …`); with `None`, `Fatal`, `Error` or `Warning` the per-test lines are not printed.

On Linux, `Documents` resolves to nothing, so the non-project log file lands in `./CAT/Logs/` under the current directory.

## Objects on the pipeline, text on the host

`Get-*` cmdlets, `Open-CatProject`, `Invoke-CatTest` and `Invoke-CatCommand` write **objects** to the pipeline (the cmdlet pages list their properties). `Show-*` cmdlets, `Invoke-CatProject`, `New-CatProject`, `Close-CatProject` and `Set-CatInstance` write **nothing** to the pipeline — what you see is host text (coloured, not capturable).

One PowerShell detail matters: the `Get-*` cmdlets that return several items write the whole list as **one object**. `Get-CatTest | Where-Object …` therefore sees a single list, not its items. Assign first, or wrap in parentheses:

```powershell
$tests = Get-CatTest
$tests | Where-Object Suite -eq 'Departures'
(Get-CatTest) | Measure-Object
(Get-CatTest).Count
```

## Errors

A refusal from the sign-in and plan check, a plan limit, a bad parameter value or a missing project is a **terminating error** of the cmdlet: the cmdlet stops, `$?` is `$false`, the error is in `$Error[0]`, `try/catch` catches it, and `-ErrorAction SilentlyContinue` does *not* hide it. The next statement of the script still runs unless `$ErrorActionPreference = 'Stop'` is set or the call is in `try`. No cmdlet sets `$LASTEXITCODE`.

Scripts can branch on the stable `FullyQualifiedErrorId`:

| `FullyQualifiedErrorId` (prefix) | Meaning |
|---------------------------------|---------|
| `CatPortal.TokenMissing` | `CAT_PORTAL_TOKEN` is not set. |
| `CatPortal.TokenInvalid` | The token was rejected by the portal. |
| `CatPortal.PlanNotAllowed` | The plan does not include the PowerShell module (Starter, Professional). |
| `CatPortal.OfflineExpired` | The portal is unreachable and no cached authorisation can be used. |
| `CatPortal.VersionExpired` | The plan or version has expired. |
| `CatPortal.InteractiveUsageRequired` | Interactive-only plan (Team) started by a CI/CD platform or a scheduler. |
| `PlanLimitExceeded` | The project exceeds a per-project limit of the plan. |
| `LicenseKeyNotSet` | `Set-CatInstance` refused the key. |

The full id is `<prefix>,<cmdlet class>`, for example `CatPortal.TokenMissing,JC.Cat.Clients.PowerShell.CatModule.OpenProjectCommand`. A project that fails to open for any other reason (a YAML error, an unreachable data source list, …) is a **non-terminating** error from `Open-CatProject`/`Invoke-CatProject` — the message is printed and no project is open afterwards.

**Failed tests are not errors.** `Invoke-CatProject` and `Invoke-CatTest` complete normally whatever the results. A script that must fail on failed tests reads the summary:

```powershell
Invoke-CatProject -Path "D:\Testing\DwhTests.cat.yaml"
$summary = Get-CatTestResultSummary
if ($summary.FailedCount -gt 0 -or $summary.ErrorCount -gt 0) { exit 1 }
```

## 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 — the module refuses to work under them (`CatPortal.PlanNotAllowed`). 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 under **Developer → Personal access tokens** and put it into the `CAT_PORTAL_TOKEN` environment variable (`$env:CAT_PORTAL_TOKEN = '…'` for the session, `setx` on Windows or your profile for good). Every `Open-CatProject` / `Invoke-CatProject` signs in afresh; the other project cmdlets reuse that session. 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; on Linux also a container runtime), it refuses with `CatPortal.InteractiveUsageRequired`. Nothing detected means allowed.

Once signed in, CAT caches the authorisation and keeps working without the portal for a limited time; during that time the cmdlet writes the warning `Working offline; authorised until <date>. Reconnect before then.` (`-WarningAction SilentlyContinue` hides it). When the portal is unreachable and no usable cache exists, it refuses with `CatPortal.OfflineExpired`.

**Enterprise** needs no sign-in and no network at all: set the license key once with [`Set-CatInstance -LicenseKey`](https://docs.justcat.it/reference/powershell-module/set-catinstance/ "Set-CatInstance") and every cmdlet is unlocked, also behind a firewall; with a valid key in place `CAT_PORTAL_TOKEN` is not read. The key is shared with the other CAT tools on the machine. 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 work, so a refused cmdlet does nothing — no project is opened, no test runs, no output is written. `Get-CatInstance` and `Set-CatInstance` skip it: you can always inspect the installation or set a key on a machine that has no portal access.

## 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 the module touches

| Windows | Linux | Content |
|---------|-------|---------|
| `%APPDATA%\CAT\.catconfig` | `~/.config/CAT/.catconfig` | Instance identity and the license key (`Get-/Set-CatInstance`). |
| `%APPDATA%\CAT\Templates\Projects\` | `~/.config/CAT/Templates/Projects/` | Project templates, including those downloaded with `-Online`. |
| `<project folder>\Logs\` · `Documents\CAT\Logs\` | `<project folder>/Logs/` · `./CAT/Logs/` | Log files, written when logging is not `None`. |
| Next to the project file | | Whatever the project's `Output` settings say (see [Outputs](https://docs.justcat.it/reference/outputs/ "Outputs")); `-SkipOutputs` skips them. |

## Platforms

One package serves Windows (x64) and Linux. Windows PowerShell 5.1 is not supported — the module needs PowerShell 7.6+. On Linux everything above applies with the Linux paths; the providers built on Windows components — `Dax@1`, `Dax@2`, `PowerBI@1`, `PowerBI@2`, `CsvOleDB@1`, `ExcelOleDB@1` — are Windows-only, and file names are case-sensitive (a `*.cat.yaml` project file must be spelled with that case). See [CAT on Linux](https://docs.justcat.it/how-to-guides/licensing-and-admin/cat-on-linux/ "CAT on Linux").

## Related

- [Installation](https://docs.justcat.it/reference/powershell-module/installation/ "Installation") — Gallery, scopes, pinning, upgrade, uninstall.
- [Get started with the PowerShell module](https://docs.justcat.it/get-started/powershell-module/ "Get started with the PowerShell module") — the tutorial.
- [Run your tests](https://docs.justcat.it/how-to-guides/organize-and-run-tests/run-your-tests/ "Run your tests") · [Integrations](https://docs.justcat.it/reference/integrations/ "Integrations") — pipelines that call the module.
- [Project file](https://docs.justcat.it/reference/project-file/ "Project file") — what the cmdlets operate on.