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.
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:
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.
Install the magento-cloud
CLI.
curl -sS https://accounts.magento.cloud/cli/installer | php
Add magento-cloud
CLI to the bash profile.
export PATH=$PATH:$HOME/.magento-cloud/bin
Reload the updated bash profile.
. ~/.bash_profile
To initiate the CLI, call magento-cloud
and enter your Cloud account credentials when prompted.
magento-cloud
Welcome to Magento Cloud!
Please log in using your Magento Cloud account.
Your email address or username:
Verify the magento-cloud
command is in your path. The following example lists the available commands.
magento-cloud list
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. |
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
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]
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.
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:
magento-cloud env
command to view a list of the environment branches and their status: active or inactive.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.
The following steps demonstrate using the CLI and Git commands interchangeably to manage your local environment:
On your local workstation, change to your project directory.
Switch to the file system owner.
Log in to your project.
magento-cloud login
List your projects.
magento-cloud project:list
List environments in the project. Every environment includes an active Git branch that contains your code, database, environment variables, configurations, and services.
magento-cloud environment:list
It is important to use the magento-cloud environment:list
command because it displays environment hierarchies, whereas the git branch
command does not.
Fetch origin branches to get the latest code.
git fetch origin
Checkout, or switch to, a specific branch and environment.
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.
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.
Use the environment ID to pull any updated code to your local. This is not necessary if the environment branch is new.
git pull origin <environment-ID>
(Optional) Create a snapshot of the environment as a backup.
magento-cloud snapshot:create -e <environment-ID>
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