`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

# 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).
Confirm readiness with the Test button.

Tuning (environment)

Worker behaviour can be tuned via environment variables — see Environment variables.

Platform (control) commands — orchestrate AM from a CLI

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

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 candidates
`platform candidate run\|reject <cid>`	Run or dismiss a candidate
`platform probe --cli <c> [--model <m>]`	Test a provider/model is reachable

Everything maps 1:1 to the 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)

# 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.