CLI Authentication

The CloudThinker CLI signs you in through your browser and stores one credential per workspace, so you never paste an API key. This page covers logging in on a laptop or remote machine, switching workspaces, and authenticating scripts and CI jobs.

Prerequisites

The CLI is installed. See CLI overview.
A CloudThinker account with access to at least one workspace. A workspace is the project that holds your connections and conversations.

Log in

Start the login

cloudthinker login

On an interactive terminal, the CLI asks How would you like to log in?

Option	Use it when
Log in with browser	You are on your own machine with a browser. Recommended for most users
Log in with a code	You are in an SSH or remote session without a browser

Use the arrow keys or press 1 or 2, then Enter.

Approve in the browser

The CLI prints Open this URL to authorize CloudThinker: with the link and opens it. Press c to copy the link if the browser didn’t open. Sign in, choose the workspace, and approve the request within five minutes.

cloudthinker login printing the consent URL before opening the browser

Success state: the terminal prints Logged in to <workspace>.Picked Log in with a code? Follow Log in on a remote machine instead.

Verify the credential

cloudthinker whoami

whoami asks the API, not the local file, so it proves the credential works.Success state: one line with host=, email=, and workspace= values. Add --json for machine-readable output.

Log in on a remote machine

Over SSH, or on Linux with no display, the CLI picks the code flow on its own and says so: No local browser detected (SSH session). Using device-code login. It prints a URL and a short code. Open the URL in any browser, on any device, and enter the code within 10 minutes.

Open this URL to authorize CloudThinker:
  <verification URL>

Enter this code:
  <code>

To	Run
Force the code flow	`cloudthinker login --device-auth`
Print the URL without opening a browser	`cloudthinker login --no-browser`
Always use one flow on this machine	Set `CLOUDTHINKER_LOGIN=browser` or `CLOUDTHINKER_LOGIN=device`

Work with several workspaces

Log in once per workspace. Each login is stored by host and workspace, so logging in to a second workspace keeps the first.

To	Run
List saved workspace logins and see the active one	`cloudthinker auth status`
Make another saved login the active one	`cloudthinker auth switch Production`
Use a workspace for one command	`cloudthinker --workspace Production whoami`
Use a workspace for the whole shell session	`export CLOUDTHINKER_WORKSPACE=Production`

--workspace, auth switch, and CLOUDTHINKER_WORKSPACE take a workspace ID or the exact workspace name. Quote names that contain spaces. --workspace goes before the command name:

cloudthinker --workspace 11111111-1111-4111-8111-111111111111 chat -p "Check the error budget"

Use a custom host

To use a host other than https://app.cloudthinker.io, run cloudthinker login --url <origin> once. Later commands remember it. You can also set CLOUDTHINKER_URL. See the CLI reference.

Authenticate a script or CI job

A pipeline has no browser, so it can’t approve a login. CloudThinker has no service account or long-lived API key for the CLI yet. Access tokens last 30 minutes by default.

Method	Use it when
Log in on the runner (recommended)	The job runs on a runner you control. Run `cloudthinker login --device-auth` on it once. The saved login refreshes itself, so the job needs no token variable
`CLOUDTHINKER_TOKEN`	A short job gets a token from a wrapper that just ran `cloudthinker auth token`. The CLI uses it and ignores stored credentials. It never refreshes it, so the job fails with exit code 3 once the token expires
`cloudthinker auth token`	Another tool needs a bearer. The command prints the current access token on stdout and nothing else, refreshing it first if it is close to expiry

A runner login acts as the person who logged in, so every job on that runner runs with their access. Use a dedicated CloudThinker user for it if your organization allows one. To revoke it, run cloudthinker logout on the runner.

# Short job: a wrapper hands the CLI a fresh token
export CLOUDTHINKER_TOKEN="$(cloudthinker auth token)"
cloudthinker chat -p "Summarize last night's failed runs" --json

The token from cloudthinker auth token authenticates as you until it expires. Treat it like a password: never log it, commit it, or paste it into a chat. You can’t combine CLOUDTHINKER_TOKEN with --workspace. The token already names its workspace, so the CLI rejects both together with exit code 2.

Where credentials live

The CLI writes credentials as plain JSON to one file, readable only by your user (mode 0600). It doesn’t use the OS keychain; releases before 0.5.3 did, and upgrading moves those logins into the file.

OS	Path
macOS	`~/Library/Application Support/cloudthinker/credentials.json`
Linux	`$XDG_CONFIG_HOME/cloudthinker/credentials.json`, or `~/.config/cloudthinker/credentials.json` when that variable isn’t set

The file holds every workspace login, keyed by host and workspace.

Log out

cloudthinker logout          # the selected or active workspace
cloudthinker logout --all    # every workspace stored for this host

Logout asks the server to revoke the credential, then deletes it from the local file. The local copy is removed even if the server can’t be reached. Success state: the terminal prints Logged out., or Logged out of all workspaces for this host.

Troubleshooting

A command says you are not logged in (exit code 3)

The credential is missing or expired, or the server refused access. Run cloudthinker login again. In a non-interactive shell, the CLI never opens a browser: it prints the login command to run and stops.

CLOUDTHINKER_TOKEN is rejected, or auth switch has no effect

The environment token outranks stored credentials, so logging in again or running auth switch changes nothing. Replace the token, or run unset CLOUDTHINKER_TOKEN and use your saved logins.

A workspace name is not accepted

--workspace matches an exact name or a workspace ID. Run cloudthinker auth status to see your saved workspaces, and quote a name that contains spaces.

Start here

Learn the basics

Help

Work where you are

Prerequisites

Log in

Log in on a remote machine

Work with several workspaces

Use a custom host

Authenticate a script or CI job

Where credentials live

Log out

Troubleshooting

Next steps

Headless chat

CLI reference

​Prerequisites

​Log in

​Log in on a remote machine

​Work with several workspaces

​Use a custom host

​Authenticate a script or CI job

​Where credentials live

​Log out

​Troubleshooting

​Next steps

Headless chat

CLI reference

Prerequisites

Log in

Log in on a remote machine

Work with several workspaces

Use a custom host

Authenticate a script or CI job

Where credentials live

Log out

Troubleshooting

Next steps