Get Help

Apply a license key

The license key is how the Enterprise plan unlocks CAT: set once on a machine, every CAT tool on it runs without signing in, offline, and unattended. Here is how to set it in each tool, what it is not, and where it lives.

What the key is — and is not

The license key belongs to the Enterprise plan (and its trial). It came by email — from the trial request, or from us after the license agreement — and looks like 42800B3FH804525-0C-1P93C2B09E-10-7114C17B6E (not a real one). Treat it as a secret: it is the thing that unlocks CAT.

It is not any of these, which you may also hold:

Used for Where
License key unlocking Enterprise — no sign-in, offline, unattended set once per machine and account, this page
Portal account (sign-in) Starter, Professional, Team CAT Studio’s sign-in, or CAT_PORTAL_TOKEN on the command line
Personal access token signing in on the command line with the account the CAT_PORTAL_TOKEN environment variable, Team plan
Paddle subscription / receipt paying for Professional or Team your account page; nothing to enter into CAT

A Team or Professional customer never has a key; an Enterprise customer never needs the token.

Set the key

The Settings page → License Key: paste the key, press Set Key. Studio signs you out of the portal account if you were signed in — the key is the identity now — and shows Enterprise as the plan.

catcli instance --setLicenseKey "42800B3FH804525-0C-1P93C2B09E-10-7114C17B6E"

catcli instance afterwards shows the plan and the key’s validity — see instance.

Set-CatInstance -LicenseKey '42800B3FH804525-0C-1P93C2B09E-10-7114C17B6E'
Get-CatInstance          # shows the plan and the key

See Set-CatInstance.

import justcatit as cat
cat.set_instance("42800B3FH804525-0C-1P93C2B09E-10-7114C17B6E")
print(cat.get_instance())

See set_instance.

The key is checked before it is stored; a genuine key is stored even when it is not yet valid or already expired — what it unlocks is decided every time CAT runs, so a renewal key can be set ahead of time. A mistyped key is refused with the reason.

From an environment variable

Every CAT tool also reads the key from the CAT_LICENSE_KEY environment variable. Nothing is stored: set the variable, and CAT is unlocked for as long as it is set.

The variable wins over the stored key, completely. While it is set, .catconfig is not consulted at all, and there is no falling back:

  • a variable holding a key CAT cannot use — expired, mistyped, or something that is not a key — stops the run before any test executes, with a message naming the variable. CAT CLI exits with code 8. It does not quietly use the stored key or sign in instead, because the variable is an instruction to use that key;
  • an empty variable counts as not set, so the stored key applies as usual;
  • every tool says where the key came from: catcli instance adds (from the CAT_LICENSE_KEY environment variable) to the License Key row, Get-CatInstance and get_instance() return a LicenseKeySource property, and CAT Studio’s Settings page shows a line under the key. Nothing changes for anyone who never sets the variable;
  • storing or removing a key while the variable is set still works, and warns you that it has no effect until the variable is gone. Setting the same key the variable holds is silent, because nothing about it is surprising.

Where this earns its keep:

Pipelines. Map the secret that holds the key to a CAT_LICENSE_KEY variable on the step, and CAT reads it — no set-key step. See Integrations and the platform guides. On Azure DevOps, mind one trap: a step that maps a pipeline variable nobody defined passes the literal text $(CAT_LICENSE_KEY), which CAT refuses like any other unusable key.

Containers and throw-away sandboxes. A container has no .catconfig to keep, and re-running the set-key step in every new session is the only alternative. Pass the variable to the container and the image stays unchanged.

AI coding agents. Put the key into the agent’s secrets or environment settings and the agent never sees it. To store a key, an agent has to handle its text — pasted into the prompt, or read and put on a command line — after which the key sits in the conversation, in the transcript and in the command log.

Where it lives, and for whom

One store per machine and account: %APPDATA%\CAT\.catconfig (~/.config/CAT/.catconfig on Linux and macOS), shared by all four tools. Two consequences:

  • every user of a shared machine sets the key once for themselves — unless the key comes from the CAT_LICENSE_KEY environment variable, which needs no setup per account;
  • a pipeline agent, a scheduled task or a SQL Server Agent job runs under its own account — set the key under that account, or from a secret in the pipeline step; from CAT 3.0 an unattended run without it stops before any test runs. See Integrations.

An empty key removes it — catcli instance --setLicenseKey "", Set-CatInstance with no key, cat.set_instance("") — and the tools go back to sign-in.

Asked which key is set, the tools answer with a masked one — A...LrK8, the first and the last four characters of the key without its CAT3. prefix, the same short form the portal shows on its License Keys page. That is enough to tell keys apart and to match one against the portal; the .catconfig file is where the whole key lives, so keep a copy of it wherever you keep secrets.

← Get a CAT license
Manage CAT Pilot with Group Policy →