Upload an app binary and run Maestro flows on DeviceCloud. This is the primary command and a drop-in replacement for maestro cloud.
dcd cloud <app-file> <flows-dir> [flags]
The command blocks until all tests have completed, then exits with an appropriate exit code.
| Argument |
Description |
<app-file> |
Path to your app binary (.apk for Android, .app or .zip for iOS) |
<flows-dir> |
Path to the flow file or directory of flows to run |
| Flag |
Description |
--api-key <key> |
Your DeviceCloud API key. Defaults to the DEVICE_CLOUD_API_KEY env var. Optional if you've run dcd login |
See Authentication for the full picture.
| Flag |
Description |
--app-binary-id <id> |
Reuse a previously uploaded binary instead of uploading again |
--app-url <url> |
Signed URL to an Expo iOS build (.tar.gz). The archive is downloaded and extracted automatically. Expo signed URLs expire after ~1 hour. Mutually exclusive with --app-file |
--app-file <path> |
Path to the app binary (alternative to the positional <app-file> argument) |
--ignore-sha-check |
Force re-upload even if a binary with the same SHA already exists |
| Flag |
Description |
--android-device <device> |
Android device model to run on (see Devices) |
--android-api-level <level> |
Android API level |
--ios-device <device> |
iOS device model to run on (see Devices) |
--ios-version <version> |
iOS version |
--device-locale <locale> |
Device locale (see Device Locale) |
--orientation <orientation> |
Device orientation, 0 (portrait) or 90 (landscape). Android only (see Orientation) |
--google-play |
Use a Google Play-enabled device. Android only (see Google Play APIs) |
--runner-type <type> |
Runner type to use (see Runner Types) |
| Flag |
Description |
--flows <paths> |
Comma-separated list of flow files to run (alternative to positional arg) |
--config <path> |
Path to a config.yaml workspace config file (see Workspace Configuration) |
--exclude-flows <paths> |
Comma-separated list of flow files or sub-directories to exclude |
--include-tags <tags> |
Only run flows with these tags (comma-separated) |
--exclude-tags <tags> |
Skip flows with these tags (comma-separated) |
| Flag |
Description |
--maestro-version <version> |
Maestro version to use, or latest (see Maestro Versions) |
--env <KEY=VALUE> |
Environment variables to pass to the test. Repeat for multiple values |
--metadata <key=value> |
Arbitrary metadata to attach to the run (shown in the console). Repeat for multiple values |
--name <name> |
Name for this upload (shown in the console) |
--retry <n> |
Retry failed tests up to n times (free of charge). Max 2 (see Retry Strategies) |
Attach Git and pull request metadata to a run. These values are displayed in the DeviceCloud console alongside the test results, making it easy to trace a run back to the exact commit or PR that triggered it.
| Flag |
Description |
--branch <name> |
Git branch name for this run |
--commit-sha <sha> |
Git commit SHA for this run |
--repo-name <owner/repo> |
Repository in owner/repo format (e.g. acme/my-app) |
--pr-number <number> |
Pull request number |
--pr-url <url> |
Pull request URL |
| Flag |
Description |
--maestro-chrome-onboarding |
Force Maestro-based Chrome onboarding. Slows tests but can fix browser-related crashes (see Chrome Onboarding) |
--android-no-snapshot |
Force cold boot instead of snapshot boot. Automatically enabled for API 35+ |
--show-crosshairs |
Display crosshairs for screen interactions during test execution |
| Flag |
Description |
--disable-animations |
Disable device animations during test execution. On Android, disables system animation scales. On iOS, enables Reduce Motion |
| Flag |
Description |
--async |
Submit tests and return immediately (exit 0) without waiting for results (see Async Execution) |
--quiet, -q |
Suppress per-test progress; print only the final summary |
--json |
Output results as JSON. Exits 0 on success, 2 on test failure, 1 on CLI/infrastructure errors |
--json-file |
Write JSON results to a file (<upload_id>_dcd.json by default). Exits 0 even if the test run fails; infrastructure errors still exit 1 |
--json-file-name <name> |
Custom name (or relative path) for the JSON file. Requires --json-file |
--dry-run |
Simulate the run without uploading or triggering a test — useful for debugging workflow issues |
--report <format> |
Generate and download a report. Options: junit, html, html-detailed, allure (see Report Formats) |
--junit-path <path> |
Output path for the JUnit report (requires --report junit) |
--html-path <path> |
Output path for the HTML report (requires --report html or html-detailed) |
--allure-path <path> |
Output path for the Allure report (requires --report allure) |
--download-artifacts <ALL|FAILED> |
Download test artifacts after completion (see Artifacts) |
--artifacts-path <path> |
Output path for the artifacts zip (default ./artifacts.zip). Requires --download-artifacts |
--debug |
Enable verbose debug logging |
Android:
dcd cloud app.apk flows/ --android-device pixel-7 --android-api-level 34
iOS:
dcd cloud app.zip flows/ --ios-device iphone-16 --ios-version 18
Filter by tag:
dcd cloud app.apk flows/ --include-tags smoke
Reuse a previously uploaded binary:
dcd cloud flows/ --app-binary-id 67894274-b789-4c1e-80d4-da8998998999
Save results to JSON:
dcd cloud app.apk flows/ --json-file --json-file-name results.json