Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 trust --formula mobile-dev-inc/tap/maestro
brew install mobile-dev-inc/tap/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:

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

  1. Download the latest maestro.zip.

  2. Extract the content to a stable location (e.g., C:maestro).

  3. 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"

  4. 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.

  1. Create the Android directory:

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

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

  4. Reload the terminal running:

  5. Install the 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.

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:

  1. Open Android Studio on Windows.

  2. 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:

Restart your PowerShell terminal after running this command.

Manual method

  1. Search for Edit environment variables for your account in Windows Search.

  2. Edit the Path variable.

  3. 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:

  1. Close Android Studio.

  2. Kill the existing process running:

  3. 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.

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

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:

To install on Linux, you can use the cURL command on any distribution:

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

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 overviewNextUpdate the Maestro CLI

Last updated