environments Command - Medusa Cloud CLI Reference

In this guide, you'll learn how to manage your Cloud environments using the CLI.

environments list#

List all environments in a project.

Options#

environments get#

Retrieve a single environment by its handle. This is useful if you want to retrieve the environment's details, such as its status or tracked branch.

Returns the following information:

Arguments#

Options#

environments create#

Create a new long-lived environment for a project. You must already have a branch in your repository to track. The environment will be deployed and updated with every push to the tracked branch.

Options#

environments delete#

Delete an environment by its handle.

Arguments#

Options#

environments redeploy#

Redeploy an environment using its current active deployment build. This is useful when you want to roll back to a previous deployment or re-run the active deployment without triggering a new build.

The environment must already have an active deployment. If it doesn't, run mcloud environments trigger-build first to create one.

Arguments#

Options#

environments trigger-build#

Start a new build for an environment from its tracked branch. This is the equivalent of pushing a commit to the tracked branch but without requiring a Git push.

Arguments#

Options#

Find Environment Handles#

Commands that operate on environments require an environment handle. You can either:

• Use the interactive selector in mcloud use to set an active environment for the current context. Once set, you can omit the --environment flag from all subsequent commands;
• Or use environments list --json to get machine-readable environment data. Pipe the output to jq to extract handles for use in subsequent commands. This is useful if you want to set the active environment through an AI agent, script, or CI/CD pipeline.

For example, to set the first environment in the list as the active environment:

To set an environment by name as the active environment:

Once set, you can omit the --environment flag from all subsequent commands.

Manage Environments in a CI/CD Pipeline#

You can provision and tear down environments automatically as branches are created and deleted in your repository. This is useful for staging environments that mirror production, or for short-lived feature-branch environments used for testing and review.

For example, the following GitHub Actions workflow:

• Creates a Cloud environment when a branch is pushed
• Deletes it when the branch is removed.

.github/workflows/cloud-environments.yml
1name: Cloud Environments2
3on:4  create:5    branches-ignore:6      - main7  delete:8    branches-ignore:9      - main10
11env:12  MCLOUD_TOKEN: ${{ secrets.MCLOUD_TOKEN }}13
14jobs:15  create-environment:16    if: github.event_name == 'create' && github.event.ref_type == 'branch'17    runs-on: ubuntu-latest18    steps:19      - name: Install the Cloud CLI20        run: npm install -g @medusajs/mcloud21
22      - name: Create Cloud environment23        run: |24          mcloud environments create \25            --organization org_123 \26            --project proj_123 \27            --name "${{ github.event.ref }}" \28            --branch "${{ github.event.ref }}" \29            --custom-subdomain "my-store-${{ github.event.ref }}"30
31  delete-environment:32    if: github.event_name == 'delete' && github.event.ref_type == 'branch'33    runs-on: ubuntu-latest34    steps:35      - name: Install the Cloud CLI36        run: npm install -g @medusajs/mcloud37
38      - name: Delete Cloud environment39        run: |40          mcloud environments delete "${{ github.event.ref }}" \41            --organization org_123 \42            --project proj_123 \43            --yes

The create-environment job runs mcloud environments create with the branch name as both the environment name and tracked branch. The delete-environment job runs mcloud environments delete with --yes to skip the confirmation prompt, which is required for non-interactive environments like CI runners.