CLI Reference

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

These come before the subcommand and apply to every authenticated command.

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`
`-h`, `--help`	Print help for the command
`-V`, `--version`	Print the CLI version

cloudthinker --help listing every command and global option

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.

CLI overview

Install the CLI and run your first session

Headless chat

Run prompts from scripts and pipelines

APIs & Tooling

Deployment

Global options

Authentication commands

Agent

Chat

Review

Update

Environment variables

Exit codes

Files

CLI overview

Headless chat

​Global options

​Authentication commands

​Agent

​Chat

​Review

​Update

​Environment variables

​Exit codes

​Files

​Related

CLI overview

Headless chat

Global options

Authentication commands

Agent

Chat

Review

Update

Environment variables

Exit codes

Files

Related