CLI Reference

Look up every cloudthinker command, flag, environment variable, and exit code in one place

Every command in the cloudthinker binary, with the flags it accepts and the codes it returns. Start with the CLI overview if you have not installed it yet.

Global options

Put --url and --workspace before the subcommand. --skill, help, and version work without authentication.

Option	Description
--url <URL>	API base URL. Defaults to https://app.cloudthinker.io. Pass the bare origin, not a path under it
--workspace <ID or NAME>	Use the stored credential for this workspace. Cannot be combined with CLOUDTHINKER_TOKEN
--skill [MODULE]	Print the bundled agent guidance and exit. Modules: auth, chat, review; omit the module for the index
-h, --help	Print help for the command
-V, --version	Print the CLI version

Authentication commands

Command	Description
login	Browser login over a loopback callback
login --no-browser	Print the consent URL instead of opening a browser
login --device-auth	Authorize with a short code on another device
logout	Clear the credential for the selected or active workspace
logout --all	Clear every credential stored for this host
whoami	Print the live host, account, and workspace behind the credential
auth token	Print the current access token on stdout, refreshing it first when it is close to expiry

Details and CI patterns live in CLI authentication.

Agent

Command	Description
agent	Run the local coding agent in the current directory
agent <args...>	Pass every argument to the agent verbatim
agent -- <args...>	Force pass-through when an agent option shares a name with a CLI option

A bare cloudthinker runs agent. See Agent CLI.

Chat

Command	Description
chat -p <PROMPT>	Submit a prompt and wait for Anna’s answer
chat -p ... --continue <UUID>	Continue a conversation, by run ID or conversation ID
chat -p ... --no-wait	Return as soon as the run is queued
chat -p ... --timeout <SECS>	Stop waiting after this many seconds. Default 2400. The run continues server-side
chat -p ... --json	Emit one JSON envelope instead of the plain answer
chat status <RUN_ID>	Show a run’s current state, and its answer when it has one
chat status <RUN_ID> --wait	Poll the run until it reaches a terminal state
chat ls	List recent headless runs, newest first
chat ls --conversation <UUID>	List only the runs in one conversation
chat ls --limit <N>	Return up to N runs, 1 to 50. Default 10

In human mode, chat -p writes only the answer to stdout; progress and the continue_with= hint go to stderr. See Headless chat.

Review

Read a Review that CloudThinker already tracks, by pasting the merge-request or pull-request URL. These commands never start a review.

Command	Description
review status <MR_URL>	One-shot summary: merge request, provider, title, status, verdict, finding count
review findings <MR_URL>	List the findings, worst severity first
review watch <MR_URL>	Poll the review until it reaches a terminal state

All three accept --json, and watch also accepts --timeout <SECS>.

cloudthinker review status https://gitlab.com/acme/api/-/merge_requests/128
cloudthinker review findings https://github.com/acme/api/pull/412 --json

A finding line reads [severity] file:line (category) — title, with [resolved] appended once an agent has settled it.

Value	Where it appears
in review, review complete, filtered, failed	Review status
in review, approved, review suggested, changes requested, failed, filtered	Review verdict

Update

Command	Description
update	Install the latest release over the running one
update --force	Reinstall the latest release even when it is already current
update --json	Emit { updated, old_version, new_version } instead of a human line

On an interactive terminal the CLI also offers an update at start-up when a newer release exists. The check has a two second budget and never delays or fails a start. CLOUDTHINKER_NO_UPDATE_CHECK=1 turns it off.

update only works on an installation the CLI installer created. A binary copied into place by hand is refused with the reinstall command to run instead.

Environment variables

Variable	Effect
CLOUDTHINKER_URL	API base URL, same as --url
CLOUDTHINKER_WORKSPACE	Workspace ID or exact name, same as --workspace
CLOUDTHINKER_TOKEN	Bearer token to use instead of stored credentials. Cannot be combined with --workspace
CLOUDTHINKER_NO_UPDATE_CHECK	Set to 1 to silence the start-up update offer
NO_COLOR	Suppress color in stderr output. Color is off automatically when stderr is not a terminal

Exit codes

Code	Meaning
0	Success
1	The job failed: a failed run, an unknown run or review, or exhausted transport retries
2	Bad usage, or a request rejected by workspace policy
3	Not logged in, or the credential expired
4	The CLI stopped waiting. The work continues server-side
5	The run paused for an approval in the browser

Files

Path	Contents
<config dir>/cloudthinker/credentials.json	One credential per workspace for each host, owner-readable only
~/.cloudthinker/agent/bin/<version>/	The installed agent bundle for that CLI version
~/.local/bin/cloudthinker	The binary the installer places on your PATH

To remove the CLI, run cloudthinker logout --all to clear the stored credentials, then delete the binary and the ~/.cloudthinker directory.

Related

CLI overview

Install the CLI and run your first session

Headless chat

Run prompts from scripts and pipelines