> For the complete documentation index, see [llms.txt](https://docs.devicecloud.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devicecloud.dev/cli-reference/dcd-cloud.md). # Cloud Upload an app binary and run Maestro flows on DeviceCloud. This is the primary command and a drop-in replacement for `maestro cloud`. ```bash dcd cloud [flags] ``` The command blocks until all tests have completed, then exits with an appropriate [exit code](/advanced/exit-codes.md). ## Arguments | Argument | Description | | ------------- | ---------------------------------------------------------------------- | | `` | Path to your app binary (`.apk` for Android, `.app` or `.zip` for iOS) | | `` | Path to the flow file or directory of flows to run | ## Flags ### Authentication | Flag | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `--api-key ` | Your DeviceCloud API key. Defaults to the `DEVICE_CLOUD_API_KEY` env var. Optional if you've run [`dcd login`](/cli-reference/dcd-login.md) | See [Authentication](/getting-started/api-keys.md) for the full picture. ### App | Flag | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--app-binary-id ` | Reuse a previously uploaded binary instead of uploading again | | `--app-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 to the app binary (alternative to the positional `` argument) | | `--ignore-sha-check` | Force re-upload even if a binary with the same SHA already exists | ### Device | Flag | Description | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `--android-device ` | Android device model to run on (see [Devices](/getting-started/devices-configuration.md)) | | `--android-api-level ` | Android API level | | `--ios-device ` | iOS device model to run on (see [Devices](/getting-started/devices-configuration.md)) | | `--ios-version ` | iOS version | | `--device-locale ` | Device locale (see [Device Locale](/configuration/device-locale.md)) | | `--orientation ` | Device orientation, `0` (portrait) or `90` (landscape). Android only (see [Orientation](/configuration/orientation.md)) | | `--google-play` | Use a Google Play-enabled device. Android only (see [Google Play APIs](/configuration/google-play-apis.md)) | | `--runner-type ` | Runner type to use (see [Runner Types](/configuration/runner-type.md)) | ### Flows | Flag | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `--flows ` | Comma-separated list of flow files to run (alternative to positional arg) | | `--config ` | Path to a `config.yaml` workspace config file (see [Workspace Configuration](/configuration/workspace-config.md)) | | `--exclude-flows ` | Comma-separated list of flow files or sub-directories to exclude | | `--include-tags ` | Only run flows with these tags (comma-separated) | | `--exclude-tags ` | Skip flows with these tags (comma-separated) | ### Test Configuration | Flag | Description | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `--maestro-version ` | Maestro version to use, or `latest` (see [Maestro Versions](/configuration/maestro-versions.md)) | | `--env ` | Environment variables to pass to the test. Repeat for multiple values | | `--metadata ` | Arbitrary metadata to attach to the run (shown in the console). Repeat for multiple values | | `--name ` | Name for this upload (shown in the console) | | `--retry ` | Retry failed tests up to `n` times (free of charge). Max `2` (see [Retry Strategies](/advanced/retry-strategies.md)) | ### 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 ` | Git branch name for this run | | `--commit-sha ` | Git commit SHA for this run | | `--repo-name ` | Repository in `owner/repo` format (e.g. `acme/my-app`) | | `--pr-number ` | Pull request number | | `--pr-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](/advanced/chrome-onboarding.md)) | | `--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 | ### 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](/advanced/async-execution.md)) | | `--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 (`_dcd.json` by default). Exits `0` even if the test run fails; infrastructure errors still exit `1` | | `--json-file-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 ` | Generate and download a report. Options: `junit`, `html`, `html-detailed`, `allure` (see [Report Formats](/test-artifacts-and-reports/report-formats.md)) | | `--junit-path ` | Output path for the JUnit report (requires `--report junit`) | | `--html-path ` | Output path for the HTML report (requires `--report html` or `html-detailed`) | | `--allure-path ` | Output path for the Allure report (requires `--report allure`) | | `--download-artifacts ` | Download test artifacts after completion (see [Artifacts](/test-artifacts-and-reports/artifacts.md)) | | `--artifacts-path ` | Output path for the artifacts zip (default `./artifacts.zip`). Requires `--download-artifacts` | | `--debug` | Enable verbose debug logging | ## Examples **Android:** ```bash dcd cloud app.apk flows/ --android-device pixel-7 --android-api-level 34 ``` **iOS:** ```bash dcd cloud app.zip flows/ --ios-device iphone-16 --ios-version 18 ``` **Filter by tag:** ```bash dcd cloud app.apk flows/ --include-tags smoke ``` **Reuse a previously uploaded binary:** ```bash dcd cloud flows/ --app-binary-id 67894274-b789-4c1e-80d4-da8998998999 ``` **Save results to JSON:** ```bash dcd cloud app.apk flows/ --json-file --json-file-name results.json ```