Cloud 2.02

Magento Cloud CLI Tool

Using the magento-cloud CLI for project management, SSH/database access, and local testing.

Exam Critical: Understanding the Magento Cloud CLI tool is essential for the AD0-E717 exam! Know installation, key commands, SSH/database access, and the difference between magento-cloud CLI and ece-tools.

Magento Cloud CLI Tool

mindmap root((magento-cloud CLI)) Installation One-line installer curl command Path in environment Project Commands project:info project:get project:list project:clear-build-cache Environment Access SSH connection Database access tunnel:open Local Build local:build local:clean Test before push CLI vs ece-tools magento-cloud global ece-tools project-specific

What is the Magento Cloud CLI?

The magento-cloud CLI is a command-line tool for managing Magento Commerce Cloud projects and environments.

Critical Distinction

magento-cloud CLI vs ece-tools:

  • magento-cloud CLI: Global tool for project configuration and information (installed system-wide)
  • ece-tools: Project-specific tool for build, cron, docker actions (found in vendor/bin/ece-tools inside Cloud project)

Installing the Magento Cloud CLI

One-Line Installer

Install the CLI using the one-line installer:

curl -sS https://accounts.magento.cloud/cli/installer | php

Installation Steps

  1. Run the installer: Execute the curl command above
  2. Add to PATH: Include the CLI path in your environment variables
  3. Verify installation: Run magento-cloud list to see all available commands

Environment Variables

After installation, add the CLI to your PATH so you can run it from any directory:

# Add to ~/.bash_profile or ~/.bashrc
export PATH="$HOME/.magento-cloud/bin:$PATH"

Viewing Available Commands

List All Commands

magento-cloud list

This displays all available commands organized by category:

  • project: Project management commands
  • environment: Environment management
  • ssh: SSH connection commands
  • db: Database commands
  • tunnel: SSH tunnel commands
  • local: Local build commands

Project Management Commands

project:info

Retrieve detailed information about a project:

magento-cloud project:info

Information Provided

  • Project ID and name
  • Subscription status (active/inactive)
  • Region and zone
  • Plan type (Starter/Pro)
  • Default branch
  • Created date

project:get

Clone a project locally and associate the current directory with a Magento Cloud project:

magento-cloud project:get [PROJECT_ID]

What it does:

  • Clones the Git repository
  • Sets up remote connection
  • Associates directory with project
  • Downloads project configuration

project:list (projects, pro)

Get a list of all active projects for your account:

magento-cloud project:list
# Alias
magento-cloud projects

project:clear-build-cache

Clear a project's build cache:

magento-cloud project:clear-build-cache

When to Use

Clear build cache when:

  • Testing custom build hooks in .magento.app.yaml
  • Troubleshooting build issues
  • Ensuring a clean build process
  • Build artifacts are causing problems

project:set-remote

Set the remote project for the current Git repository:

magento-cloud project:set-remote [PROJECT_ID]

SSH and Database Access

SSH Access

Prerequisites

Before accessing SSH, you must configure your SSH key:

  1. Go to Cloud Admin UI
  2. Click your profile (upper right-hand corner)
  3. Navigate to Account Settings → SSH Keys
  4. Add your public SSH key

The Cloud dashboard provides easy SSH access. Copy the SSH details to your terminal:

# Example SSH command from dashboard
ssh [project-id]-[environment]@ssh.[region].magentosite.cloud

Database Access

Integration Environment Database

Connection Details:

  • Host: database.internal
  • Username: user
  • Password: (empty)
  • Database: main

magento-cloud db:sql Command

magento-cloud db:sql

This command automatically loads connection details and connects to the database.

Pro Plan: Staging and Production

Pro Staging and Production databases require different credentials:

  • Host: 127.0.0.1
  • Username: [username] (suffix with _stg for staging)
  • Password: [from env.php]
  • Database: [database] (suffix with _stg for staging)

Getting Password:

  1. SSH to node 1
  2. Retrieve from app/etc/env.php

SSH Tunneling

tunnel:open

Create an SSH tunnel to access services (database, Redis, Elasticsearch) from your local machine:

magento-cloud tunnel:open

