---name: mcloud-logsdescription: 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.