Cloud CLI

Last update: 2024-02-05
  • Topics:
  • Cloud
    View more on this topic
  • 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. 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:

  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.

    curl -sS https://accounts.magento.cloud/cli/installer | php
    
  3. Add magento-cloud CLI to the bash profile.

    export PATH=$PATH:$HOME/.magento-cloud/bin
    
  4. Reload the updated bash profile.

    . ~/.bash_profile
    
  5. 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:
    
  6. Verify the magento-cloud command is in your path. The following example lists the available commands.

    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.

    magento-cloud login
    
  4. List your projects.

    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.

    magento-cloud environment:list
    
    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.

    git fetch origin
    
  7. 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 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.

    git pull origin <environment-ID>
    
  9. (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

On this page