Help

deployments Command - Medusa Cloud CLI Reference

In this guide, you'll learn how to inspect Cloud deployments and their build logs using the CLI.

deployments list#

List recent deployments for a project. By default, the command returns the 20 most recent deployments across all environments in the project, ordered by creation time (newest first).

Options#

Option	Description	Required	Default
`-o <id>`, `--organization <id>`	The ID of the organization that the project belongs to.	Yes	Falls back to the organization in the active context, if set.
`-p <id-or-handle>`, `--project <id-or-handle>`	The ID or handle of the project to list deployments from.	Yes	Falls back to the project in the active context, if set.
`-e <handle>`, `--environment <handle>`	Filter deployments to a specific environment by handle. If not provided, and not set in the active context, deployments from all environments in the project will be returned.	No	Falls back to the environment in the active context, if set.
`--environment-type <type>`	Filter deployments by environment type. One of `production`, `long-lived`, or `preview`. If you set the environment using its flag or in the active context, this filter is applied to the specified environment.	No	-
`--commit <sha>`	Filter deployments by Git commit SHA. Accepts a full SHA or a prefix.	No	-
`--limit <number>`	Maximum number of deployments to return. Minimum: `1`, maximum: `200`.	No	`20`
`--offset <number>`	The number of deployments to skip before retrieving the deployments. Useful for pagination.	No	`0`
`--json`	Print the result as JSON instead of formatted text.	No	`false`

deployments get#

Retrieve a single deployment by its ID. Returns the deployment's status, commit details, environment, and timestamps.

Note: This only retrieves the deployment's details. If you want to view its build logs, use mcloud deployments build-logs instead.

Arguments#

Option	Description	Required
`deployment`	The ID of the deployment to retrieve.	Yes

Options#

Option	Description	Required	Default
`-o <id>`, `--organization <id>`	The ID of the organization that the project belongs to.	Yes	Falls back to the organization in the active context, if set.
`-p <id-or-handle>`, `--project <id-or-handle>`	The ID or handle of the project that the deployment belongs to.	Yes	Falls back to the project in the active context, if set.
`--json`	Print the result as JSON instead of formatted text.	No	`false`

deployments build-logs#

Fetch the build logs for a deployment. Use this to debug build failures or to inspect the build output for a specific deployment.

Tip: To fetch the runtime logs for a deployment after it is live, use mcloud logs --deployment <id> instead.

Arguments#

Option	Description	Required
`deployment`	The ID of the deployment to retrieve the build logs for.	Yes

Options#

Option	Description	Required	Default
`-o <id>`, `--organization <id>`	The ID of the organization that the project belongs to.	Yes	Falls back to the organization in the active context, if set.
`-p <id-or-handle>`, `--project <id-or-handle>`	The ID or handle of the project that the deployment belongs to.	Yes	Falls back to the project in the active context, if set.
`--type <backend\|storefront>`	Which build log stream to read.	No	`backend`
`--json`	Print the result as JSON instead of formatted text.	No	`false`

Investigate a Failed Deployment#

When a deployment fails, combine deployments list, deployments get, and deployments build-logs to find the deployment, inspect its status, and read the build output.

Check Build Logs for a Failed Deployment#

If the build itself failed (status build-failed), use deployments build-logs to read the build output:

Terminal
❯# Assuming context is set with mcloud use. Otherwise, add the necessary flags to each command as shown in previous sections.❯
❯# Find the most recent build-failed deployment and store its ID in a variable❯DEPLOYMENT_ID=$(❯  mcloud deployments list --json \❯    | jq -r '.[] | select(.backend_status == "build-failed") | .id' \❯    | head -n 1❯)❯
❯# Get deployment details❯mcloud deployments get "$DEPLOYMENT_ID"❯
❯# Fetch its backend build logs❯mcloud deployments build-logs "$DEPLOYMENT_ID"❯
❯# Or fetch the storefront build logs❯mcloud deployments build-logs "$DEPLOYMENT_ID" --type storefront

Check Runtime Logs for a Failed Deployment#

If the build succeeded but the rollout failed (status deployment-failed), the build logs won't show the cause. Use mcloud logs with --deployment to read the runtime logs for that specific deployment:

Terminal
❯# Assuming context is set with mcloud use. Otherwise, add the necessary flags to each command as shown in previous sections.❯
❯# Find the most recent deployment-failed deployment and store its ID in a variable❯DEPLOYMENT_ID=$(❯  mcloud deployments list --json \❯    | jq -r '.[] | select(.backend_status == "deployment-failed") | .id' \❯    | head -n 1❯)❯
❯# Get deployment details❯mcloud deployments get "$DEPLOYMENT_ID"❯
❯# Fetch the runtime logs scoped to that deployment❯mcloud logs --deployment "$DEPLOYMENT_ID" --limit 1000❯
❯# Or filter to error-level lines only❯mcloud logs --deployment "$DEPLOYMENT_ID" --search error --limit 1000

To redeploy after fixing the underlying issue, use mcloud environments redeploy. To start a fresh build from the tracked branch, use mcloud environments trigger-build.

Backend and Storefront Statuses#

When retrieving the details of a deployment, you can see the backend and storefront statuses through the backend_status and storefront_status fields when using the --json flag.

Possible backend and storefront statuses are:

Status	Description
`created`	The deployment record exists but the build has not started yet.
`building`	The build is running. Use `mcloud deployments build-logs` to follow the output.
`built`	The build finished successfully but the deployment to the environment hasn't started yet.
`deploying`	The built artifact is being rolled out to the environment.
`deployed`	The deployment is live and serving traffic. The current active deployment for an environment is marked `(active)` in the formatted table. You can get the active deployment logs using `mcloud logs --deployment <id>`.
`build-failed`	The build step failed before any code was deployed. Use `mcloud deployments build-logs` to find the build error.
`deployment-failed`	The build succeeded but the rollout to the environment failed. Use `mcloud logs` to fetch the logs for the affected deployment.
`timed-out`	The build or deployment exceeded the maximum allowed duration and was terminated. This status applies to backend deployments only.
`canceled`	The build or deployment was canceled, usually because a newer deployment superseded it.
`idle`	The deployment is no longer the active one for its environment. Idle deployments can be re-activated with `mcloud environments redeploy`.

Was this guide helpful?