> ## 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.
# Agent CLI
> Run a local coding agent in your repository that reads and changes your cloud through the CloudThinker Sandbox with workspace approval
**Preview** — `cloudthinker agent` ships with the CloudThinker CLI for macOS and Linux and needs a paid workspace plan. [Contact us](https://cloudthinker.io/contact) to join the preview.
`cloudthinker agent` is a coding agent that runs in your terminal, built on [pi](https://github.com/badlogic/pi-mono). It edits files and runs commands on your machine, and it reaches your cloud only through the CloudThinker Sandbox with your workspace connections.
## Why the Agent CLI
* **Your repository stays local.** The model loop, file edits, and shell commands run on your laptop.
* **No cloud credential on your machine.** A cloud command runs in the CloudThinker Sandbox with a connection credential injected for that run only.
* **Workspace rules apply.** A cloud write follows the same [Auto Mode](/guide/auto-mode) and approval rules as chat.
* **Every session is mirrored.** Teammates can read the session in the browser, and the workspace audits and bills it.
## Start a session
Install the [CloudThinker CLI](/guide/cli/overview) and run `cloudthinker login`. The agent runs the browser login for you when no credential exists.
```bash theme={null}
cd my-terraform-repo
cloudthinker agent
```
On first run the CLI downloads the agent bundle for your platform and verifies its checksum.
The header names the workspace, your user, the session link, and the workspace approval mode as `· Auto` or `· Manual`.
**Success state:** the footer shows `◆ 0.00 credits` and your first prompt is ready.
## Two environments
The agent works in exactly two places and tells you which one it is using.
| Environment | What runs there | Credentials |
| ------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Your machine** | pi's local tools: bash, read, write, edit, grep, find, ls | none from CloudThinker |
| **CloudThinker Sandbox** | `ct_cloud_read` and `ct_cloud_write` | a workspace connection credential, injected per run and never sent to your machine |
A connection is a credential the Sandbox can use, not a third environment. The agent sees the same connection detail Anna sees in chat, refreshed before every turn, so a connection you add in the browser is available on your next prompt.
A command can use multiple named AWS and GCP connections together with GitLab. Tell the agent which aliases to use. Each cloud execution keeps its credentials and local file edits isolated; only new declared output files return to the workspace, and existing files are not overwritten.
## Cloud tools
| Tool | Use | Where it runs |
| ---------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `ct_cloud_read` | A bounded read-only investigation, such as listing buckets or describing a deployment | CloudThinker Sandbox |
| `ct_cloud_write` | One state-changing command you can name, such as a rollout restart | CloudThinker Sandbox, after the workspace decides |
| `ct_ask` | Work that needs the workspace itself: memory of past incidents, a specialist agent, or several dependent steps | Anna, in a linked conversation |
A `ct_ask` run opens one Anna thread per session and reuses it. `ct_run_status` resumes a paused run after an approval.
## Approve a cloud write
A cloud write is a request the workspace decides, not a call. The agent requests it, and the terminal pins a card above the editor with the reason, the connection, the command, and a browser link.
| Result line | Meaning |
| ---------------------------------------------------------------------- | -------------------------------------------------------- |
| `auto: allowed (trusted command) · ran in CloudThinker Sandbox · 2.0s` | Auto Mode allowed it and it ran at once |
| `auto: needs approval` | Auto Mode paused it for a person |
| `manual: needs approval` | The workspace is in Manual, so every write pauses |
| `auto: escalated` | Auto Mode stopped it and raised an alert; it did not run |
| `auto: denied` | Policy blocked it; no approval can run it |
On the card, choose **Approve**, **Approve and trust this command**, or **Decline**. Press Escape to decline. Only an [approver](/guide/approval) can decide, and the same card appears in the browser for a teammate who is one.
**Approve and trust this command** records the command in the workspace policy, the same Trust that chat's approval dialog offers. Under Auto, that command runs without a pause next time. Trusting needs a workspace owner or admin.
Approval keeps the exact connections selected when the write was requested. Adding a connection cannot widen a pending write; removing access or changing a selected identity blocks execution. If a write reports an unknown outcome, check its effects before requesting it again. Resuming the request does not automatically replay the command.
## Auto Mode in the terminal
Auto Mode is the workspace's one choice, and the terminal shows it rather than keeping its own. Run `/cloudthinker auto` to print the mode. Run `/cloudthinker auto on` or `/cloudthinker auto off` to switch the whole workspace, which needs the workspace-settings edit permission and is recorded like the switch in chat.
There is no per-session override and no flag to bypass approval from a laptop. Local commands on your machine are not gated by CloudThinker; pi runs them as you.
## Notifications
An Agent CLI session sends no approval notification by itself, because the card is already in front of you in the terminal and in the browser. That also covers approvals Anna raises in the session's `ct_ask` thread.
If you are not an approver, run `/cloudthinker notify` to send the approval request once to the workspace approvers on the channels they configured in [Notifications](/guide/notifications).
## Commands
| Command | What it does |
| ------------------------------ | --------------------------------------------------------------------------- |
| `/cloudthinker about` | Version, pi attribution, config directory, and session link |
| `/cloudthinker session` | File, message, and token counts for this session, ending in credits charged |
| `/cloudthinker auto [on\|off]` | Print or switch the workspace approval mode |
| `/cloudthinker notify` | Send the pending approval request to the workspace approvers once |
| `/open` | Open this session in the browser |
| `/cloud` | Show the workspace, connections, and mirror status |
pi's own commands, such as `/model`, `/fork`, and `/settings`, work as usual. `/share` and `/thinking` are removed.
## Session mirror
Every session is mirrored into the workspace as an **Agent CLI** conversation. Opening it in the browser shows a read-only viewer with the repository, branch, tool calls, and the linked Anna thread. Nobody can type into it, because the terminal that owns the session is the only writer. Any workspace member with the view permission can read it, and only the workspace owner can delete it.
The transcript stays on your machine as pi's session file. Resuming that file grows the same conversation, and a `/fork` opens a new one that records its parent.
## Credits
The footer shows the credits charged to this session, for example `◆ 1.75 credits`. The agent never prices a model in a currency. The footer adds a mirror status only when you have to act on it, such as `✕ mirror offline, 3 pending`.
## Related
Install the CloudThinker CLI and log in
Choose Manual or Auto for the workspace
Approvers and tool permissions
Set up the connections the Sandbox can use