Headless Chat

cloudthinker chat -p sends one prompt to CloudThinker in the cloud and prints the answer. Only the answer goes to stdout, so it drops straight into a pipe, a file, or a CI step, and the run keeps going on the server if your terminal disconnects.

Prerequisites

The CloudThinker CLI installed and logged in. For CI, see Authenticate a script or CI job: there is no service account or long-lived API key yet, so a job runs on a login or a short-lived token.
jq for the scripted examples on this page.
Connections for anything you want CloudThinker to inspect, such as an AWS account or a Kubernetes cluster.

Send a prompt

Ask a question

cloudthinker chat -p "List EC2 instances in us-east-1 with average CPU under 5% this week"

A spinner on stderr shows the run status while you wait.Success state: stderr shows one line, then the answer prints on stdout:

continue_with=0f9e364e-9c34-406e-be7d-52a143fede85 web_url=<link to the conversation>
<CloudThinker's answer, as plain text>

Each run uses workspace credits, like a chat turn. A nightly CI job spends them too, so keep an eye on Usage.

Pipe or save the answer

stdout holds only the answer, so redirect it like any other command:

cloudthinker chat -p "Summarize yesterday's incidents" > summary.md
cloudthinker chat -p "List unattached EBS volumes, one ID per line" | grep vol-

Follow up in the same conversation

Pass the continue_with ID, or the run ID, to --continue. In a script, capture it with --json and jq:

conv=$(cloudthinker chat -p "Draft a rollout plan for the api service" --json < /dev/null | jq -r .conversation_id)
cloudthinker chat -p "Remove the risky step" --continue "$conv"

Open the web_url to see the same conversation in the browser. Only one turn runs in a conversation at a time, so wait for the previous run to finish first.

Send input from another command

Piped stdin joins your prompt, so you can hand CloudThinker logs, diffs, or files:

kubectl logs deploy/api --tail 200 | cloudthinker chat -p "Why does this crash?"
cloudthinker chat -p - < prompt.md

Input	What CloudThinker receives
`-p "text"` with nothing piped	Your text
`-p "text"` with piped stdin	Your text, then the piped data in `<stdin>` tags
`-p -`	The whole prompt read from stdin

The prompt and piped data together can be up to 50,000 characters. If stdin is open but sends nothing, the CLI waits 3 seconds and sends the prompt alone. In scripts with nothing to pipe, add < /dev/null to skip the wait. To have a custom agent answer, pass its UUID or alias: --agent <uuid-or-alias>.

Submit now, collect later

A long investigation doesn’t need to hold your terminal. --no-wait returns as soon as the run is queued:

run=$(cloudthinker chat -p "Which S3 buckets have no lifecycle policy?" --no-wait --json < /dev/null | jq -r .run_id)

The command prints one JSON object:

{
  "run_id": "7d5fae84-be6f-45fa-802f-5041f0ff5d42",
  "conversation_id": "0f9e364e-9c34-406e-be7d-52a143fede85",
  "status": "pending",
  "web_url": "<link to the conversation>"
}

Collect the answer later, from any machine logged in to the same workspace:

cloudthinker chat status "$run" --wait
cloudthinker chat ls --limit 10
cloudthinker chat ls --conversation 0f9e364e-9c34-406e-be7d-52a143fede85 --json

Plain chat ls prints one tab-separated row per run:

RUN ID  CONVERSATION ID  STATUS  PROMPT  CREATED AT  WEB URL

Stopping the wait never cancels the run, and the CLI has no command that cancels one. --timeout (default 2400 seconds) and Ctrl-C only stop the CLI from waiting; the CLI prints the chat status command that picks the run back up. Follow the same run ID rather than sending the prompt again, so the work doesn’t run twice.

Read JSON output

--json writes one JSON object to stdout instead of the plain answer.

Field	Meaning
`run_id`	The run to follow with `chat status`
`conversation_id`	The conversation to pass to `--continue`
`status`	One of the statuses below
`answer`	CloudThinker’s answer, or `null` while the run is unfinished
`web_url`	The conversation in the browser
`message`	Extra detail from the server, when there is any
`failure_kind`	A short reason code for a failed run, when known. Treat it as detail for a person to read, not a value to branch on

With --no-wait --json, only run_id, conversation_id, status, and web_url come back, because no answer exists yet.

`status` in JSON	Plain `chat status` shows	Meaning
`pending`	`pending`	Queued
`running`	`running`	CloudThinker is working
`succeeded`	`succeeded`	Finished; `answer` is set
`failed`	`failed`	Finished without an answer
`required_approval`	`approval required`	Paused until someone approves an action in the browser
`cancelled`	`cancelled`	Stopped before it finished

