using-ao

AO Cloud CLI Catalog

ao inside a cloud sandbox is a thin client over the AO control plane. It is a

different, smaller CLI than the desktop ao: there is no ao session,

ao project, ao status, ao preview, or ao browser here. Every command is

ao help for the authoritative list.

| Command | What it does | Who can run it | Details |

|---|---|---|---|

| spawn | Create a worker session in its own fresh sandbox | Orchestrators only | [commands/orchestration.md](commands/orchestration.md) |

| list (ls, status) | List the workers this orchestrator spawned, with branch, status, and PR facts | Orchestrators only | [commands/orchestration.md](commands/orchestration.md) |

| send | Send a message into a worker's conversation | Orchestrators only | [commands/orchestration.md](commands/orchestration.md) |

| kill (delete, rm) | Terminate a worker session and its sandbox | Orchestrators only | [commands/orchestration.md](commands/orchestration.md) |

| report | Send a message to the orchestrator that spawned this session | Workers with an orchestrator parent | [commands/orchestration.md](commands/orchestration.md) |

| claim-pr | Attach an existing pull request to this session | Any session | [commands/pull-requests.md](commands/pull-requests.md) |

Conventions

• ao list --json prints machine-readable output; --all includes terminated

workers (hidden by default).

• --agent is an alias for --harness on ao spawn.
• Session ids are UUIDs shown by ao list.
• Every session runs in its own isolated sandbox. Never try to reach another

session's sandbox directly (no ssh, no shared filesystem); the ao commands

above are the only channel between sessions.

• A send to a worker whose sandbox is still provisioning is queued by the

control plane and delivered when the worker's agent is ready — check

runtimeConnected in ao list --json to see whether a worker is live.

• Spawning and messaging are idempotent server-side; a command that prints a

success line has been durably accepted even if the effect is not visible yet.

• Pull requests and reviews are handled through socket helpers described in

[commands/pull-requests.md](commands/pull-requests.md), not through ao.