Sites

xCloud Sites

Owns site lifecycle and delivery. Read the shared layer first for auth, base URL, envelope, pagination, and rate limits:

• ${CLAUDE_PLUGIN_ROOT}/reference/auth.md
• ${CLAUDE_PLUGIN_ROOT}/reference/conventions.md
• ${CLAUDE_PLUGIN_ROOT}/reference/mcp.md — prefer mcp__xcloud__sites_* tools when connected (e.g. sites_index, sites_show, sites_status, sites_rescue, sites_destroy); the $XC calls below are the REST fallback.

XC="${CLAUDE_PLUGIN_ROOT}/scripts/xcloud.sh"

Scopes: reads need read:sites, writes need write:sites.

Response format

Brand every user-facing reply (see reference/conventions.md → Response format): open with ☁️ **xCloud · Sites** — <site domain>, give the trimmed result, and close with a _via xcloud:sites_ line.

Narrate each call (see Progress narration): before every $XC call print one line of what xCloud is doing, e.g. ☁️ xCloud is fetching site \`…; the first call of a task opens with ☁️ xCloud is starting a session…. **Every progress line and every action sentence must start with xCloudas the actor — never a bare verb like "Creating…" or "Polling…". SayxCloud is creating…`.**

On the first xcloud reply in a conversation, lead with the xCloud startup banner (see reference/conventions.md → Startup banner) in a fenced code block — once per conversation.

Sub-resources (load on demand)

Core endpoints

Not here: SSL → xcloud:ssl; WordPress/vulns/pagespeed → xcloud:wordpress; servers → xcloud:servers.

Common reads

Find a site by domain (resolve its UUID first):

"$XC" GET "/sites?search=example.com&per_page=20" \
  | jq '(.data.items // .data.data // []) | map({uuid, name, domain: .domain_name, status, type})'

Status + recent events (the go-to triage pair):

SITE_UUID='replace-me'
"$XC" GET "/sites/$SITE_UUID/status" | jq '.data'
"$XC" GET "/sites/$SITE_UUID/events" | jq '(.data.items // .data) | .[0:10]'

Writes

Rescue a broken site (all flags optional booleans; pick the repairs you need — supported options depend on site type: repair_node, repair_pm2, and repair_openclaw exist for Node/OpenClaw sites, reinstall_php for PHP sites):

"$XC" POST "/sites/$SITE_UUID/rescue" '{
  "isolate_user": true,
  "regenerate_nginx": true,
  "restart_nginx": true,
  "directory_permissions": true,
  "reinstall_php": false
}' | jq '.message'

Delete a site — destructive and irreversible; never call without explicit user confirmation naming the exact domain. The delete_* flags choose what is removed alongside the record; deletion is async (status → deleting, staging sites are removed too):

"$XC" DELETE "/sites/$SITE_UUID" '{
  "delete_files": true,
  "delete_database": true,
  "delete_user": true,
  "delete_local_backups": false,
  "delete_dns_record": false
}' | jq '.message'
# poll: GET /sites/{uuid}/status until the site is gone

Pitfalls

• Many list endpoints differ in pagination shape — use (.data.items // .data.data // []).
• Writes are async; confirm via GET /sites/{uuid}/events.
• A 502 with status still provisioned is usually a missing site OS user — pull /sites/{uuid}/ssh (site_user) and the server tasks to confirm.
• Site deletion requires the site:delete team permission; sites tied to their server's lifecycle (e.g. OpenClaw) cannot be deleted independently.
• Monitoring history is a paid feature — expect 403 on free plans.