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

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** — , 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 xCloud as the actor — never a bare verb like "Creating…" or "Polling…". Say xCloud 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)

| Sub-resource | Reference file | |---|---| | Backups (trigger, list, settings, status, count) | reference/backups.md | | Domains, redirections, web rules | reference/domains.md | | Cache (purge, purge-all, settings) | reference/cache.md | | SSH/SFTP config & keys | reference/ssh.md | | Site cron jobs | reference/cron-jobs.md | | Git deployment settings and manual deploys | reference/git.md |

Core endpoints

| Operation | Method + path | |---|---| | List sites | GET /sites | | Get site | GET /sites/{uuid} | | Status | GET /sites/{uuid}/status | | Events | GET /sites/{uuid}/events | | Deployment logs | GET /sites/{uuid}/deployment-logs | | Monitoring (+ history) | GET /sites/{uuid}/monitoring[/history] | | Access logs | GET /sites/{uuid}/access-logs | | Git deployment info | GET /sites/{uuid}/git | | Update Git deployment settings | PUT /sites/{uuid}/git | | Trigger Git deployment | POST /sites/{uuid}/git/deploy | | Snapshots | GET /sites/{uuid}/snapshots | | Staging sites | GET /sites/{uuid}/staging-sites | | Custom nginx / site scripts / IP access | GET /sites/{uuid}/{custom-nginx,site-scripts,ip-access} | | Rescue site | POST /sites/{uuid}/rescue |

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):

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

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xCloudDev
• Source: xCloudDev/xcloud-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.