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]
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.
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
NOTE
It is important to use themagento-cloud environment:list
command because it displays environment hierarchies, whereas thegit 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.TIP
You can create an environment branch using themagento-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>
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