get_instance
Returns the identity and versions of this CAT installation, the stored license key and the platform it runs on. Works without sign-in.
Signature
cat.get_instance()
Parameters
None.
What it does
Loads the engine if needed, reads %APPDATA%\CAT\.catconfig (~/.config/CAT/.catconfig on Linux and macOS) and the runtime, and returns one object describing the installation. It does not sign in and needs neither a token nor a key — it is the one function that always works, which makes it the first thing to run when something else does not (and the way to verify an installation).
If you use CAT_LICENSE_KEY, it has to be in the environment the process starts with, before the first justcatit call — not set through os.environ later. The key is read when the session starts, and on Linux and macOS .NET does not see os.environ changes made after it has started.
Returns
A 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 None 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, None 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 None when CAT could not read the key. |
LicenseKeyValidFrom, LicenseKeyValidTo |
First and last day the key is valid, or None when CAT could not read the key. |
AutomationPlatform |
The CI/CD platform CAT detected it was started by, or None 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 |
Python. |
CoreVersion, ToolVersion |
Versions of the CAT engine and of the package. |
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, which this function does not do.
Raises
RuntimeError: Failed to create a .NET runtime (coreclr)… when the package’s bundled runtime could not be loaded and no installed .NET was found either (a source checkout, or a wheel built without the runtime).
Examples
from justcatit import cat
i = cat.get_instance()
print(i) # the whole object, one line
print(i.ToolVersion, i.CoreVersion, i.Platform)
print(bool(i.LicenseKey)) # is a key in effect on this machine?
print(i.LicenseKeySource) # and does it come from the environment variable?
print(i.LicenseKey, i.LicenseKeyStatus, i.LicenseKeyPlan, i.LicenseKeyValidTo)
Related
- Introduction — session model, logging, .NET objects, exceptions, sign-in.
set_instance— set or remove the key.- Installation.