Cloud CLI
The magento-cloud
CLI tool enables developers and system administrators the ability to manage Cloud projects and environments, perform routines and run automation tasks. 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.
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.code language-bash curl -sS https://accounts.magento.cloud/cli/installer | php
-
Add
magento-cloud
CLI to the bash profile.code language-bash export PATH=$PATH:$HOME/.magento-cloud/bin
-
Reload the updated bash profile.
code language-bash . ~/.bash_profile
-
To initiate the CLI, call
magento-cloud
and enter your Cloud account credentials when prompted.code language-bash magento-cloud
code language-terminal 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.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.
magento-cloud login
magento-cloud list
magento-cloud environment:list
magento-cloud environment:checkout
magento-cloud environment:merge -e
magento-cloud variables
magento-cloud ssh
magento-cloud url
magento-cloud web
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]
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:
-
On your local workstation, change to your project directory.
-
Switch to the file system owner.
-
Log in to your project.
code language-bash magento-cloud login
-
List your projects.
code language-bash 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.
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 thegit branch
command does not. -
Fetch origin branches to get the latest code.
code language-bash git fetch origin
-
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. -
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>
-
(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