# mcloud-logs

Fetches and streams runtime logs from Medusa Cloud backend and storefront environments, with filters for time range and deployment.

Skill by Medusa. Category: Shipping and ops.

## Install

Project (for this project only):

```sh
npx skills add medusajs/medusa-agent-skills --skill mcloud-logs
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add medusajs/medusa-agent-skills --skill mcloud-logs -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.
- Runs shell commands: Its steps run shell commands in your terminal.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Warn

Installs: 1214. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/medusajs/medusa-agent-skills/mcloud-logs)

## Source

[Open the source](https://github.com/medusajs/medusa-agent-skills/tree/HEAD/plugins/medusa-cloud/skills/mcloud-logs). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
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

```bash
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

```bash
# 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.
````

- Previous: [mcloud-projects](https://syn4pse.dev/terminal/medusa-mcloud-projects.md)
- Next: [mcloud-organizations](https://syn4pse.dev/terminal/medusa-mcloud-organizations.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
