login & logout
These two commands open and close your connection to a Cotalker environment. If you've already read the Authentication page, you've met login — this page is the complete reference for both commands, including every option and the less common cases like on-premise environments.
cotctl login
login authenticates you against a Cotalker environment and saves the result as a reusable profile in ~/.cotctl/config.json. You typically run it once per environment.
cotctl login --url <webclient-url> --subdomain <subdomain> [options]
The key thing to remember: --url is the webclient address (what you'd type into a browser), not an API URL. cotctl discovers the API automatically from it.
Options
| Option | Required | Default | Description |
|---|---|---|---|
--url | Yes | — | Webclient URL of the environment |
--subdomain | Yes | — | Company subdomain |
--api-url | No | Auto-detected | Manual override of the API URL |
--no-browser | No | false | Use email/password instead of the browser flow |
--profile | No | Value of -c, else of --subdomain | Custom profile name. Wins over -c when both are given (see Naming the profile) |
-c / --company | No | — | The global profile option. On login it names the profile to save, as --profile does |
--machine-id | No | Sanitized hostname | Identifier embedded in the ApiToken's code, so you can tell tokens apart per machine |
--paste-token | No | false | Paste a pre-generated ApiToken instead of authenticating, typed at a prompt (see below) |
--token | No | — | The same, supplied as an argument, a file or standard input — the form that works with no terminal (see below) |
--yes / -y | No | false | Overwrite an existing profile without asking. Required in CI, where the prompt cannot be answered (see Overwriting an existing profile) |
--allow-unverified-company | No | false | Continue when the environment cannot confirm which company the token belongs to |
Naming the profile
The profile is named after --subdomain unless login is given a name: --profile <name>, or the global -c <name>, placed before or after login. That is how one company gets a profile per environment — two logins with the same --subdomain would otherwise save under the same name, and the second would ask to overwrite the first:
cotctl login --url https://web.cotalker.com --subdomain acme -c acme-prod
cotctl login --url https://web.staging.cotalker.com --subdomain acme -c acme-staging
cotctl apply -f survey.yaml -c acme-prod
Whatever the name, --subdomain still labels the company the profile belongs to. An empty or blank name counts as not given: -c "" saves under --subdomain. When --profile and -c are both given and differ, --profile wins, and login says so on stderr:
Warning: -c "acme-prod" is ignored — --profile "mine" names the profile this login saves.
Changed in 0.16.0. Before, login ignored -c and saved the profile under the --subdomain value. A script or alias that passes -c to login now finds the profile under the -c name — and when that name is a profile that already exists, login asks before overwriting it, or, without a terminal and without --yes, exits 1. With --yes it overwrites that profile with the credentials of whichever environment the login authenticated against, so check the name a script that passes both -c and --yes targets. The same holds for a wrapper that adds -c to every command.
Overwriting an existing profile
When the profile name is already taken, login asks before overwriting it — before it discovers the API URL, opens the browser or asks for a password, so a login that will not be saved mints no ApiToken. Answering n cancels with exit 1 and leaves the existing profile as it was:
Profile "acme" already exists. Overwrite? (y/N) n
Error: Login cancelled — the existing profile "acme" was not overwritten.
With no terminal attached (a pipe, a CI job), it fails immediately unless --yes is given, with Profile "<name>" already exists and there is no terminal to confirm the overwrite on. The one case asked after authenticating is a profile that another process saved while login ran: by then the browser and password flows have minted their token, so a cancellation names the token it leaves behind.
Browser flow (the default)
cotctl login --url https://web.cotalker.com --subdomain acme
This opens your browser on the Cotalker authentication page, you approve access, and the token is handed back to the CLI. The flow times out after 5 minutes if you don't complete it.
Email/password flow
When there's no browser available — a server, a CI runner — add --no-browser and you'll be prompted for credentials in the terminal:
cotctl login --url https://web.cotalker.com --subdomain acme --no-browser
On-premise environments
Most environments expose a variables file that lets cotctl auto-discover the API URL. If a customer runs Cotalker on their own infrastructure and that discovery fails, point cotctl at the API explicitly with --api-url:
cotctl login \
--url https://cotalker.empresa.com \
--subdomain emp \
--api-url https://api.empresa.com
Give the API's base URL: a trailing /api is dropped, with a notice, since cotctl adds the /api/… paths itself.
Pasting a pre-generated token
The two flows above both mint an ApiToken for you, which requires the admin-apitokens-write permission. If your user doesn't have it, there's a third path: an administrator issues an ApiToken for you from the webclient admin panel, and you register it with --paste-token:
cotctl login --url https://web.cotalker.com --subdomain acme --paste-token
cotctl prompts you to paste the token (masked), validates it against the backend, and saves the profile — no email/password and no browser involved. A pasted token can be saved in more than one profile: when another profile already holds the same token against the same API URL, login (with --paste-token or --token) saves the new profile anyway and warns on stderr, naming the profiles that hold it — see cotctl logout for what that means when one of them logs out. A token from the ApiTokens panel has no expiry, and the profile records none. Because it reads from a prompt, this flow needs a terminal: in a pipeline, use --token below or an environment credential instead. See CI/CD.
Logging in with no terminal: --token
New in 0.12.0. --paste-token reads from a prompt, which a pipeline cannot answer. --token takes the same pre-generated ApiToken as an argument instead, in three forms:
| Form | Reads the token from |
|---|---|
--token <jwt> | The value itself, on the command line |
--token @<path> | A file |
--token - | Standard input |
Prefer one of the two indirect forms. A bare value sits in the process arguments, where any process on the same host can read it — and a CI provider masks its own job log, not the process table. The recommended shape is:
echo "$CI_COTCTL_TOKEN" | cotctl login \
--url https://web.cotalker.com \
--subdomain acme \
--token - \
--yes \
--allow-unverified-company
All three forms are read before the API URL is discovered, before any request reaches the Cotalker backend and before login asks anything, so a missing or unreadable file, an empty or oversized stdin, or a terminal where - expects a pipe fails without waiting on the discovery.
Neither indirect form can hang or run away. --token - gives up 10 seconds after login starts reading it if the pipe stays open without delivering a token, and stops reading at 8 KB, so a job never burns its global timeout on a stalled stdin. --token @<path> warns — it does not fail — when the file is readable beyond its owner, so a secret mounted with your cluster's own mode still works.
Since 0.15.0, --token and --paste-token only take a token they can recognize as an ApiToken. A token whose type claim is missing or is not api-token — such as a session JWT copied from the browser — or one without an _id or a company claim is refused before it is sent anywhere, with exit 1; --allow-unverified-company does not waive the company claim. Mint an ApiToken with cotctl login, or have an admin issue one from the webclient's ApiTokens panel, and pass that one instead. A profile saved earlier from a session JWT is not checked again: it stops working when that session expires (within 7 days), and cotctl login replaces it.
--token and --paste-token supply the same thing, so passing both is an error. --machine-id is rejected alongside --token as well: it labels the machine that mints a token, and --token supplies one minted elsewhere.
Do not name the CI variable COTCTL_TOKEN. cotctl reserves that name as an environment credential, so exporting it changes the behaviour of every later command that omits -c.
Which one should a pipeline use? If the job addresses one company, prefer the environment credential — no login step, no profile file, no -c. Reach for --token when a single job has to address several companies, which one token cannot do. CI/CD walks through both.
Telling tokens apart with --machine-id
Each ApiToken carries a code that includes a machine identifier — by default your sanitized hostname — so you can recognize which machine a token came from in the admin panel. Override it with --machine-id <id> when the default isn't distinctive (for example, several ephemeral CI runners that share a hostname).
A value you pass with --machine-id is pinned, and survives re-authentication. cotctl records whether the identifier was chosen by you or derived from the hostname: a pinned one is reused when the token is renewed, and a derived one keeps being re-derived, so a renamed host is still picked up.
Fixed in 0.12.0, and it needs one action from you. Until this release the automatic re-login re-derived the identifier from the hostname and wrote it over whatever you had pinned, so the per-device naming reverted on the first renewal — and the token's code changed with it. A profile written before 0.12.0 carries no record of how its identifier was chosen and is treated as derived, so if you rely on the flag, run cotctl login --machine-id <id> once more to pin the value.
Where credentials live. The profile is written to ~/.cotctl/config.json with restrictive file permissions (0600). In the browser and email/password flows there is no token to copy or store yourself; with --paste-token or --token you supply one, and it is written to that same file.
A note on permissions
To apply resources (surveys, workflows, and so on) you need administration permissions in Cotalker. If a command later returns a 403, that's the platform telling you the logged-in user lacks the required permission — ask the company's administrator to grant it.
What the success line says
A login that mints a token reports it as created and prints a URL where you can revoke it. A login that supplies one — --token or --paste-token — reports API token "…" accepted and prints no revoke line, because you did not mint that token here and the panel that owns it may not even be yours to reach. Before 0.12.0 both said "created", which was misleading in the second case.
cotctl logout
logout removes a profile's credentials from your local config file.
cotctl logout <profile>
# or, equivalently:
cotctl logout -c <profile>
# revoke the token even when another profile still uses it:
cotctl logout <profile> --revoke
The positional <profile> is optional if you pass -c <profile> instead; when both are given, the positional one wins.
| Option | Description |
|---|---|
--revoke | Revoke the ApiToken even when another local profile still uses it, and name the profiles that can no longer authenticate |
logout revokes your token server-side. For modern API-token profiles, cotctl logout revokes the ApiToken on the Cotalker server and then removes the local profile, so the token can no longer be used. Revocation is best-effort: if the server can't be reached, cotctl still removes the local profile and warns you to revoke the token manually in the admin panel — so a logout never leaves you unable to log back in. (Legacy JWT profiles have nothing to revoke — they simply expire — so they're only removed locally.) This is the key difference from cotctl profile delete, which removes the profile locally only and leaves any token valid.
A token another profile still uses is not revoked (since 0.16.0). login --paste-token and login --token save a pre-generated ApiToken, so the same token can end up in several profiles. When another profile on this machine holds the same token against the same API URL, logout removes only the profile you named, keeps the token active and names, on stderr, the profiles that still use it. The last of them to log out revokes it; --revoke revokes it at once.
Only the profiles on this machine are checked. A token also saved on another machine, or kept as a CI secret, is still revoked by the last logout here; to remove a profile without touching the token, use cotctl profile delete. Revoking needs the admin-apitokens-write permission: without it the server refuses, logout warns and removes the local profile anyway, and the token stays active.
See also
- Authentication — the conceptual walkthrough of profiles and the
-cflag - Managing profiles — list and delete saved profiles