A run that needs an approval stays required_approval until someone decides in the browser; the CLI prints Approval required. Approve in your browser: <link> and exits 5. Branch on the exit code rather than the answer, because answer is null for anything but succeeded:

out=$(cloudthinker chat -p "Check the error budget for checkout" --json < /dev/null) && echo "$out" | jq -r .answer

Exit codes

Branch on the exit code instead of parsing text.

Code	Meaning	What to do
0	The run finished and the answer printed	Use the answer
1	The run failed or was cancelled, or the run ID is unknown	Read the error on stderr
2	Bad usage, or the server rejected the request	Fix the command; don’t resend it unchanged
3	Not logged in, the credential expired, or access was refused	Run `cloudthinker login`, or replace `CLOUDTHINKER_TOKEN`
4	The CLI stopped waiting; the run continues	Run `chat status <run_id> --wait`
5	The run paused for an approval in the browser	Open `web_url` and decide, or ask an approver
130	You pressed Ctrl-C; the run continues	Run `chat status <run_id> --wait`

chat ls and chat status without --wait exit 0 after a successful read, even if the run is still going. chat status --wait returns the run’s own code.

Use it in CI

Install the CLI on a runner you control, log in on it once with cloudthinker login --device-auth (the saved login refreshes itself), save the run ID, and let the exit code decide:

# Once, on the runner: install the CLI and log in.
#   curl -fsSL https://cloudthinker.io/install.sh | sh
#   cloudthinker login --device-auth
export PATH="$HOME/.local/bin:$PATH"

# Submit first, so the run ID exists even if the wait below times out.
run=$(cloudthinker chat -p "Review last night's failed deployments and list the likely cause of each" \
  --no-wait --json < /dev/null | jq -r .run_id)
echo "$run" > run_id.txt    # upload as a job artifact

# Most CI shells run with `set -e`, which would end the job on a non-zero
# exit before the case below runs. `|| code=$?` keeps the job alive.
code=0
cloudthinker chat status "$run" --wait --timeout 900 > report.md || code=$?

case $code in
  0) echo "report ready" ;;
  4) echo "still running, collect it in the next job with: cloudthinker chat status $run --wait" ;;
  5) echo "waiting for an approval in the browser"; exit 5 ;;
  *) exit 1 ;;
esac

Code 4 ends this job green on purpose, so a later job can collect the report; report.md is empty until then. Code 5 fails the job here, because nothing happens until a person decides. Change either line to suit your pipeline. To pin a version, download the installer from that release instead of install.sh: https://github.com/cloudthinker-ai/cloudthinker-cli/releases/download/v<VERSION>/cloudthinker-cli-installer.sh. Each release on the releases page lists a SHA-256 checksum for each archive. A headless run follows the workspace Approval mode like chat. If a prompt asks for a change that needs approval, the run pauses with exit code 5 instead of acting.

Under Auto, a write that your rules or the AI check allow runs at once, with no person in the loop. The run acts as the user who logged in on the runner (or whose token the job holds), and that’s who CloudThinker records for it. There is no service account yet, so choose that login with care. See CLI authentication.

Headless chat or headless agent?

You want	Use
CloudThinker to investigate your cloud through workspace connections, and keep running if you disconnect	`cloudthinker chat -p`
An answer about the files in this folder, on this machine	`cloudthinker agent -p`. See Agent CLI

Troubleshooting

The command hangs for a few seconds before starting

Stdin is open with no data, so the CLI waits 3 seconds for input. Add < /dev/null when nothing is piped.

The prompt is rejected as too long

The prompt plus piped input is over 50,000 characters. Trim the input, for example with --tail on logs.

--continue fails because a stream is already active

Another run is still working in that conversation. Wait for it with chat status <run_id> --wait, then continue.

The run exits with code 5

CloudThinker wants to make a change your workspace requires a person to approve. Open the web_url, decide, then check the same run with chat status <run_id> --wait. Don’t submit a new run to get around the approval.

Next steps

CLI authentication

CLI reference

Every command, flag, variable, and exit code

Start here

Learn the basics

Help

Work where you are

Prerequisites

Send a prompt

Send input from another command

Submit now, collect later

Read JSON output

Exit codes

Use it in CI

Headless chat or headless agent?

Troubleshooting

Next steps

CLI authentication

CLI reference

​Prerequisites

​Send a prompt

​Send input from another command

​Submit now, collect later

​Read JSON output

​Exit codes

​Use it in CI

​Headless chat or headless agent?

​Troubleshooting

​Next steps

CLI authentication

CLI reference

Prerequisites

Send a prompt

Send input from another command

Submit now, collect later

Read JSON output

Exit codes

Use it in CI

Headless chat or headless agent?

Troubleshooting

Next steps