> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless Chat

> Send a prompt to CloudThinker from a script or CI job, pipe the answer, and collect long runs later by run ID.

`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](https://docs.cloudthinker.io/guide/cli/authentication.md#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`](https://jqlang.org) for the scripted examples on this page.
* [Connections](https://docs.cloudthinker.io/guide/connections/overview.md) for anything you want CloudThinker to inspect, such as an AWS account or a Kubernetes cluster.

## Send a prompt

**1. Ask a question**

```bash theme={null}
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:

```text theme={null}
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](https://docs.cloudthinker.io/guide/billing/usage.md).

**2. Pipe or save the answer**

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

```bash theme={null}
cloudthinker chat -p "Summarize yesterday's incidents" > summary.md
cloudthinker chat -p "List unattached EBS volumes, one ID per line" | grep vol-
```

**3. 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`:

```bash theme={null}
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:

```bash theme={null}
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](https://docs.cloudthinker.io/guide/agents/customize.md) 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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```text theme={null}
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`:

```bash theme={null}
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](https://docs.cloudthinker.io/guide/approvals/approvers.md) |
| 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:

```bash theme={null}
# 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](https://github.com/cloudthinker-ai/cloudthinker-cli/releases) lists a SHA-256 checksum for each archive.

A headless run follows the workspace [Approval mode](https://docs.cloudthinker.io/guide/approvals/approval-mode.md) like chat. If a prompt asks for a change that needs approval, the run pauses with exit code 5 instead of acting.

> [!WARNING]
>
> 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](https://docs.cloudthinker.io/guide/cli/authentication.md#authenticate-a-script-or-ci-job).

## 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](https://docs.cloudthinker.io/guide/cli/agent.md#run-the-agent-without-the-screen) |

## Troubleshooting

> [accordion] 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.

> [accordion] 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.

> [accordion] --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.

> [accordion] 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

> [card] [CLI authentication](https://docs.cloudthinker.io/guide/cli/authentication.md)
>
> Log in a runner, or hand a job a short-lived token

> [card] [CLI reference](https://docs.cloudthinker.io/guide/cli/reference.md)
>
> Every command, flag, variable, and exit code


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.