dcd cloud

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.

Arguments

Argument	Description
<app-file>	Path to your app binary: .apk for Android, .app or .zip for iOS, or an Expo iOS build archive (.tar.gz), which is extracted automatically
<flows-dir>	Path to the flow file or directory of flows to run

Flags

Authentication

Flag	Description
--api-key <key>, --apiKey	Your DeviceCloud API key. Defaults to the DEVICE_CLOUD_API_KEY env var. Optional if you've run dcd login
--api-url <url>	API base URL. Defaults to the environment you logged in to with dcd login, otherwise https://api.devicecloud.dev

See Authentication for the full picture.

App

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
--encrypt / --no-encrypt	Encryption is on by default (CLI 5.7.0 and later): the app binary, flow files and --env values are encrypted on your machine before upload, each with its own key. Pass --no-encrypt (or set DCD_ENCRYPT=0) to upload them unencrypted. An unchanged binary is still deduplicated, so it isn't uploaded again. See Data Encryption

Device

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)
--render-engine <engine>	Android only. Software renderer the emulator boots with: lavapipe (default) or swiftshader. Try swiftshader if your app fails to render or the device drops out mid-run. Apps built with Flutter are detected and switched automatically
--ios-device-matrix <device>:<version>	Run every flow once on each listed iOS device, e.g. iphone-16:18. Repeat the flag for each device (see Device Matrix)
--android-device-matrix <device>:<apiLevel>	Run every flow once on each listed Android device, e.g. pixel-8:34. Append :play for Google Play. Repeat the flag for each device (see Device Matrix)

Flows

Flag	Description
--flows <path>	Path to a flow file or a directory of flows (alternative to the positional <flows-dir> argument)
--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)

Test Configuration

Flag	Description
--maestro-version <version>, --maestroVersion	Maestro version to use, or latest (see Maestro Versions)
--env <KEY=VALUE>, -e	Environment variables to pass to the test. Repeat for multiple values (see Environment Variables)
--metadata <key=value>, -m	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)

GitHub / PR Context

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

Android-Specific

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 a cold boot instead of a snapshot boot on the standard Android runner. Automatically enabled for API 34+
--show-crosshairs	Display crosshairs for screen interactions during test execution

Performance

Flag	Description
--disable-animations	Disable device animations during test execution. On Android, disables system animation scales. On iOS, enables Reduce Motion

Output & Execution

Flag	Description
--async	Submit tests and return immediately (exit 0) without waiting for results (see Async Execution)
--cancel-previous	Cancel the still-queued tests of the previous run from the same CI context. Needs --repo-name plus --branch or --pr-number (see Cancelling superseded runs)
--priority <level>	low, normal (default) or high. Reorders only your organisation's own queued runs (see Run Priority)
--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. The output includes a notices array with any deprecation or other notices for the run. A run superseded through --cancel-previous has status SUPERSEDED and exits 0
--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>, --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). The HTML report downloads as a ZIP, so use a .zip path such as ./report.zip
--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

Examples

Android:

dcd cloud app.apk flows/ --android-device pixel-8 --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