DocumentationCommerceCommerce on Cloud Infrastructure Guide

Cloud CLI

Last update: Thu Sep 19 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin
  • Developer

The magento-cloud CLI tool enables developers and system administrators the ability to manage Cloud projects and environments, perform routines and run automation tasks locally. The magento-cloud CLI extends the features and functionality of the Cloud Console. After you install the magento-cloud CLI on your local workstation, you can use it to manage your Adobe Commerce on cloud infrastructure Starter and Pro integration environments.

NOTE
This is a local tool and cannot be installed on the Cloud environment (which is read-only) using this method. You can only install modules on the Cloud environment through the deployment workflow

To install the magento-cloud CLI:

  1. On your local workstation, change to the directory where you intend to clone the Cloud project and where the file system owner has write access.

  2. Install the magento-cloud CLI.

    code language-bash 
    curl -sS https://accounts.magento.cloud/cli/installer | php

  3. Add magento-cloud CLI to the bash profile.

    code language-bash 
    export PATH=$PATH:$HOME/.magento-cloud/bin

  4. Reload the updated bash profile.

    code language-bash 
    . ~/.bash_profile

  5. To initiate the CLI, call magento-cloud and enter your Cloud account credentials when prompted.

    code language-bash 
    magento-cloud
    code language-none 
    Welcome to Magento Cloud!
Please log in using your Magento Cloud account.
Your email address or username:

  6. Verify the magento-cloud command is in your path. The following example lists the available commands.

    code language-bash 
    magento-cloud list

Common commands

Adobe designed these commands to manage Cloud integration environments and recommends that you run the magento-cloud CLI from a project directory so you can omit the -p <project-ID> parameter.

The following list of commonly used magento-cloud CLI commands includes required options only. You can use the --help option with any command to see more information.

Command
Description
magento-cloud login
Log in to the project.
magento-cloud list
List the available commands for CLI tool.
magento-cloud environment:list
List the environments in the current project.
magento-cloud environment:checkout
Check out an existing environment.
magento-cloud environment:merge -e
Merge changes in this environment with its parent.
magento-cloud variables
List variables in this environment.
magento-cloud ssh
Use SSH to connect to the remote environment.
magento-cloud url
Open the Adobe Commerce storefront in a browser.
magento-cloud web
Open the Cloud Console.

Environment commands

The environment name is different from the environment ID only if you use spaces or capital letters in the environment name. An environment ID consists of all lowercase letters, numbers, and allowed symbols. Capital letters in an environment name are converted to lowercase in the ID; spaces in an environment name are converted to dashes.

An environment name cannot include characters reserved for your Linux shell or for regular expressions. Forbidden characters include curly braces ({ }), parentheses, asterisk (*), angle brackets (< >), ampersand (&), percent (%), and other characters.

The magento-cloud environment:list command displays environment hierarchies, whereas git branch does not. If you have any nested environments, use the following:

magento-cloud environment:list

Redeploy the environment

Trigger a redeployment without using a push. Verify and confirm the environment to redeploy. Do not use redeploy if there is a build in a pending state.

magento-cloud environment:redeploy

Sample response:

Are you sure you want to redeploy the environment <environment-name>? [Y/n]
WARNING
The deployment process begins when you perform a merge, push, or synchronization of your environment, or when you trigger a manual redeployment, during which the Commerce application is in maintenance mode. For a Production environment, Adobe recommends completing this work during off-peak hours to avoid service disruptions.

Git commands

You may notice that some of these commands are similar to Git commands. The magento-cloud commands directly connect to the Git-based Cloud project with additional features. If you create a branch without using the magento-cloud CLI, it is not “activated” and does not automatically build when you push changes to the remote environment. The magento-cloud CLI command includes activation.

To create a branch, use the magento-cloud command so the branch is activated.

magento-cloud environment:branch <new-name> <parent-branch>

For branch status:

  • Use the magento-cloud env command to view a list of the environment branches and their status: active or inactive.
  • Use the magento-cloud environment:activate command to activate an environment branch.

Push an empty Git commit to trigger a deployment. For example:

git commit --allow-empty -m "redeploy" && git push <branch-name>

Some actions, such as adding a user, do not result in deployment.

Create an environment branch

The following steps demonstrate using the CLI and Git commands interchangeably to manage your local environment:

  1. On your local workstation, change to your project directory.

  2. Switch to the file system owner.

  3. Log in to your project.

    code language-bash 
    magento-cloud login

  4. List your projects.

    code language-bash 
    magento-cloud project:list

  5. List environments in the project. Every environment includes an active Git branch that contains your code, database, environment variables, configurations, and services.

    code language-bash 
    magento-cloud environment:list
    note note
    NOTE
    It is important to use the magento-cloud environment:list command because it displays environment hierarchies, whereas the git branch command does not.

  6. Fetch origin branches to get the latest code.

    code language-bash 
    git fetch origin

  7. Checkout, or switch to, a specific branch and environment.

    code language-bash 
    magento-cloud environment:checkout <environment-ID>

    Git commands only checkout the Git branch. The magento-cloud checkout command checks out the branch and switches to the active environment.

    note tip
    TIP
    You can create an environment branch using the magento-cloud environment:branch <environment-name> <parent-environment-ID> command syntax. It may take some additional time to create and activate an environment branch.

  8. Use the environment ID to pull any updated code to your local. This is not necessary if the environment branch is new.

    code language-bash 
    git pull origin <environment-ID>

  9. (Optional) Create a snapshot of the environment as a backup.

    code language-bash 
    magento-cloud snapshot:create -e <environment-ID>

Update the CLI

The magento-cloud CLI checks for available updates when you log in, but you can check for updates using the self:update command. If there is an update available, follow the instructions to update the CLI.

If your magento-cloud CLI is up to date, you see the following response:

magento-cloud update

Checking for Magento Cloud CLI updates (current version: X.XX.X)
No updates found
recommendation-more-help
05f2f56e-ac5d-4931-8cdb-764e60e16f26