CLI parameters

The marathon-cloud CLI submits test runs, lists device configurations, and downloads artifacts. This page documents every command and flag as of CLI 1.0.65.

Commands

Command	Description
run android	Run Android instrumentation tests.
run ios	Run XCTest / XCUITest suites on iOS simulators.
run maestro android	Run Maestro flows on Android.
run maestro ios	Run Maestro flows on iOS.
devices android	List available Android device configurations.
download	Download artifacts and reports for a run.
completions	Generate shell completion scripts.

There is no devices ios command; the iOS device list is fixed and documented in supported devices.

Exit codes

The CLI is designed to gate a pipeline. With the default --wait true:

Exit code	Meaning
0	All tests passed, or --ignore-test-failures was set.
1	At least one test failed, or the run could not be submitted or completed (validation error, upload failure, API error).

With --wait false the CLI exits 0 as soon as the run is accepted, and the result reflects submission only.

Result file

Pass --result-file <path> to get a machine-readable summary. The format follows the extension: .json (default) or .yaml / .yml.

With --wait true (default), the file is written when the run finishes:

{
  "id": "01J8ZQ6W5K3R2YV7N4X1M9P0QA",
  "report": "https://cloud.marathonlabs.io/runs/01J8ZQ6W5K3R2YV7N4X1M9P0QA/report",
  "state": "passed",
  "passed": 412,
  "failed": 0,
  "ignored": 3,
  "billable_time": 7260.5
}

state is passed or failure. billable_time is the total device time in seconds, summed across all devices used by the run.

With --wait false, only the run ID is written:

{ "id": "01J8ZQ6W5K3R2YV7N4X1M9P0QA" }

Use the ID with marathon-cloud download --id <id> later in the pipeline.

Common run flags

These flags are accepted by every run subcommand.

Flag	Description	Default
--api-key	Marathon Cloud API token. Required. Also read from MARATHON_CLOUD_API_KEY.
--base-url	API base URL.	https://cloud.marathonlabs.io/api
-o, --output	Local directory to download reports and artifacts into after the run.
--wait	Wait for the run to complete and exit with its result.	true
--name	Human-readable run name shown in the console.
--link	URL back to the CI job or pull request.
--branch	Branch name recorded with the run.
--project	Project slug, when your organization uses multiple projects.
--filter-file	YAML filter file.
--isolated	Run every test in its own batch. See batching.	false
--ignore-test-failures	Exit 0 even when tests fail.	false
--code-coverage	Collect code coverage.	false
--concurrency-limit	Cap the number of devices used in parallel. An escape hatch for suites or backends that cannot handle parallel execution; it makes runs slower. See batching.	unlimited
--result-file	Path to write the result file.
--no-progress-bars	Disable interactive progress output. Recommended in CI.	false
--retry-quota-test-uncompleted	Allowed re-runs per test for executions that did not complete (device or infrastructure failure).	platform default
--retry-quota-test-preventive	Allowed preventive retries per test. See retries.	platform default
--retry-quota-test-reactive	Allowed reactive retries per test after a failure.	platform default
--no-retries	Disable all retries. Sets every quota to 0. Conflicts with the --retry-quota-* flags.	false
--analytics-read-only	Use historical data for scheduling but do not record this run into it. Useful for experiments that should not skew future runs.	false

--wait, --isolated, --ignore-test-failures, --code-coverage, and --analytics-read-only accept an optional value: --isolated, --isolated true, and --isolated false are all valid. The remaining boolean flags (--no-retries, --no-progress-bars, --mock-location, --profiling) are switches and take no value.

marathon-cloud run android

marathon-cloud run android \
  --application app.apk \
  --test-application tests.apk

Flag	Description	Default
-a, --application	Application APK.
-t, --test-application	Instrumentation test APK.
--application-bundle	Multi-module bundle as app.apk,test.apk. Repeatable. Alternative to --application + --test-application.
--library-bundle	Test APK for a library module without a separate app APK. Repeatable.
--os-version	Android version: 8, 8.1, 9, 10, 11, 12, 13, 14, 15, 16, 17. Versions 15+ require a google_apis* image; versions below 10 require google_apis.	platform default
--system-image	default, google_apis, google_apis_playstore.	platform default
--arch	Emulator CPU architecture: amd64 or arm64. arm64 needs Android 9 or later; default images are arm64 only. See architecture.	amd64
--device	Device type ID from marathon-cloud devices android. Use watch or tv for those form factors; anything else is treated as a phone. See supported devices for valid OS and image combinations.	phone
--flavor	Deprecated. Only native is supported; the flag is ignored.
--instrumentation-arg	KEY=VALUE passed to the instrumentation runner. Repeatable.
--pull-files	Files to pull from the device after each batch, as ROOT:PATH where ROOT is EXTERNAL_STORAGE or APP_DATA and PATH is relative to that root, e.g. EXTERNAL_STORAGE:Documents/results. Repeatable.
--mock-location	Allow mock location providers. Switch; takes no value.	false
--front-camera	none, emulated. Requires a google_apis* image.	none
--back-camera	none, virtualscene, emulated. Requires a google_apis* image.	none
--profiling	Collect performance profiling data.	false

