mcloud-logs

★ 195

by medusajs · part of medusajs/medusa-agent-skills

Execute mcloud logs to fetch and stream runtime logs for Cloud environments. Use when reading backend or storefront logs, filtering by time range, searching…

🔥🔥🔥✓ VerifiedFreeQuick setup

#git

🧩 One of 7 skills in the medusajs/medusa-agent-skills package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

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.