How to install Maestro CLI

Step-by-step installation guide for Maestro CLI on macOS, Windows, and Linux.

Maestro also provides you with the option to use the CLI by terminal. This document will cover the installation of Maestro CLI on the three operational system supported: macOS, Windows and Linux.

Prerequisites

To install the Maestro CLI, you need the following:

Java version 17 or higher.

Ensure that the JAVA_HOME environment variable points to your Java 17+ installation.
You can install Java using Oracle JDK, Temurin JDK or SDKMAN.
To verify the version of your Java installation, run java -version.

Installation

You can install the Maestro CLI on Windows, macOS and Linux.

To install on macOS, you can either run:

curl -fsSL "https://get.maestro.mobile.dev" | bash

Or you can use homebrew by running the commands:

brew tap mobile-dev-inc/tap
brew install maestro

Run maestro --help to verify that the Maestro CLI is working properly.

For macOS, ensure that your have also the last version os XCode and XCode Command Line Tools installed.

To install on Windows, you can either run:

curl -fsSL "https://get.maestro.mobile.dev" | bash

Or you can install using the releases page on GitHub. To install using the release package, follow these steps:

Download the latest maestro.zip.
Extract the content to a stable location (e.g., C:maestro).
Update your PATH to add the Maestro CLI environment variable. Run the following in PowerShell to add the Maestro bin folder to your environment variables:
```
setx PATH "%PATH%;C:\maestro\bin"
```
Restart your terminal to apply changes.

Run maestro --help to verify that the Maestro CLI is working properly.

Installing Maestro in WSL2 allows you to use a Linux environment while using Android emulators running on your Windows host.

Use the Windows (WSL) option only if it is strictly necessary.

Although it is possible to run the Maestro CLI on WSL, Maestro recommends using one of the other supported environments (macOS, Windows, or Linux). The WSL setup requires advanced port configuration, which can introduce issues when testing your app.

If you encounter problems running your tests using Maestro CLI on WSL, check the troubleshooting guide.

1. Install Java and Maestro

First, ensure you have Java 17+ installed.

sudo apt update
sudo apt install openjdk-17-jdk

Update your environment variables to ensure JAVA_HOME is set and Maestro is in your PATH. Add the following to your ~/.bashrc (or ~/.zshrc):

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
export PATH=$PATH:$HOME/.maestro/bin

Reload your configuration:

source ~/.bashrc

Now, install Maestro:

curl -fsSL "https://get.maestro.mobile.dev" | bash

2. Setup Android environment

Since you cannot run the Android Studio GUI directly in WSL easily, you need to set up the Android command-line tools manually. This enables you to access and control the Android emulator running on Windows.

Create the Android directory:
```
mkdir -p $HOME/Android/cmdline-tools
```

Download the latest command line tools for Linux (zip/targz) and unzip it. Make sure you update the URL with the latest version.

cd $HOME/Android/cmdline-tools
# Replace with the actual URL for the latest version
wget https://dl.google.com/android/repository/commandlinetools-linux-14742923_latest.zip -O cmdline-tools.zip
unzip cmdline-tools.zip
mv cmdline-tools latest
rm cmdline-tools.zip

Configure the environment by adding the following to your ~/.bashrc:

# --- Android PATH ---
export ANDROID_HOME=$HOME/Android
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools

Reload the terminal running:
```
source ~/.bashrc.
```
Install the platform tools:
```
sdkmanager --install "platform-tools"
```

3. Connect to Windows Emulator

Android Emulators run on the Windows host. You need to bridge ADB from WSL to Windows.

On Windows (PowerShell):

Start the ADB server to allow external connections.

adb -a -P 5037 nodaemon server

If successful, the command will not show any output and will just sit there. This is normal! Do not close this PowerShell window, as it keeps the connection alive.

After starting the server and proceeding to WSL, you must have an active Android device. To accomplish this:

Open Android Studio on Windows.
Launch a Virtual Device using the Emulator.

`adb` is not recognized?

If you see an error saying The term 'adb' is not recognized, it means the Android SDK platform-tools are not in your Windows PATH.

Add to PATH via PowerShell (Recommended)

Run this command in PowerShell to permanently add the path for your user:

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:LOCALAPPDATA\Android\Sdk\platform-tools", "User")

Restart your PowerShell terminal after running this command.

Manual method

Search for Edit environment variables for your account in Windows Search.
Edit the Path variable.
Click New and paste: %LOCALAPPDATA%\Android\Sdk\platform-tools.

Error: could not install `smartsocket` listener?

If you see an error like cannot bind to 0.0.0.0:5037, it means another ADB (e.g., from Android Studio) is already running. To solve this problem, do the following:

Close Android Studio.
Kill the existing process running:
```
taskkill /F /IM adb.exe
```
Try to start the ADB server again.

On WSL:

Configure ADB to connect to the Windows host IP. Replace <WINDOWS_IP> with your actual Windows IP address.

adb kill-server
export ADB_SERVER_SOCKET=tcp:<WINDOWS_IP>:5037
adb devices

To identify the WINDOWS_IP, run the following command in yout WSL terminal:

ip route show | grep default | awk '{print $3}'

You should see your emulator listed, indicating your connection is working.

4. Running Maestro

When running Maestro commands, use the --host flag to point to your Windows machine:

maestro --host <WINDOWS_IP> test flow.yaml

Next steps

Now that the Maestro CLI is installed on your system, it’s time to run your first app test. Follow the Run your first test with the Maestro CLI guide to get started.

If you need to update the CLI or install a specific Maestro CLI version, check the Update the Maestro CLI guide.

PreviousMaestro CLI overview NextUpdate the Maestro CLI

Last updated 3 days ago

Good evening

hashtagPrerequisites

hashtagInstallation

hashtagUse the Windows (WSL) option only if it is strictly necessary.

hashtag1. Install Java and Maestro

hashtag2. Setup Android environment

hashtag3. Connect to Windows Emulator

hashtagadb is not recognized?

hashtagError: could not install smartsocket listener?

hashtag4. Running Maestro

hashtagNext steps