--- title: "signin" description: "catcli signin — sign in to CAT Portal with a code sent to your email, and see who is signed in." url: "https://docs.justcat.it/reference/cat-cli/signin/" --- # signin ## Synopsis ``` catcli signin --email [--userName ] catcli signin --email --code catcli signin --status ``` ## Options | Short | Long | Value | Meaning | |-------|------|-------|---------| | `-e` | `--email` | email | The address to sign in. Needed by both steps. | | `-c` | `--code` | code | The code from the mail. With it the command finishes the sign-in. | | `-u` | `--userName` | name | User name for a new CAT Portal account. Optional: without it the name is made from the email. Not used when the account already exists. Only without `--code`. | | `-s` | `--status` | | Show who is signed in. Alone. | | `-l` | `--loggingLevel` | level | `None` (default), `Information`, `Debug`, … — see [Logging](https://docs.justcat.it/reference/cat-cli/introduction/#logging "Logging"). | Use exactly one of the three forms in the synopsis. Any other combination prints the usage line and exits with code `1`. ## What it does Signing in takes two steps, and nothing waits between them: each command returns at once. 1. `catcli signin --email you@example.com` asks CAT Portal to mail a 6-digit code to that address. 2. `catcli signin --email you@example.com --code 123456` finishes the sign-in with the code from the mail. Both steps carry the email; CAT CLI remembers nothing between them. An email that has no CAT Portal account yet gets one when the code is used. By using the code you accept the [terms of use](https://docs.justcat.it/terms-of-use/ "Terms of use") and the [privacy policy](https://docs.justcat.it/privacy-policy/ "Privacy policy"); the first step says so with the two links. Nothing about your computer is sent to CAT Portal. `--userName` names the new account. It is used only when the code creates the account; for an account that exists it changes nothing. Without it the name is made from the email. A name somebody already has is not refused: the new account gets it with a space and four digits. The sign-in is a personal access token that CAT Portal issues for you, valid for 90 days. CAT CLI keeps it in `.catportaltoken`, in `%APPDATA%\CAT\` on Windows and in `~/.config/CAT/` on Linux and macOS, next to `.catconfig`. On Linux and macOS the file can be read by your user only. The token is never printed. Every verb that needs sign-in finds it there; to remove it, use [`catcli signout`](https://docs.justcat.it/reference/cat-cli/signout/ "signout"). CAT Portal lists it among your personal access tokens as `CAT CLI, signed in UTC`. The limits are CAT Portal's: ten codes per email in 24 hours; a code is valid for 10 minutes and stops working after five wrong tries. Ask for a new code with the first step again. `signin` is for the **Starter** and **Team** plans. With a valid Enterprise license key CAT needs no sign-in, and both steps are refused before CAT Portal is contacted. The PowerShell and Python modules never sign in: they need a license key. `CAT_PORTAL_TOKEN` is the other way to sign in. While the variable is set, CAT signs in with it, and both steps are refused, so no code is mailed and none is used up; `catcli signout` is refused too. `--status` works and names the variable. See [Sign-in, plans and the license key](https://docs.justcat.it/reference/cat-cli/introduction/#sign-in-plans-and-the-license-key "Sign-in, plans and the license key"). A machine that starts fresh for every session, such as a cloud sandbox, keeps no `.catportaltoken` between sessions and would ask for a code every time. Give it a personal access token as a secret in the `CAT_PORTAL_TOKEN` variable instead. `signin` does not run the sign-in and plan check, so it works on an expired version and with any plan. ## Output ### `catcli signin --email ` On success, to standard output: ``` A sign-in code was sent to you@example.com. The code is valid for 10 minutes. By using the code you accept the terms of use (https://docs.justcat.it/terms-of-use) and the privacy policy (https://docs.justcat.it/privacy-policy). To finish: catcli signin --email you@example.com --code ``` The second line is CAT Portal's own. | Situation | What it prints | Exit code | |---|---|---| | The code was mailed | the lines above | `0` | | Ten codes were already sent to this email in the last 24 hours | CAT Portal's message, then three steps: sign in at CAT Portal or sign up there, create a token under **Developer → Personal access tokens**, set it as the `CAT_PORTAL_TOKEN` environment variable | `14` | | Too many requests from your computer or network | `Too many sign-in requests from this computer or network. Wait a few minutes and try again.` | `14` | | CAT Portal does not accept the email or the user name | CAT Portal's messages, one per line | `1` | | CAT Portal cannot be reached | `Can't reach CAT Portal. Check the connection and try again.` | `4` | ### `catcli signin --email --code ` On success, to standard output: ``` Signed in as you@example.com. Plan: Starter. The sign-in is valid for 90 days, until 2027-02-09. ``` The email is your account's, as CAT Portal stores it. When the code created the account, two lines follow the first: ``` A new CAT Portal account was created for this email. A second email explains how to set a password for CAT Portal and CAT Studio. CAT CLI does not need one. ``` When the sign-in is stored but the plan could not be read, the first line is `Signed in as you@example.com.` and `The plan could not be read; run catcli signin --status.` follows. The exit code is `0`: you are signed in. | Situation | What it prints | Exit code | |---|---|---| | Signed in | the lines above | `0` | | The code is wrong, expired or already used | `The sign-in code for you@example.com was not accepted - it is wrong, expired or already used.`, how to check the code, and how to ask for a new one | `13` | | Too many requests from your computer or network | `Too many sign-in requests from this computer or network. Wait a few minutes and try again.` | `14` | | CAT Portal does not accept the request | CAT Portal's messages, one per line | `1` | | CAT Portal cannot be reached | `Can't reach CAT Portal. Check the connection and try again.` | `4` | ### Refused in both steps | Situation | What it prints | Exit code | |---|---|---| | A valid Enterprise license key is set | `A valid Enterprise license key is set on this machine. CAT needs no sign-in, and catcli signin does nothing.` | `1` | | `CAT_PORTAL_TOKEN` is set | `CAT_PORTAL_TOKEN is set, and CAT signs in with it. catcli signin does nothing while it is set.`, then to remove the variable first, and that `catcli signin --status` shows who the variable signs in | `1` | | `CAT_LICENSE_KEY` holds no key CAT can use | the same message as every other verb | `8` | All of these go to standard error. ### `catcli signin --status` Says who is signed in, on which plan, and how. It asks CAT Portal with the token it finds, so the answer is CAT Portal's. | Situation | What it prints | Exit code | |---|---|---| | A valid Enterprise license key is set | `A valid Enterprise license key is set. CAT needs no sign-in.` CAT Portal is not contacted. | `0` | | Signed in with `catcli signin` | `Signed in as you@example.com. Plan: Team.` and `Signed in with: a code from your email, valid for 82 more days, until 2027-02-09.` | `0` | | Signed in with `CAT_PORTAL_TOKEN` | `Signed in as you@example.com. Plan: Team.` and `Signed in with: the CAT_PORTAL_TOKEN environment variable.` | `0` | | Signed in, CAT Portal cannot be reached | the two lines above, then `Working offline; authorised until . Reconnect before then.` on standard error | `0` | | Nobody is signed in | `Nobody is signed in to CAT Portal on this machine.` and the two ways to sign in | `2` | | The sign-in from `catcli signin` expired or was revoked | `The sign-in of you@example.com is no longer valid - it expired or was revoked.` and `Sign in again: catcli signin --email you@example.com` | `2` | | The token in `CAT_PORTAL_TOKEN` was rejected | that the token in the variable was rejected, and to set a valid one or remove the variable | `2` | | The stored sign-in cannot be read | `The stored sign-in in cannot be read.` and how to sign in again | `2` | | The plan does not allow the sign-in | CAT Portal's message | `3` | | CAT Portal cannot be reached and nothing is cached | `Can't reach the CAT portal and no usable cached authorisation was found. Connect to the portal once to continue.` | `4` | | `CAT_LICENSE_KEY` holds no key CAT can use | the same message as every other verb | `8` | The rows with exit code `0` print to standard output, except the "Working offline" line; every other row prints to standard error. **A license key that ran out.** When your stored license key has expired (or cannot be used) and somebody is signed in, one more line follows on standard output: `The license key on this machine expired on 2026-06-30; CAT runs on the plan of the sign-in.` When nobody is signed in, the message names the key first: how to set the renewed key with `catcli instance --setLicenseKey`, where the renewal is explained, and only then that `catcli signin` continues on the Starter or Team plan. `--status` reports the sign-in only. It does not run the rest of the check a verb runs at its start, so exit code `0` does not promise that the next verb runs: an expired version or an autonomous run is still refused there, with its own message. ## Exit code `0` when the step succeeded or the status was shown. `1` for a wrong combination of options, a refused step, or a request CAT Portal does not accept. `2`, `3` and `4` from `--status` mean what they mean at the sign-in and plan check. `8` when `CAT_LICENSE_KEY` holds no key CAT can use. `13`: the 6-digit sign-in code from the email was not accepted (wrong, expired or already used). `14`: too many sign-in requests — ten codes were already sent to this email in the last 24 hours, or too many requests came from your computer or network in a short time. See [Exit codes](https://docs.justcat.it/reference/cat-cli/introduction/#exit-codes "Exit codes"). ## Examples ``` # who is signed in? catcli signin --status # sign in: ask for a code, then finish with the code from the mail catcli signin --email you@example.com catcli signin --email you@example.com --code 123456 # a new account with a user name of your choice catcli signin --email you@example.com --userName "Jane Doe" ``` ## Related - [signout](https://docs.justcat.it/reference/cat-cli/signout/ "signout") — remove the sign-in. - [Sign-in, plans and the license key](https://docs.justcat.it/reference/cat-cli/introduction/#sign-in-plans-and-the-license-key "Sign-in, plans and the license key"). - [CAT Portal](https://docs.justcat.it/reference/cat-portal/ "CAT Portal") — personal access tokens.