Magento Cloud CLI Tool: Installation and Complete Command Guide
[Updated: March 13, 2026]
Your Adobe Commerce Cloud project needs more than a web console. The Magento Cloud CLI gives you 123 commands to deploy code, manage environments, create backups, and tunnel into remote services from your terminal.
This guide covers installation, essential commands grouped by workflow, and solutions for common issues.
Key Takeaways
- The Magento Cloud CLI (v1.47.0) provides 123 commands across 20+ categories for managing Adobe Commerce Cloud projects.
- Installation requires a Unix-based OS (Linux or macOS). Windows is not supported.
- Essential workflows include deployment, SSH access, database management, service tunneling, and environment snapshots.
- The CLI extends Cloud Console with features like API token authentication for CI/CD pipelines.
- Environment pause and resume commands reduce integration environment costs.
What is the Magento Cloud CLI?
Magento Cloud CLI = A command-line tool for managing Adobe Commerce on cloud infrastructure projects. It replaces manual Cloud Console tasks with scriptable, automatable commands.
Perfect for: DevOps engineers, backend developers, agencies managing multiple cloud projects
Not ideal for: Store owners without technical staff, teams using Magento Open Source (self-hosted)
The Magento Cloud CLI (magento-cloud) is Adobe's official command-line interface for Adobe Commerce on cloud infrastructure. Version 1.47.0 includes 123 commands organized into 20+ categories.
It handles everything the Cloud Console web interface does and more. You can deploy code, manage branches, SSH into environments, create database dumps, open tunnels to remote services, and monitor server metrics.
The CLI runs on your local machine. It connects to your cloud project through authenticated API calls. Every command targets a specific environment (integration, staging, or production), which makes it safe to work across project stages without risk of accidental changes to the wrong environment.
Important: The CLI cannot be installed on Cloud environments themselves. Those file systems are read-only. Install it on your local development machine.
How to Install the Magento Cloud CLI
Prerequisites
| Requirement | Details |
|---|---|
| Operating System | Linux or macOS (Unix-based) |
| PHP | PHP with curl extension enabled |
| Shell | Bash or Zsh |
| Windows | Not supported. Use WSL2 as a workaround |
Step 1: Run the Installer
Open your terminal and execute:
curl -sS https://accounts.magento.cloud/cli/installer | php
This downloads and installs the CLI to ~/.magento-cloud/bin/.
Step 2: Add to Your PATH
For Bash users:
export PATH=$PATH:$HOME/.magento-cloud/bin
For Zsh users (macOS default since Catalina):
echo 'export PATH=$PATH:$HOME/.magento-cloud/bin' >> ~/.zshrc
Step 3: Reload Your Shell Profile
Bash:
source ~/.bash_profile
Zsh:
source ~/.zshrc
Step 4: Authenticate
Run the CLI for the first time:
magento-cloud
This opens your browser for authentication. Enter your Adobe Commerce Cloud account credentials. The CLI stores your session token for later use.
For CI/CD pipelines (no browser available):
magento-cloud auth:api-token-login
Step 5: Verify the Installation
List all available commands:
magento-cloud list
You should see 123 commands organized by category. If you get "command not found," your PATH configuration needs fixing (see Troubleshooting below).
Step 6: Enable Auto-Updates
The CLI checks for updates on each login. To update by hand:
magento-cloud self:update
Essential Commands by Category
The CLI's 123 commands span 20+ categories. Here are the most practical ones grouped by workflow.
Environment Management
| Command | Alias | What It Does |
|---|---|---|
environment:list |
environments |
Lists all project environments |
environment:checkout |
checkout |
Switches to a different environment |
environment:branch |
branch |
Creates and activates a new branch |
environment:merge |
merge |
Merges current environment into parent |
environment:sync |
sync |
Syncs code and data from parent |
environment:push |
push |
Pushes code changes to environment |
environment:redeploy |
redeploy |
Forces a redeployment |
environment:pause |
— | Pauses an integration environment |
environment:resume |
— | Resumes a paused environment |
environment:url |
url |
Opens the environment URL in browser |
Key distinction: Regular git branch does NOT activate environments in the Cloud. Use magento-cloud environment:branch to create AND activate.
Cost savings: Use environment:pause on integration environments you do not need right now. Paused environments consume fewer resources and reduce your cloud hosting costs.
SSH and Remote Access
| Command | Alias | What It Does |
|---|---|---|
environment:ssh |
ssh |
Opens SSH session to environment |
ssh-key:add |
— | Adds your SSH key to the project |
ssh-key:list |
— | Lists configured SSH keys |
Add your SSH key before attempting remote access:
magento-cloud ssh-key:add ~/.ssh/id_rsa.pub
Then connect:
magento-cloud ssh -e staging
Database Operations
| Command | What It Does |
|---|---|
db:dump |
Creates a local copy of the remote database |
db:sql |
Runs SQL queries on the remote database |
db:size |
Shows database size information |
Create a database dump before any major deployment:
magento-cloud db:dump -e production
Service Tunneling
Tunnel commands let you access remote services (MySQL, Redis, Elasticsearch) from your local machine. This is valuable for debugging production issues without deploying debug code.
| Command | What It Does |
|---|---|
tunnel:open |
Opens SSH tunnels to all remote services |
tunnel:close |
Closes active tunnels |
tunnel:list |
Lists active tunnels |
tunnel:single |
Opens a tunnel to a single service |
tunnel:info |
Shows tunnel connection details |
# Open tunnels to all services
magento-cloud tunnel:open -e staging
# Connect to the tunneled MySQL
mysql -h 127.0.0.1 -P 30000 -u user -p
This eliminates the need to install services on your local development environment when you need to work with the remote environment's data.
Snapshots and Backups
| Command | What It Does |
|---|---|
snapshot:create |
Creates a full environment backup |
snapshot:list |
Lists available snapshots |
snapshot:restore |
Restores from a snapshot |
Best practice: Create a snapshot before every production deployment.
# Snapshot before deploying
magento-cloud snapshot:create -e production
# Deploy
magento-cloud environment:push -e production
# If something breaks, restore
magento-cloud snapshot:restore -e production
Read our Magento backup guide for a complete backup strategy that combines CLI snapshots with additional data protection layers.
Monitoring and Metrics
| Command | Alias | What It Does |
|---|---|---|
metrics:all |
metrics |
Shows CPU, memory, and disk usage |
metrics:cpu |
— | CPU usage details |
metrics:memory |
— | Memory usage details |
metrics:disk-usage |
— | Disk usage details |
magento-cloud metrics:all -e production
Monitor resource consumption to know when it is time to scale your infrastructure. For stores outgrowing Adobe Commerce Cloud, managed Magento hosting on AWS provides the same monitoring with more control over scaling decisions.
Variables and Configuration
| Command | What It Does |
|---|---|
variable:list |
Lists environment variables |
variable:set |
Sets an environment variable |
variable:get |
Gets a variable value |
variable:delete |
Removes a variable |
decode |
Decodes MAGENTO_CLOUD_VARIABLES |
The decode command is useful for debugging. It shows the decoded JSON content of the MAGENTO_CLOUD_VARIABLES environment variable:
magento-cloud decode MAGENTO_CLOUD_VARIABLES
CI/CD Integration
The CLI supports non-interactive mode for automated pipelines.
Set the environment variable to suppress interactive prompts:
export MAGENTO_CLOUD_CLI_NO_INTERACTION=1
Authenticate with an API token instead of browser login:
magento-cloud auth:api-token-login
A minimal deployment pipeline looks like:
#!/bin/bash
export MAGENTO_CLOUD_CLI_NO_INTERACTION=1
magento-cloud auth:api-token-login
magento-cloud snapshot:create -e production
magento-cloud push -e production
This approach gives teams reliable, repeatable zero downtime deployments without manual intervention.
Troubleshooting Common Issues
| Issue | Cause | Fix |
|---|---|---|
| "command not found" | CLI not in PATH | Re-add export PATH=$PATH:$HOME/.magento-cloud/bin to your shell profile and reload with source |
| "Permission denied" | Wrong directory permissions | Run chmod +x ~/.magento-cloud/bin/magento-cloud or use sudo for the install |
| Login fails | Wrong credentials or 2FA issue | Reset password at accounts.magento.cloud. Verify your 2FA app is synced |
| Environment not listed | Wrong project directory | Run magento-cloud project:list to verify your project, then cd into the correct directory |
| SSH connection refused | Missing or wrong SSH key | Run magento-cloud ssh-key:add with your public key |
| Merge conflicts | Diverged branches | Pull latest changes with git pull, resolve conflicts, then retry the merge |
| Tunnel connection drops | Network instability | Reconnect with magento-cloud tunnel:open |
| Self-update fails | Permission issue on CLI directory | Run magento-cloud self:update with appropriate permissions |
Zsh vs Bash note: macOS switched to Zsh as the default shell in Catalina (10.15). If you added the PATH to ~/.bash_profile but your terminal uses Zsh, the Magento CLI commands will not be found. Add the PATH to ~/.zshrc instead.
Complete Command Reference
Version 1.47.0 includes 123 commands. Here are the most common categories:
| Category | Commands | Key Operations |
|---|---|---|
| Environment | 20 | Branch, merge, push, SSH, pause, URL, Xdebug |
| Integration | 9 | Activity, webhook, service management |
| Domain | 5 | Add, remove, list, update, get |
| Service | 6 | MongoDB, Redis service operations |
| Tunnel | 5 | Open, close, list, single, info |
| User | 5 | Add, delete, list, role, get |
| Variable | 5 | Set, get, list, delete, update |
| Auth | 4 | Login, logout, browser-login, API token |
| Certificate | 4 | Add, list, delete, get |
| SSH Key | 3 | Add, list, delete |
| Snapshot | 3 | Create, list, restore |
| Mount | 4 | Upload, download, list, size |
| Metrics | 4 | All, CPU, memory, disk |
| Activity | 4 | List, get, log, cancel |
| DB | 3 | Dump, SQL, size |
Additional categories include project, app, commit, repo, route, cron, worker, and blackfire. Run magento-cloud list for the full reference, or see the official Cloud CLI Reference for all options and flags.
FAQ
What is the Magento Cloud CLI?
The Magento Cloud CLI is Adobe's official command-line tool for managing Adobe Commerce on cloud infrastructure. It provides 123 commands for deployment, environment management, SSH access, and monitoring.
How do I install the Magento Cloud CLI?
Run curl -sS https://accounts.magento.cloud/cli/installer | php in your terminal. Add the install path to your shell profile, reload it, and authenticate with your Adobe Commerce Cloud account.
Does the Magento Cloud CLI work on Windows?
No. The CLI requires a Unix-based OS (Linux or macOS). Windows users should use WSL2 (Windows Subsystem for Linux) as a workaround.
What is the difference between magento-cloud push and git push?
Both push code to the remote. The magento-cloud push command triggers the Cloud build and deploy process with progress feedback and error handling. A regular git push does the same when pushing to the Cloud Git remote, but without the CLI's built-in monitoring.
How do I SSH into my Cloud environment?
Run magento-cloud ssh -e <environment-name>. Make sure your SSH key is added to the project first with magento-cloud ssh-key:add.
Can I use the CLI in CI/CD pipelines?
Yes. Set MAGENTO_CLOUD_CLI_NO_INTERACTION=1 and use magento-cloud auth:api-token-login for non-interactive authentication.
How do I create a backup before deployment?
Use magento-cloud snapshot:create -e production before deploying. Restore with magento-cloud snapshot:restore if needed.
What does environment:pause do?
It pauses an integration environment to reduce resource consumption and costs. Resume it with environment:resume when needed. This works on integration environments, not staging or production.
How do I access remote databases from my local machine?
Use magento-cloud tunnel:open to create SSH tunnels to all remote services. Then connect to the tunneled database on localhost with the port shown in magento-cloud tunnel:info.
How do I update the CLI to the latest version?
Run magento-cloud self:update. The CLI also checks for updates on each login.
