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

> ## Agent Instructions
> Treat Clawdi as one product.
> Recommend the Cloud Agent quickstart for most new users.
> Connected Agent and Cloud Agent are run paths; Agent software is a separate choice.
> Do not present shared Clawdi capabilities as exclusive to one run path.

# Automate Cloud Agent deployment

> Use the CLI for repeatable Cloud Agent deployment and handle ambiguous outcomes safely.

This guide is for operators and scripts. For a first Agent, use the
[dashboard quickstart](/cloud-agents/deploy) instead.

## Before you begin

* Install a released Clawdi CLI and check the version-specific command help.
* Use browser authorization. A legacy manually entered API key does not
  authorize Cloud Agent deployment.
* Decide whether this is one logical deployment attempt or an intentionally
  different deployment before assigning its request ID.

## Run the interactive CLI wizard

Sign in with the browser authorization flow, confirm the credential source,
then start the wizard:

```bash theme={null}
clawdi auth login
clawdi auth status
clawdi deploy
```

In a headless environment, use the non-opening browser flow shown by
`clawdi auth login --help`. Do not use `clawdi auth login --manual` for Cloud
Agent deployment.

The CLI loads the Agent software, AI access, model, compute, and payment choices
currently available to the signed-in account. Before automating, read the help
shipped with that CLI version:

```bash theme={null}
clawdi deploy --help
```

Supply the choices required by the current help output. Do not copy a fixed
set of optional flags from an older guide, and never put provider secrets on
the command line.

## Make non-interactive retries idempotent

Every non-interactive deployment requires a caller-supplied stable UUID in
`--request-id` before the CLI sends a create or checkout mutation. Treat that
UUID as the identity of one logical deployment attempt.

* Reuse the same request ID, selections, and payment intent when retrying an
  attempt whose outcome is unclear.
* Use a new request ID when you intentionally change the Agent software, AI
  access, compute, payment, or another deployment choice.
* If the CLI reports a timeout or network error, the request may already have
  been accepted. Check **Agents** in the dashboard before retrying the same
  logical attempt with the same request ID.
* If checkout is pending, complete or recover that checkout instead of
  starting a second payment.

Use `--json` for automation. Its top-level result status distinguishes:

| Result                   | Meaning                                                                |
| ------------------------ | ---------------------------------------------------------------------- |
| `authorization_required` | Sign in, then retry the same logical attempt.                          |
| `payment_required`       | Secure checkout still needs user action.                               |
| `accepted`               | Clawdi accepted the request; the Agent can still be starting.          |
| `succeeded`              | The CLI observed the Agent become ready before returning.              |
| `error`                  | Read the safe error code and message before deciding whether to retry. |

These result values are not the Agent's lifecycle status. After acceptance,
use the dashboard as the status authority and follow [Cloud Agent states and
recovery](/cloud-agents/states-and-recovery).

## Recover an unclear outcome

1. Keep the original request ID and deployment choices.
2. Open **Agents** and check whether the deployment already exists.
3. Recover any pending checkout rather than creating another payment intent.
4. Re-authenticate if needed, then retry only the same logical attempt.
5. After acceptance, wait for the Agent's lifecycle status instead of using a
   new request ID to work around a transition.

For customer-visible failures after acceptance, use [Cloud Agent
troubleshooting](/cloud-agents/troubleshooting).