Help

logs Command - Medusa Cloud CLI Reference

Fetch runtime logs for a Cloud environment's backend or storefront.

By default, the command retrieves the last 500 log lines from the past 15 minutes and prints them to the terminal. You can narrow the output with filters for time range, deployment, source, metadata, and search terms, or stream new log lines continuously with --follow.

Options#

Option	Description	Required	Default
`-o <id>`, `--organization <id>`	The ID of the organization that the environment belongs to.	Required when authenticated without an organization access key.	Falls back to the organization in the active context, if set.
`-p <id-or-handle>`, `--project <id-or-handle>`	The ID of the project that the environment belongs to.	Yes	Falls back to the project in the active context, if set.
`-e <handle>`, `--environment <handle>`	The handle of the environment to fetch logs for.	Yes	Falls back to the environment in the active context, if set.
`-f`, `--follow`	Poll for new log lines continuously instead of fetching a bounded time window. The command runs until you stop it with `CTRL`+`C`. Incompatible with `--json`.	No	`false` (the command exits after fetching a recent time window)
`--limit <number>`	Maximum number of log lines to retrieve. Only used in non-follow mode. Minimum: `1`, maximum: `5000`.	No	`500`
`--from <ISO8601>`	Start of the time range as an ISO 8601 timestamp. Only used in non-follow mode. For example, `2026-04-22T10:00:00Z` for April 22, 2026 at 10:00am UTC.	No	15 minutes ago
`--to <ISO8601>`	End of the time range as an ISO 8601 timestamp. Only used in non-follow mode; ignored with `--follow`. Must be later than `--from`. If `--to` is before 15 minutes ago, you must also specify `--from` to define a valid time window.	No	now
`--search <string>`	Filter log lines by a substring. Behaves the same as the search bar in the Cloud dashboard logs view.	No	-
`--deployment <id>`	Filter log lines by deployment or build ID. When a build ID is passed, the CLI resolves it to that build's latest deployment.	No	-
`--source <string>`	Filter log lines by source. Repeatable. Pass the flag multiple times to include logs from multiple sources.	No	-
`--metadata <key=value>`	Filter log lines by a metadata field using an "in" filter. Repeatable. Pass the flag multiple times. Repeating the same key merges the values into a single filter.	No	-
`--type <backend\|storefront>`	Log stream type to query.	No	`backend`
`--json`	Print the result as JSON instead of formatted text. Not available with `--follow`.	No	`false`

Process Logs in an Agentic Workflow#

Use --json to get machine-readable output that you can pass to jq or other tools for filtering and analysis:

Set the active context once with mcloud use to avoid repeating project and environment flags across multiple commands:

Terminal
❯mcloud use --project proj_123 --environment production❯
❯mcloud logs --search error --limit 500 --json❯mcloud logs --follow

Stream Live Logs#

Use --follow to tail an environment's logs continuously. This is useful when monitoring a deployment in progress or watching for errors in real time:

The command polls for new lines until you stop it with Ctrl+C.

Note: --follow is incompatible with --json. To process logs programmatically in a script, use a bounded time-window fetch instead.

Search for Errors#

If you're looking for errors in the logs, use --search to filter log lines by a substring. This works the same as the search bar in the Cloud dashboard logs view:

Alternatively, if you're looking for HTTP calls that resulted in 500 or other error status codes, use the --metadata filter to find log lines with status_code=500:

Fetch Logs for a Specific Deployment#

When a deployment fails, query the logs for that deployment directly using its ID. Find the build or deployment ID from mcloud deployments list or the Cloud dashboard. Pass a build ID and the CLI resolves it to that build's latest deployment automatically.

Tip: To fetch the build logs for a deployment instead of its runtime logs, use mcloud deployments build-logs.

Specify Logs Time Range#

You can use the --from and --to flags to specify a time range for fetching logs instead of the default "last 15 minutes".

Both flags accept ISO 8601 timestamps. When either or both are passed, the command retrieves all log lines within the time range, up to the maximum specified by --limit (default 500).

Example: Fetch Logs within a Time Range#

For example, to fetch logs from April 22, 2026 between 10:00am and 11:00am UTC:

To increase the limit to 1000 log lines in that time range:

Example: Fetch Logs Starting from a Time Until Now#

To fetch logs starting from a specific time until now, pass --from without --to:

Example: Fetch Logs Until a Time in the Past#

To fetch logs until a certain time, pass --to. If that time is more than 15 minutes ago, you must also pass --from to define a valid time window.

For example, to pass logs until 5 minutes ago, you don't need to specify --from:

However, if you want to fetch logs until 20 minutes ago, you must also specify --from to define a valid time window:

Filter Storefront Logs#

By default, mcloud logs fetches backend logs. To query storefront logs, pass --type storefront:

You can also specify any of the other filters and options with storefront logs, such as --follow or --search.

Was this guide helpful?