What It Does

  • Creates secure SSH tunnel to environment
  • Exposes services on local ports
  • Allows local tools to connect (MySQL Workbench, TablePlus, etc.)
  • Displays local connection details

Example Output

SSH tunnel opened on port 30000 to relationship: database
SSH tunnel opened on port 30001 to relationship: redis

Logs are written to: ~/.magento-cloud/tunnels.log

List tunnels with: magento-cloud tunnels
View tunnel details with: magento-cloud tunnel:info
Close tunnels with: magento-cloud tunnel:close

Connecting Through Tunnel

Once the tunnel is open, connect using:

mysql -h 127.0.0.1 -P 30000 -u user main

Local Build Testing

Why Test Builds Locally?

Building the project locally helps:

  • Troubleshoot build issues before pushing to Git
  • Test custom build hooks in .magento.app.yaml
  • Verify build process works as expected
  • Catch problems early in development

local:build

Execute the build process locally:

magento-cloud local:build

Build Process

  1. Reads .magento.app.yaml configuration
  2. Executes build hooks
  3. Compiles code and dependencies
  4. Generates static content
  5. Creates build artifacts

local:clean

Clean up files generated by local build:

magento-cloud local:clean

Critical Warning

Always delete build-generated files before committing!

If build artifacts end up in your Git repository, they can cause serious problems for the build process on the server.

MySQL Service Setup

Before running local builds, ensure MySQL service is set up and accessible locally to match your .magento.app.yaml services configuration.

CLI vs ece-tools

Understanding the Difference

Aspect magento-cloud CLI ece-tools
Installation Global system installation Project dependency (vendor/bin/)
Purpose Project and environment management Build, deploy, cron, docker operations
Scope Works across all Cloud projects Specific to one Cloud project
Command Prefix magento-cloud ./vendor/bin/ece-tools
Examples project:info, ssh, tunnel:open docker:build, run scenario/build
Technology Built with Symfony, imports Platform.sh PHP client Magento-specific build/deploy tool

Best Practices

Do's
  • Configure SSH keys before attempting SSH access
  • Use tunnel:open for secure local service access
  • Test builds locally before pushing to Git
  • Always run local:clean after local:build
  • Use project:clear-build-cache when troubleshooting
  • Keep CLI updated to latest version
  • Use magento-cloud list to discover commands
Don'ts
  • Don't commit build artifacts to Git
  • Don't skip local:clean after builds
  • Don't confuse magento-cloud with ece-tools
  • Don't share SSH keys or database credentials
  • Don't forget to suffix _stg for Pro staging DB
  • Don't attempt SSH without configuring keys first
  • Don't push untested build hooks

Common Workflows

1. Initial Project Setup

# Install CLI
curl -sS https://accounts.magento.cloud/cli/installer | php

# Get project
magento-cloud project:get [PROJECT_ID]

# View project info
magento-cloud project:info

2. Testing Build Locally

# Clear build cache
magento-cloud project:clear-build-cache

# Build locally
magento-cloud local:build

# Test the build...

# Clean up
magento-cloud local:clean

3. Database Access

# Direct SQL access
magento-cloud db:sql

# Or via tunnel
magento-cloud tunnel:open
# Then connect to localhost:PORT

Exam Tips

Key Points to Remember

  • Installation: curl -sS https://accounts.magento.cloud/cli/installer | php
  • View commands: magento-cloud list
  • CLI vs ece-tools: magento-cloud = global project management, ece-tools = project-specific builds
  • Project info: project:info shows subscription status and details
  • Clone project: project:get [PROJECT_ID]
  • SSH prerequisite: Must configure SSH keys in Account Settings first
  • Integration DB: host=database.internal, user=user, password=(empty), db=main
  • Pro DB: Use _stg suffix for staging; get password from env.php
  • Database command: magento-cloud db:sql auto-connects
  • Tunneling: tunnel:open creates secure connection to services
  • Local build: local:build then local:clean
  • Critical: Always delete build artifacts before committing
  • Clear cache: project:clear-build-cache for build troubleshooting
  • Technology: CLI built with Symfony, imports Platform.sh PHP client
Previous: Cloud 2.01 Local Development Practice Cloud 2.02