From 277e23c15a524f04bb33c1396456147608ada658 Mon Sep 17 00:00:00 2001
From: finalerock44 <77282157+finalerock44@users.noreply.github.com>
Date: Fri, 10 Jul 2026 18:03:57 +0100
Subject: [PATCH] docs: device matrix via --ios-config/--android-config (#1105)

Document running a whole suite across N devices in one upload with repeatable
--ios-config/--android-config, replacing the shell-loop workaround. Covers the
no-cross-product rule, one-platform-per-upload, flow-override precedence, the
cost preview, and the --json device field.
---
 getting-started/devices-configuration.md | 39 ++++++++++++++++++------
 1 file changed, 30 insertions(+), 9 deletions(-)

diff --git a/getting-started/devices-configuration.md b/getting-started/devices-configuration.md
index a09afb1..17e825f 100644
--- a/getting-started/devices-configuration.md
+++ b/getting-started/devices-configuration.md
@@ -84,17 +84,38 @@ dcd cloud app.zip test.yaml --ios-device ipad-pro-6th-gen
 
 ### Targeting a single flow
 
-The flags above set the device for the **whole upload**. When only one flow needs a particular device then that flow can name its own device inits YAML instead. See [per-flow-devices.md](../configuration/per-flow-devices.md).
-To run your **entire** suite against more than one device, submit one upload per device:
+The flags above set the device for the **whole upload**. When only one flow needs a particular device then that flow can name its own device in its YAML instead. See [per-flow-devices.md](../configuration/per-flow-devices.md).
+
+### Running your whole suite across a device matrix
+
+To run your **entire** suite against several devices in one go, pass a repeatable `--ios-config <device>:<version>` (or `--android-config <device>:<apiLevel>`) for each device you want. Every flow runs once per config, all under **one upload** — one console entry, one pass/fail rollup, results comparable side by side.
 
 ```bash
-for device in iphone-16-pro iphone-16-pro-max; do
-  dcd cloud --app-binary-id <id> ./flows \
-    --ios-device "$device" --ios-version 18 --async
-done
+dcd cloud --app-binary-id <id> ./flows \
+  --ios-config iphone-16-pro:18 \
+  --ios-config iphone-16-pro:26 \
+  --ios-config iphone-16-pro-max:26
+# → one upload, 3 devices × N flows
 ```
 
-{% hint style="warning" %}
-`--async` matters here. Without it, each `dcd cloud` blocks on its own poll loop waiting for
-results, so the uploads run one after another instead of concurrently.
+Android works the same way — append `:play` to target a Google Play device for that cell:
+
+```bash
+dcd cloud --app-binary-id <id> ./flows \
+  --android-config pixel-7:34 \
+  --android-config pixel-7:34:play
+```
+
+Each `--ios-config` / `--android-config` is **one explicit device cell** — there is no cross-product. `--ios-config iphone-15:17 --ios-config iphone-16-plus:26` runs exactly those two configs, nothing else. Every config is validated against the [compatibility tables above](#ios-devices) before anything runs, so an unsupported pair fails fast, naming it, and no partial run is submitted.
+
+Before submitting, the CLI prints the number of cells and the estimated **cost** — a device matrix bills one run per (flow × config), so a 4-config matrix over 10 flows is 40 runs.
+
+A few rules:
+
+- **One platform per upload.** A matrix runs one app binary, so `--ios-config` and `--android-config` can't be combined in the same run.
+- **A flow that names its own device wins.** If a flow sets its own device via [`DEVICECLOUD_OVERRIDE_*`](../configuration/per-flow-devices.md), it runs once on that device and is excluded from the matrix.
+- **`--json` distinguishes devices.** Under `--json`, each entry in `tests[]` carries a `device` object, so the same flow run on two devices is no longer ambiguous.
+
+{% hint style="info" %}
+Prefer separate uploads (e.g. in CI, one per shard)? You can still submit one `dcd cloud` per device with `--ios-device` / `--ios-version` and `--async` — but a single matrix upload keeps the results together and comparable.
 {% endhint %}