Skip to main content
The CLI signs in with your Cortex account, the same one the web and desktop apps use. You sign in once per machine and the CLI keeps the session in your operating system’s credential store, so you do not repeat it for every project. This page covers the interactive sign-in, the device-code route for machines without a browser, single sign-on, the unattended options for scripts and pipelines, how to check who you are signed in as, how to sign out, and where credentials are kept. If you have not installed the CLI yet, start with Install the CLI.

​
Sign in from a browser

A sign-in page opens in your browser. Approve it there and the CLI continues on its own. Confirm the result with cortex whoami. From inside a session, /login does the same thing without leaving the session. The inline sign-in screen offers exactly two rows, Continue with browser and Paste an API key. There is no guest row and no exit row: pick one of the two, or press Esc. While the CLI is waiting it shows Waiting for browser authentication…. On success it prints Signed in as .... If the attempt expires, is refused, or the credential store rejects the write, it prints Sign-in didn't complete and you can run cortex login again.

​
Sign in on a machine without a browser

For a server, a container, or a remote shell:
The CLI prints a short code, for example Your code WXYZ-1234, along with the address to visit. Open that address on any device that does have a browser, enter the code, and approve the sign-in. The CLI picks the session up as soon as you have approved it.

​
Single sign-on

Use this when your organization signs in through single sign-on. The web sign-in dialog offers the same route, labelled Single sign-on (SSO).

​
Unattended runs and CI

Do not use the browser flow in a pipeline. There is no browser to open and, on most runners, no credential store to write to, so cortex login on its own cannot complete. Read the secret from standard input so it never reaches your shell history or the process list:
Or skip cortex login altogether and set a variable for the job: The CLI resolves credentials in this order: CORTEX_AUTH_TOKEN first, then CORTEX_API_KEY, and the credential cortex login stored last. An environment variable therefore wins over a stored sign-in, which is what makes a runner predictable, and what to check first when a machine keeps acting as an account you did not expect.
Take the value from your secret store at run time. Never write a key or a token into a workflow file, a configuration file, or a commit.

​
Check the state, and sign out

Inside a session the equivalents are /account (aliases /whoami and /me), /login and /logout.

​
Where credentials are kept

Sign-in writes to your operating system’s credential store, under the service name cortex-cli and the account name auth. Credentials are deliberately not written to a plaintext file in your home directory, and never into the repository you are working in. The session material the CLI does keep in its own home directory carries no secrets.
If no credential store is available, a bare container or a headless runner for instance, use CORTEX_API_KEY or CORTEX_AUTH_TOKEN rather than trying to make a store work.

​
When sign-in does not work

The CLI could not reach api.cortex.foundation. Check network access and any proxy in front of it, then try again. This message is deliberately the whole story: the CLI does not surface provider, SDK or transport names, so there is no extra detail hiding behind it.
The credential store did not persist the session. On Linux, check that a Secret Service provider is actually running in your session; over SSH or in a minimal desktop there often is not one. Otherwise fall back to CORTEX_API_KEY.
It tried the browser flow. Use cortex login --with-api-key or cortex login --token, or set CORTEX_API_KEY in the job environment and skip cortex login entirely.
The stored session expired or was cleared. Run cortex login again. If it keeps happening on the same machine, the credential store is probably not persisting between runs; the two checks above apply.