/mcloud-logs

name: mcloud-logs
description: Execute mcloud logs to fetch and stream runtime logs for Cloud environments. Use when reading backend or storefront logs, filtering by time range, searching for errors, or scoping logs to a specific deployment.
allowed-tools: Bash(mcloud logs*), Bash(jq*)

Cloud CLI: Logs Command

Execute `mcloud logs` to fetch runtime logs for a Cloud environment's backend or storefront.

Constraints

• `--follow` and `--json` are incompatible. For programmatic log analysis, use bounded time windows with `--from`/`--to` and `--json`.
• `--follow` streams until interrupted with `Ctrl+C` — do not use in scripts or pipelines.
• Default retrieves the last 500 log lines from the past 15 minutes.

Command

mcloud logs \
  --organization <org-id> \
  --project <project-id-or-handle> \
  --environment <environment-handle> \
  [options]

Options

| Option | Description | Default | |--------|-------------|---------| | `-o/--organization <id>` | Organization ID | Active context | | `-p/--project <id-or-handle>` | Project ID or handle | Active context | | `-e/--environment <handle>` | Environment handle | Active context | | `-f/--follow` | Stream logs continuously (incompatible with `--json`) | `false` | | `--limit <1-5000>` | Max log lines (non-follow mode only) | `500` | | `--from <ISO8601>` | Start of time range (e.g. `2026-04-22T10:00:00Z`) | 15 minutes ago | | `--to <ISO8601>` | End of time range; if >15 min ago, must also pass `--from` | now | | `--search <string>` | Filter by substring (same as dashboard search bar) | — | | `--deployment <id>` | Filter by deployment or build ID | — | | `--source <string>` | Filter by source (repeatable) | — | | `--metadata <key=value>` | Filter by metadata field (repeatable; same key merges values) | — | | `--type <backend\|storefront>` | Log stream to query | `backend` | | `--json` | Output as JSON (incompatible with `--follow`) | `false` |

Examples

# Basic log fetch (last 500 lines, last 15 min)
mcloud logs --json

# Search for errors
mcloud logs --search error --limit 1000 --json

# Filter for HTTP 500 errors via metadata
mcloud logs --metadata status=500 --limit 1000 --json

# Logs for a specific deployment (build or deployment ID)
mcloud logs --deployment bld_01ABC123 --json

# Structured output for agent analysis
mcloud logs --search error --json | jq '.[] | {timestamp, source, message}'

# Storefront logs
mcloud logs --type storefront --json

# Stream live logs (human-readable, not for scripts)
mcloud logs --follow

# Logs within a specific time range
mcloud logs --from 2026-04-22T10:00:00Z --to 2026-04-22T11:00:00Z --limit 1000 --json

# Logs from a time until now
mcloud logs --from 2026-04-22T10:00:00Z --json

# Multiple source filters
mcloud logs --source api --source worker --json

# Multiple metadata filters (HTTP 4xx and 5xx)
mcloud logs --metadata status=400 --metadata status=500 --limit 500 --json

Time Range Notes

• Default window is the past 15 minutes.
• Pass `--from` without `--to` to fetch from a time until now.
• Pass `--to` without `--from` only if `--to` is within the last 15 minutes; otherwise also pass `--from`.
• Both `--from` and `--to` accept ISO 8601 timestamps.