marathon-cloud run ios

marathon-cloud run ios \
  --application YourApp.app \
  --test-application YourAppUITests-Runner.app

Flag	Description	Default
-a, --application	Application bundle: a .app directory, or a .zip / .ipa containing it. Required.
-t, --test-application	Test runner bundle: a .app or .xctest directory, or a .zip / .ipa containing it. Required.
--os-version	iOS version: 18.2, 18.4, 26.1. Inferred from --device when omitted.
--device	iPhone-11, iPhone-16, iPhone-16-Plus, iPhone-16-Pro, iPhone-16-Pro-Max, iPhone-17, iPhone-17-Pro, iPhone-17-Pro-Max. Not every device is available on every iOS version; see supported devices.
--xcode-version	Deprecated and hidden. Xcode is selected from --os-version; passing this flag prints a warning.
--batch-isolation	default or uninstall_app (remove the app between batches).	default
--xctestrun-env	KEY=VALUE environment variable for the test runner process. Repeatable.
--xctestrun-test-env	KEY=VALUE environment variable for the app under test. Repeatable.
--xctestplan-filter-file	.xctestplan file used to select tests.
--xctestplan-target-name	Target name inside the test plan.
--test-timeout-default	Per-test timeout in seconds.	300
--test-timeout-max	Upper bound in seconds for per-test timeouts set inside the test plan.
--granted-permission	Permission to pre-grant. Repeatable. Values: calendar, contacts-limited, contacts, location, location-always, photos-add, photos, media-library, microphone, motion, notifications, reminders, siri.

Directories are zipped by the CLI before upload.

marathon-cloud run maestro

Maestro runs accept the common run flags plus the flags below. --system-image, --flavor, and the Android device-feature flags are not available; Maestro runs always use google_apis images.

Android

marathon-cloud run maestro android \
  --application app.apk \
  --test-application flows/ \
  [FLOW...]

Flag	Description	Default
-a, --application	Application APK. Required.
-t, --test-application	Directory containing Maestro YAML flows. Required.
--os-version	Android version, same values as run android.	platform default
--arch	amd64 or arm64. arm64 needs Android 9 or later.	amd64
--device	Device type ID from marathon-cloud devices android.	phone
--maestro-env	KEY=VALUE made available to flows as ${KEY}. Repeatable.
FLOW...	Positional paths (files or directories) inside --test-application to run. Runs everything when omitted.

iOS

marathon-cloud run maestro ios \
  --application YourApp.app \
  --test-application flows/ \
  [FLOW...]

Flag	Description	Default
-a, --application	Application bundle (.app, .zip, or .ipa). Required.
-t, --test-application	Directory containing Maestro YAML flows. Required.
--os-version	iOS version, same values as run ios.
--device	iOS device, same values as run ios.
--maestro-env	KEY=VALUE made available to flows as ${KEY}. Repeatable.
FLOW...	Positional paths (files or directories) inside --test-application to run. Runs everything when omitted.

marathon-cloud devices android

Prints the Android device catalog as YAML, including the device type IDs accepted by --device.

marathon-cloud devices android --api-key $MARATHON_CLOUD_API_KEY

Flag	Description	Default
--api-key	Marathon Cloud API token. Required.
--base-url	API base URL.	https://cloud.marathonlabs.io/api
--no-progress-bars	Disable interactive progress output.	false

marathon-cloud download

Download artifacts for an existing run. See artifacts for the directory layout.

marathon-cloud download --id <RUN_ID> --output artifacts/

Flag	Description	Default
--id	Run ID. Required.
-o, --output	Directory to download into. Required.
--wait	Wait for the run to finish before downloading.	true
--glob	Only download paths matching the glob, e.g. 'tests/**'.	everything
--api-key	Marathon Cloud API token. Required.
--base-url	API base URL.	https://cloud.marathonlabs.io/api
--no-progress-bars	Disable interactive progress output.	false

marathon-cloud completions

marathon-cloud completions bash > /etc/bash_completion.d/marathon-cloud

Supported shells: bash, zsh, fish, powershell, elvish.

Global options

Flag	Description
-v, --verbose	Increase log verbosity. Repeat for more detail (-vv).
-q, --quiet	Decrease log verbosity. Repeat to silence more.
-h, --help	Show help.
-V, --version	Show the CLI version.

Note

For task-oriented walkthroughs, see the Android, iOS, and Maestro setup guides.