# Cloud Test Tools

The `dcd_*` tools run Maestro tests in the cloud and read their results. [`dcd mcp`](https://docs.devicecloud.dev/ai-agents-and-mcp/connect-an-ai-agent.md) serves them. This page lists each tool's parameters and return shape. The tools that drive a cloud device are in [Agent Devices Tools](https://docs.devicecloud.dev/ai-agents-and-mcp/agent-devices-tools.md).

All tools return pretty-printed JSON as their text payload. Failures come back as an error result the agent can read and react to — a failing tool never tears down the server, so an agent can recover and retry.

> **Warning:**
>
> The `dcd_*` tools are in beta, so they may change.

## dcd_list_devices

Discover the devices, OS versions, and Maestro versions available on DeviceCloud. Agents should call this **before** `dcd_run_cloud_test` so they pass valid device values.

Takes no parameters.

Returns `{ ios, android, androidPlay, maestro }`. `ios`, `android` and `androidPlay` each map a device, such as `pixel-10`, to the OS versions it runs. `androidPlay` covers the [Google Play](https://docs.devicecloud.dev/devices/google-play-apis.md) images: a device with an empty list has none. `maestro` holds `supportedVersions`, `defaultVersion` and `latestVersion`. See [Devices & OS Versions](https://docs.devicecloud.dev/devices/devices-and-os-versions.md) and [Maestro Versions](https://docs.devicecloud.dev/configuration/maestro-versions.md).

## dcd_list_runs

List recent flow uploads for your team, most recent first.

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Filter by upload name. Supports a `*` wildcard, e.g. `nightly-*` |
| `from` | string | Only uploads created on or after this ISO 8601 date, e.g. `2024-01-01` |
| `to` | string | Only uploads created on or before this ISO 8601 date |
| `limit` | integer | Maximum uploads to return, 1–100 (default `20`) |
| `offset` | integer | Uploads to skip, for pagination (default `0`) |

Returns `{ uploads: [{ id, name, created_at, consoleUrl }], total, limit, offset }`. Use a returned `id` with `dcd_get_status` or `dcd_download_artifacts`.

## dcd_get_status

Get the status and per-test results of a single upload. This is the polling primitive: after an async `dcd_run_cloud_test`, call this until `status` leaves `PENDING` / `QUEUED` / `RUNNING`.

| Parameter | Type | Description |
|-----------|------|-------------|
| `uploadId` | string | UUID of the upload, as returned by `dcd_run_cloud_test` or `dcd_list_runs` |
| `name` | string | Name of the upload to look up |

Provide **exactly one** of `uploadId` or `name` — passing both, or neither, is an error.

Returns `{ status, name, createdAt, tests: [{ name, status, durationSeconds, failReason }] }`.

## dcd_download_artifacts

Download a completed run's artifacts zip (videos, logs and screenshots) to local disk, plus a formatted report if you ask for one. The artifacts zip is always downloaded; `report` adds a report on top of it. It reads cloud state and writes local files, so it stays available in [read-only mode](https://docs.devicecloud.dev/ai-agents-and-mcp/connect-an-ai-agent.md#read-only-mode).

| Parameter | Type | Description |
|-----------|------|-------------|
| `uploadId` | string | **Required.** UUID of the upload to download artifacts for |
| `type` | `ALL` \| `FAILED` | Which tests to include artifacts for (default `ALL`) |
| `artifactsPath` | string | Where to write the artifacts zip (default `./artifacts.zip`). A relative path is from the server's working directory, which your MCP client chooses, so prefer an absolute path |
| `report` | `junit` \| `allure` \| `html` | Also download a formatted report of this type. `allure` is deprecated, see [Deprecations & Removals](https://docs.devicecloud.dev/product-lifecycle/deprecations-and-removals.md) |
| `reportPath` | string | Where to write the report (defaults by type: `report.xml` for `junit`, `report.zip` for `html`, `report.html` for `allure`). The `html` report is a ZIP. A relative path works as for `artifactsPath` |

Returns `{ uploadId, artifactsPath, reportPath, warnings }`. A **non-empty `warnings` array means a download could not be produced** — most often because the run has no results yet. An empty array means success. See [Artifacts & Downloads](https://docs.devicecloud.dev/test-artifacts-and-reports/artifacts-and-downloads.md) and [Report formats](https://docs.devicecloud.dev/test-artifacts-and-reports/artifacts-and-downloads.md#report-formats).

## dcd_get_team_settings

Read how your team is set up: concurrency limits, test runtime, sign-in requirement, retry escalation, overage limit and connected integrations. It changes nothing, so it stays available in [read-only mode](https://docs.devicecloud.dev/ai-agents-and-mcp/connect-an-ai-agent.md#read-only-mode). An agent can use it to check limits before it plans a run.

Takes no parameters.

Returns `{ orgId, name, restricted, concurrency: { runners, pools }, testRuntime: { defaultMinutes, extendedMinutes }, integrations: { webhook, slack, github }, signInRequirement, retryEscalation, overage }`, the same object as [`GET /org/settings`](https://docs.devicecloud.dev/rest-api/team-settings.md#get-team-settings) and `dcd settings --json`. When `restricted` is `true` (a standard team member), `signInRequirement`, `retryEscalation` and `overage` are `null`. Owners, admins and API keys see them.

## dcd_run_cloud_test

Submit a Maestro flow, or a directory of flows, to run on DeviceCloud.

> **Warning:**
>
> This tool consumes test credits. It's annotated as destructive so clients can prompt before calling it, and it's hidden entirely in [read-only mode](https://docs.devicecloud.dev/ai-agents-and-mcp/connect-an-ai-agent.md#read-only-mode).

| Parameter | Type | Description |
|-----------|------|-------------|
| `flowFile` | string | **Required.** Path to a Maestro `.yaml`/`.yml` flow, or a directory of flows |
| `appFile` | string | Path to a local app binary — `.apk`, `.app`, or `.zip`. Mutually exclusive with `appBinaryId` |
| `appBinaryId` | string | ID of a previously uploaded binary. Mutually exclusive with `appFile` |
| `iosVersion` | string | iOS version, e.g. `26` |
| `iosDevice` | string | iOS device, e.g. `iphone-16` |
| `androidApiLevel` | string | Android API level, e.g. `34` |
| `androidDevice` | string | Android device, e.g. `pixel-10` |
| `googlePlay` | boolean | Use a [Google Play-enabled](https://docs.devicecloud.dev/devices/google-play-apis.md) Android image |
| `name` | string | A name for this run |
| `env` | string[] | [Environment variables](https://docs.devicecloud.dev/configuration/environment-variables.md) as `KEY=VALUE` strings |
| `includeTags` | string[] | Only run flows with these tags |
| `excludeTags` | string[] | Skip flows with these tags |
| `excludeFlows` | string[] | Flow paths/patterns to exclude |
| `maestroVersion` | string | Pin a specific [Maestro version](https://docs.devicecloud.dev/configuration/maestro-versions.md) |
| `retry` | integer | Auto-[retry](https://docs.devicecloud.dev/configuration/retry-strategies.md) failed tests, 0–2 |
| `runnerType` | `default` \| `m4` \| `m1` \| `cpu1` | [Runner type](https://docs.devicecloud.dev/devices/runner-types.md) (default `default`). |
| `priority` | `low` \| `normal` \| `high` | [Run priority](https://docs.devicecloud.dev/configuration/run-priority.md) (default `normal`). Reorders only your team's own queued runs. |
| `configFile` | string | Path to a [workspace config](https://docs.devicecloud.dev/configuration/workspace-configuration.md) |
| `ignoreShaCheck` | boolean | Force re-upload of the binary even if an identical one already exists |
| `encrypt` | boolean | Apply envelope encryption to the binary, flows and `env` values on your machine before upload. Omit it to follow `DCD_ENCRYPT`, then the default, which is on; pass `false` to turn it off (the upload is still encrypted in transit). See [Data Encryption](https://docs.devicecloud.dev/security-and-compliance/security-overview.md#data-encryption) |
| `dryRun` | boolean | Preview which flows would run, without submitting |
| `wait` | boolean | Block until the run completes instead of returning immediately (default `false`) |
| `waitTimeoutSeconds` | integer | Max seconds to wait when `wait` is true, 30–3600 (default `600`). A flow with [extended runtime](https://docs.devicecloud.dev/configuration/extended-runtime.md) can run for up to 20 minutes, so raise this when the run includes one |

You must provide either `appFile` or `appBinaryId` — not both, and not neither. A `dryRun` needs neither. Use [`dcd upload`](https://docs.devicecloud.dev/cli-reference/upload.md) or a previous run to get a reusable `appBinaryId`.

### Async by default

By default the tool returns as soon as the run is submitted:

```json
{ "uploadId": "...", "consoleUrl": "...", "status": "PENDING", "tests": [ ... ] }
```

Poll `dcd_get_status` with that `uploadId` until the status is terminal. This is the recommended shape for agents — it keeps the tool call short and avoids a long-blocking request.

Set `wait: true` to block instead. The tool polls every 10 seconds up to `waitTimeoutSeconds`, then returns with `timedOut: true` if the run hasn't finished. **The run continues in the cloud regardless** — a timeout is not a cancellation, and you can resume by polling `dcd_get_status` with the returned `uploadId`.

### Previewing a run

`dryRun: true` resolves the flows and returns them without submitting anything or spending credits:

```json
{
  "dryRun": true,
  "flows": [{ "file": "...", "flowName": "...", "tags": [ ... ] }],
  "sequentialFlowCount": 0
}
```

This is a cheap way for an agent to confirm it's about to run the flows you expect before it calls the billable path for real.
