DocsPricingCompat
Sign in
Search⌘K
Getting Started
OverviewInstallationQuick StartFirst TestPlansFAQ
Previews & Sharing
Preview uploads & sharingApp Store screenshots
CI & GitHub
GitHub PR PreviewsTests in CITest Results
Cloud (beta)
OverviewPricing
Testing
OverviewMaestro SuitesDetox SuitesPlain-Language Tests
Guides
ConfigurationWrap Existing AppReporting IssuesTroubleshootingMCP
Agents
SetupCLI UseAgent Devtool (Inspect)
REST API
OverviewAuthenticationPreviewsBuildsTest RunsCloud SessionsBilling & LimitsRate LimitsErrors
API
ConfigSettingsMetro PluginOne PluginAgent SkillsTest BridgeDetox DriverMaestro Driver
CLI
Overviewswiftkotlintestmaestrodetoxcleanuprecordfilmstoragepermissionslocationperfdescribefindassertscreenshotgetdowaitshellmodedevicenetworklogsdebugwhat-happenedtimelineiosandroidremoteopenpreviewlistuseskillclaimagentclosesetupcompatproject-reportsupportdesktopdaemonversionupgradeserveruntimeauthloginlogoutconfig
Compatibility
OverviewCustom StubsNative View Primitives
[ Documentation ]
peach maestro

peach maestro

The single YAML test surface. Run Maestro flows using the supported verbs, generate a flow from a plain-language goal, or author one from live CLI actions. Check --list-compat before running an existing suite. Playback, recording, profiling, and hosted results all use the same runner.

terminal
peach maestro [test] <flow-or-dir> [options]

peach maestro            # auto-discovers ./.maestro/ or ./maestro/

peach maestro compare <flow-or-dir> [--udid <id>]   # iOS simulator vs peach, html diff report

peach maestro generate "<goal>"

peach maestro start|keep|end

peach maestro validate <flow>

peach maestro init       # scaffold a starter flow

peach maestro --list-compat

Options

flagdescription
--env KEY=VALUEset env vars for ${KEY} interpolation (repeatable)
--continuouswarn and run once; file watching is not implemented
--format <fmt>junit writes an XML report; html warns without a report
--profilecapture performance stats while the flow runs
--out <dir>write recordings and screenshots to this directory
--url <url>load this target before running the flow
--output <path>JUnit report path for tests, or flow path on maestro end
--validatere-run a live-authored flow before clearing its draft
--videorecord while validating a live-authored flow
--newforce a fresh sim for this run
--headedforce a fresh, VISIBLE window (implies —new, overrides —headless) to watch the flow run live
--recordrecord a webm while the flow runs
--previewrecord events+video, upload, and print /preview/<id>
--preview-openopen the uploaded preview link after a successful run
--preview-origin <url>upload target for —preview
--preview-public-origin <url>public link origin for —preview
--test-output-dir <dir>save flow artifacts and result JSON here; result JSON defaults to —out or /tmp/peach-recordings
--slow <ms>delay between steps for natural pacing
--list-compatprint supported and unsupported Maestro verbs

Examples

terminal
peach maestro test .maestro/login.yaml

peach maestro compare .maestro/ --udid <simulator-udid>

peach maestro generate "log in and verify the welcome screen"

peach maestro start

peach maestro end --output .maestro/login.yaml --validate

peach maestro --env USERNAME=alice test .maestro/login.yaml

peach maestro test .maestro/flow.yaml --record

peach maestro --list-compat

One Maestro Surface

peach maestro owns every YAML test: existing suites, generated tests, and live-authored drafts. Check --list-compat for the supported verbs before running an existing Maestro project:

terminal
peach maestro                          # discover .maestro/ workspace

peach maestro test .maestro/login.yaml # single flow

peach maestro generate "log in and verify the welcome screen"

peach maestro start                    # begin a live-authored draft

peach do tap loginButton

peach maestro keep

peach maestro end --output .maestro/login.yaml --validate

peach maestro init                     # scaffold .maestro/login.yaml

peach maestro --list-compat            # verb support matrix

Supports: tapOn, longPressOn, assertVisible, inputText, scrollUntilVisible, launchApp with JSON arguments, stopApp, clearState, copyTextFrom, evalScript, openLink, when:/optional:, onFlowStart/onFlowComplete, repeat, runFlow, env var interpolation. Launch arguments are installed before guest app entry and replace or clear on each later launch. Device-only verbs (setLocation, addMedia, killApp) throw a clear error.

Directory discovery selects root YAML flows by default, as Maestro does. For nested suites, pass their folder, such as .maestro/flows, or add config.yaml with flows: ["flows/**"]. Keep shared subflows outside those globs; runFlow can still load them. The CLI prints the result directory after writing preview or run receipts.

For live authoring, only the last successful write action becomes the pending candidate; maestro keep commits it to the draft. maestro end --validate re-runs from a clean run before clearing the draft, and preserves the draft if validation fails.

Existing flow files still support frontmatter like:

---

app: 8081

electron: true

---

That lets a flow file encode which target it opens and whether the desktop companion is the preferred runtime for that flow. When you want frame timing for a full scripted path, run the same file with --profile. Maestro playback, recording, and profiling stay on the same bridge-backed sim/action surface as the rest of the CLI.

Related

previous

test

next

detox