mcloud-deployments - SKILL.md Agent Skill

name: mcloud-deployments description: Execute mcloud deployments commands to list deployments, retrieve deployment details, and fetch build logs. Use when listing deployments, checking deployment status, or reading build output for debugging build failures. allowed-tools: Bash(mcloud deployments), Bash(jq)

Cloud CLI: Deployments Commands

Execute mcloud deployments commands to inspect deployments and their build logs.

Constraints

Always pass --json when parsing output — plaintext format may change.
Always confirm context (mcloud whoami --json) before running commands if org/project are not already known.
Use --deployment IDs in the format depl_* or build IDs; build IDs resolve to their latest deployment automatically.

Commands

deployments list

List recent deployments for a project (default: 20 most recent across all environments).

mcloud deployments list --organization <org-id> --project <project-id-or-handle> --json

Options:

-o/--organization <id> — Organization ID (falls back to active context)
-p/--project <id-or-handle> — Project ID or handle (falls back to active context)
-e/--environment <handle> — Filter by environment handle
--environment-type <production|long-lived|preview> — Filter by environment type
--commit <sha> — Filter by Git commit SHA (full or prefix)
--limit <1-200> — Max results (default: 20)
--offset <number> — Pagination offset (default: 0)
--json — Output as JSON

deployments get

Retrieve a single deployment's details by ID.

mcloud deployments get <deployment-id> --organization <org-id> --project <project-id-or-handle> --json

Arguments:

deployment — Deployment ID (required)

Options:

-o/--organization <id>, -p/--project <id-or-handle>, --json

deployments build-logs

Fetch build logs for a deployment. Use this to debug build-failed status.

mcloud deployments build-logs <deployment-id> --organization <org-id> --project <project-id-or-handle>

Arguments:

deployment — Deployment ID (required)

Options:

-o/--organization <id>, -p/--project <id-or-handle>
--type <backend|storefront> — Which build log stream to read (default: backend)
--json — Output as JSON

Deployment Statuses

Status	Meaning
`created`	Build not started yet
`building`	Build running
`built`	Build succeeded, awaiting rollout
`deploying`	Rolling out to environment
`deployed`	Live and serving traffic
`build-failed`	Build step failed — read `build-logs`
`deployment-failed`	Build succeeded, runtime crashed — read `mcloud logs`
`timed-out`	Exceeded time budget (backend only)
`canceled`	Superseded by a newer deployment
`idle`	No longer the active deployment

Examples

# List all deployments (with active context set)
mcloud deployments list --json

# Find most recent build-failed deployment
mcloud deployments list --json \
  | jq -r '[.[] | select(.backend_status == "build-failed")][0].id'

# Get deployment details
mcloud deployments get bld_01ABC123 --json

# Read backend build logs
mcloud deployments build-logs bld_01ABC123

# Read storefront build logs
mcloud deployments build-logs bld_01ABC123 --type storefront

# Filter deployments by commit SHA
mcloud deployments list --commit a1b2c3d --json | jq '.'

# Get deployments for a specific environment
mcloud deployments list --environment production --json