Get-CatInstance
Returns the identity and versions of this CAT installation, the stored license key and the platform it runs on. Works without sign-in.
Synopsis
Get-CatInstance [[-LoggingLevel] <string>] [[-LoggingPath] <string>]
Parameters
| Parameter | Type | Position | Default | Meaning |
|---|---|---|---|---|
-LoggingLevel |
string | 1 | None |
None · Fatal · Error · Warning · Information · Debug · Verbose. |
-LoggingPath |
string | 2 | Documents\CAT\Logs\cat-log.log |
Log file, when logging is on. |
What it does
Reads %APPDATA%\CAT\.catconfig (~/.config/CAT/.catconfig on Linux and macOS) and the runtime, and writes one object describing the installation. It does not sign in and does not need a token or a key — it is the one cmdlet that always works, which makes it the first thing to run when something else does not. If a CAT session already exists it is reused; otherwise a throw-away one is created and disposed.
Set CAT_LICENSE_KEY before the first CAT call of the session — before Open-CatProject — if you use it. The key is read when the session starts, and on Linux and macOS a variable set after that is not seen.
Output
One CatInstanceInfoDTO object:
| Property | Meaning |
|---|---|
InstanceID |
Identity of this installation (a GUID, created on first use). |
InstallationTimestamp |
When the instance was created. |
LicenseKey |
The license key in effect, masked — the first and the last four characters of the key without its CAT3. prefix, the short form the portal shows — or empty when no key is in effect. The whole key is never returned; .catconfig is the only place it can be read. |
LicenseKeySource |
CAT_LICENSE_KEY environment variable when the key comes from that variable, empty otherwise. |
LicenseKeyStatus |
Valid, Expired, Future, NotSet, or — for something that is not a readable CAT key — Incorrect, MalformedKey, UnsupportedVersion, InvalidSignature. |
LicenseKeyPlan |
The plan the key unlocks (Enterprise, Business, …), or empty when CAT could not read the key. |
LicenseKeyValidFrom, LicenseKeyValidTo |
First and last day the key is valid, or empty when CAT could not read the key. |
AutomationPlatform |
The CI/CD platform CAT detected it was started by, or empty for an interactive start — what the interactive-only rule sees. |
AgentHost |
The coding agent CAT detected it was started by (claude-code, copilot-cli, cursor, codex, gemini-cli, …), or empty / None for a plain start. Informational only; it never affects the interactive-only rule. |
AgentHostVersion |
The agent’s version when it reports one, otherwise empty / None. |
CatTool |
PowerShellModule. |
CoreVersion, ToolVersion |
Versions of the CAT engine and of the module. |
Platform, OsVersion |
Windows / Linux and the OS version. |
Expectations, Providers |
The expectations and providers this version knows, as one string each. |
The plan is not on this object — it is decided at sign-in and is visible on Get-CatSession.
Errors
None in normal use.
Examples
Get-CatInstance
Get-CatInstance | Select-Object ToolVersion, CoreVersion, Platform
# is a license key in effect on this machine, and where does it come from?
[bool](Get-CatInstance).LicenseKey
(Get-CatInstance).LicenseKeySource
# what is it worth, and until when?
Get-CatInstance | Select-Object LicenseKey, LicenseKeyStatus, LicenseKeyPlan, LicenseKeyValidTo
Related
- Introduction — session model, logging, errors, sign-in.
Set-CatInstance— set or remove the key.Get-CatSession— plan and sign-in state of the current session.