# `am-cloud` CLI

`am-cloud` does two jobs: it runs a **worker** that joins the fleet, and it's an
**agent‑friendly control CLI** (`am-cloud platform …`) for orchestrating your AM
account from a terminal or an agentic CLI (e.g. hermes).

> **Agent‑friendly by design.** Every `platform` command emits **JSON by default**
> with a stable schema (`result`, `version`, payload) and meaningful **exit
> codes**; it's fully non‑interactive. Add `--human` for readable text, and run
> `am-cloud help-json` for machine‑readable help.

## Worker

```bash
# Install + start a worker (user service, no sudo)
am-cloud worker install --panel wss://automaintainer.intrane.fr/ws/worker --token <key>

# Install as a system service (needs root)
sudo am-cloud worker install --panel <url> --token <key> --system

# Start in the foreground (debugging)
am-cloud start --panel <url> --token <key>

# Remove the worker service
am-cloud worker uninstall
```

| Flag | Meaning |
|---|---|
| `--panel <url>` | Panel WebSocket URL (`wss://…/ws/worker`) |
| `--token <key>` | Your license key (scopes the worker to your account) |
| `--system` | Install system‑wide (root) instead of a user service |

## After install

- Keep a user service alive past logout: `sudo loginctl enable-linger "$USER"`.
- Configure a provider key on the host ([BYOK](/docs/byok-provider-keys)).
- Confirm readiness with the [Test button](/docs/verify-readiness).

## Tuning (environment)

Worker behaviour can be tuned via environment variables — see
[Environment variables](/docs/environment-variables).

## Platform (control) commands — orchestrate AM from a CLI

Point the control CLI at your account with two values (flags or env):

```bash
export AM_PANEL=wss://automaintainer.intrane.fr     # or --panel
export AM_API_KEY=amk_...                            # or --api-key
```

| Command | Purpose |
|---|---|
| `platform status` | Account + worker status |
| `platform repo list` | List repos |
| `platform repo add <url> --focus <text>` | Add a repo |
| `platform repo set <id> [flags]` | Configure a repo — any subset of `--focus --verify --objective --acceptance --team --clis --arch-context --name --spawn-interval --explore --auto-merge --reviews --issues --issue-scout --pr-watch --enabled` (bools disable with `=false`) |
| `platform repo run <id> [--wait]` | Trigger a run (`--wait` polls to completion) |
| `platform runs [--repo <id>]` | List recent runs |
| `platform explore <id>` | Kick a scout to propose work (Pro+) |
| `platform candidates <id>` | List proposed [explore](/docs/explore-mode) candidates |
| `platform candidate run\|reject <cid>` | Run or dismiss a candidate |
| `platform probe --cli <c> [--model <m>]` | Test a provider/model is [reachable](/docs/verify-readiness) |

Everything maps 1:1 to the [API](/docs/api), so an agent can drive the whole
product: configure a repo, trigger and **wait** for a verified run, read the
result, or work the explore queue.

### Example: orchestrate with an agentic CLI (hermes)

```bash
# 1. point at the account
export AM_PANEL=wss://automaintainer.intrane.fr AM_API_KEY=amk_...

# 2. make sure the model actually works before spending a run
am-cloud platform probe --cli pi --model opencode-go/deepseek-v4-flash
#   → {"probe":{"ok":true,"latency_ms":2598}}

# 3. configure the repo — gate, focus, team, and any other shipped setting
am-cloud platform repo set r-123 \
  --focus "add a unit test for the untested parseConfig()" \
  --verify "npm ci && npm run test:unit" \
  --arch-context "ESM only; tests use vitest" \
  --auto-merge --reviews

# 4. run it and WAIT for the verified result (JSON to stdout)
am-cloud platform repo run r-123 --wait
#   → {"run":{"status":"success","verify_status":"passed","pr_url":"https://github.com/…/pull/42"}}

# 5. or let AM propose its own work, then pick one
am-cloud platform explore r-123
am-cloud platform candidates r-123
am-cloud platform candidate run <candidate-id>
```

Because output is JSON with exit codes, an orchestrating agent can branch on
`result`, `status`, `verify_status`, and `probe.ok` without scraping text.

## Related

- [Add a worker](/docs/add-worker) · [Environment variables](/docs/environment-variables)
- [API reference](/docs/api) · [Verify readiness](/docs/verify-readiness)