Maestro install

Maestro Install

Overview

Use this skill to make the local machine ready for Maestro CLI usage. Start by checking whether maestro already exists, then choose the smallest install, update, or repair path that matches the platform and the user's preferred package manager.

When to Use

• The user asks to install Maestro.
• maestro is missing from PATH.
• The local Maestro CLI is broken, outdated, or needs to be pinned to a specific version.
• Another Maestro skill depends on a local CLI that is not ready yet.

When Not to Use

• The local Maestro CLI already works and the user only needs help writing or debugging flows. Use $maestro-testing for testing work.
• The task is about a different toolchain and does not involve Maestro CLI setup.
• The user only wants documentation links without any environment checks or install guidance.

Inputs to Gather First

• The platform: macOS, Linux, Windows, or WSL2.
• Whether maestro already exists with command -v maestro and maestro --version.
• The installed Java version from java -version.
• The user's preferred install path, if they already manage Maestro through a package manager such as Homebrew.

Quick Start

1. Detect the platform and shell. On Unix-like systems, identify the relevant shell rc file only if PATH changes are needed.
2. Check whether the CLI is already available with command -v maestro and maestro --version.
3. Verify Java prerequisites with java -version. Maestro requires Java 17 or newer, and JAVA_HOME should point at that installation.
4. If the user wants maestro-testing and the CLI is missing, install Maestro before continuing with any flow authoring or runs.
5. After install or update, verify with maestro --version and maestro --help.

Install Decision Tree

macOS

• Prefer the official install script unless the user specifically wants Homebrew or already manages Maestro through Homebrew.
• Script install:

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

• Homebrew install:

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

• Verify:

maestro --help

• If the user plans to drive iOS simulators locally, confirm Xcode and Xcode Command Line Tools are current.

Linux

• Ensure Java 17+ is installed first.
• Official install:

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

• Verify:

maestro --help

Windows

• Prefer the official install script when a shell environment supports it.
• Script install:

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

• Manual install fallback:

1. Download the latest maestro.zip from GitHub releases.
2. Extract it into a stable folder such as C:\\maestro.
3. Add C:\\maestro\\bin to the user PATH:

setx PATH "%PATH%;C:\maestro\bin"

4. Restart the terminal.

• Verify:

maestro --help

WSL2

• Use WSL only when it is strictly necessary. Maestro's docs recommend native macOS, Windows, or Linux when possible.
• Install Java 17+ first:

sudo apt update
sudo apt install openjdk-17-jdk

• Ensure shell environment variables:

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

• Install Maestro:

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

• If the user also needs Android emulators through WSL, load references/core/installing-and-updating-maestro-cli.md and follow the WSL ADB bridging notes.

Update and Repair

• First determine how Maestro was originally installed.
• If it was installed with the official script on macOS, Linux, or WSL2, rerun:

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

• If it was installed with Homebrew on macOS, run:

brew update
brew upgrade mobile-dev-inc/tap/maestro

• If it was installed manually on Windows, replace the existing files with the latest maestro.zip contents.
• If the user needs a pinned version for team or CI compatibility, run:

export MAESTRO_VERSION={version}
curl -Ls "https://get.maestro.mobile.dev" | bash

Replace {version} with the requested Maestro CLI version and verify with maestro --version.

Execution Rules

• Prefer doing the install work directly when the user asked to install or repair Maestro. Do not stop at documentation unless the user explicitly wants instructions only.
• Installs and updates typically need network access. If a curl, brew, or download command fails because of sandbox, permission, or network restrictions, request the required access and continue.
• Do not overwrite the user's preferred package-manager choice unless it is clearly broken or unsupported on the current platform.
• If maestro is already installed and the user only wants to use it, avoid reinstalling. Verify the version and move on.
• When install succeeds but the shell still cannot find maestro, inspect PATH before retrying. Only edit shell rc files when required by the install method or current environment.

Validation

• maestro --version completes successfully.
• maestro --help completes successfully.
• Java 17 or newer is available and JAVA_HOME is consistent with that installation when required by the platform.
• The shell can locate maestro without relying on a stale or temporary path.

Common Failure Modes

• Java is missing or older than version 17.
• The install method succeeded but the shell PATH was not updated.
• The user already manages Maestro through a different package manager than the one chosen for repair.
• WSL2 setup tries to drive emulators without the required host integration or ADB bridging.
• A pinned version was requested but the installed version was never verified afterward.

References

• Load references/core/installing-and-updating-maestro-cli.md for the official commands, WSL cautions, PATH notes, and version pinning examples.