@autifyhq/aximo-cli 0.6.0 → 0.8.0

package/README.md

@@ -34,6 +34,8 @@ aximo session get SESSION_ID
 
 Get your API key from **Settings → API Keys** in the [Aximo dashboard](https://aximo.autify.com).
 
+Want to run tests on **your own hardware** instead of the cloud? See [Device (BYOD)](#device-byod--bring-your-own-device) to register this desktop (Windows/macOS/Linux), or [Mobile](#mobile-local-android-phone-or-iphone) to drive a USB-connected Android phone or iPhone — each section starts with the exact prerequisites for a fresh machine.
+
 ## Configuration
 
 Each credential resolves independently: the value in `$AXIMO_HOME/config.json` (written by `aximo configure`) wins, then the environment variable, then the default.
@@ -64,47 +66,47 @@ Credentials and device registrations are **per-environment** — to switch betwe
 
 Run `aximo <command> --help` for detailed usage. `aximo schema [command.path]` returns machine-readable argument introspection (e.g. `aximo schema session.create`).
 
-| Command                      | Description                                             |
-| ---------------------------- | ------------------------------------------------------- |
-| `aximo configure`            | Save credentials to `$AXIMO_HOME/config.json`           |
-| `aximo health check`         | Check API reachability                                  |
-| `aximo project list`         | List organization projects                              |
-| `aximo session create`       | Create and queue a test session                         |
-| `aximo session get`          | Get session status                                      |
-| `aximo session save-as-case` | Save a finished session as a reusable test case         |
-| `aximo case create`          | Create a test case                                      |
-| `aximo case delete`          | Delete a test case                                      |
-| `aximo plan create`          | Create a test plan                                      |
-| `aximo plan add-case`        | Add a case to a plan                                    |
-| `aximo plan remove-case`     | Remove a case from a plan                               |
-| `aximo trigger case run`     | Trigger a dashboard-created test case                   |
-| `aximo trigger case get`     | Get triggered case status                               |
-| `aximo trigger plan run`     | Trigger a test plan                                     |
-| `aximo trigger plan get`     | Get plan run status                                     |
-| `aximo upload create`        | Create an upload slot for an APK/IPA                    |
-| `aximo upload list`          | List previously uploaded apps                           |
-| `aximo upload get`           | Poll upload processing status                           |
-| `aximo upload put`           | Upload binary file to the slot                          |
-| `aximo upload submit`        | Finalize upload and trigger processing                  |
-| `aximo device list`          | List mobile devices from Device Farm                    |
-| `aximo device setup`         | First-time BYOD onboarding (API + Python + register)    |
-| `aximo device register`      | Register this machine as a BYOD device                  |
-| `aximo device connect`       | Start the BYOD agent and connect to the relay           |
-| `aximo device status`        | List your organization's BYOD devices                   |
-| `aximo device ping`          | Check your BYOD device's server-side status             |
-| `aximo device doctor`        | Diagnose BYOD setup (env, Python, relay, status)        |
-| `aximo device logs`          | Show the BYOD agent log                                 |
-| `aximo device unregister`    | Remove a BYOD device server-side + clear local creds    |
-| `aximo device reset`         | Remove BYOD local state (Python, deps, credentials)     |
-| `aximo mobile list`          | List physically-connected phones (Android adb, iOS idb) |
-| `aximo mobile setup`         | Install the Appium drivers used to drive phones         |
-| `aximo mobile doctor`        | Diagnose prerequisites (adb/idb, SDK/Xcode, driver)     |
-| `aximo mobile register`      | Register a connected Android phone or iPhone            |
-| `aximo mobile install`       | Install an app (.apk via adb, .ipa via idb)             |
-| `aximo mobile connect`       | Start managed Appium + open the tunnel for the phone    |
-| `aximo mobile unregister`    | Remove a local mobile device server-side + local creds  |
-| `aximo schema`               | Show CLI surface as JSON                                |
-| `aximo mcp`                  | Run a stdio MCP server for agents (see below)           |
+| Command                      | Description                                                    |
+| ---------------------------- | -------------------------------------------------------------- |
+| `aximo configure`            | Save credentials to `$AXIMO_HOME/config.json`                  |
+| `aximo health check`         | Check API reachability                                         |
+| `aximo project list`         | List organization projects                                     |
+| `aximo session create`       | Create and queue a test session                                |
+| `aximo session get`          | Get session status                                             |
+| `aximo session save-as-case` | Save a finished session as a reusable test case                |
+| `aximo case create`          | Create a test case                                             |
+| `aximo case delete`          | Delete a test case                                             |
+| `aximo plan create`          | Create a test plan                                             |
+| `aximo plan add-case`        | Add a case to a plan                                           |
+| `aximo plan remove-case`     | Remove a case from a plan                                      |
+| `aximo trigger case run`     | Trigger a dashboard-created test case                          |
+| `aximo trigger case get`     | Get triggered case status                                      |
+| `aximo trigger plan run`     | Trigger a test plan                                            |
+| `aximo trigger plan get`     | Get plan run status                                            |
+| `aximo upload create`        | Create an upload slot for an APK/IPA                           |
+| `aximo upload list`          | List previously uploaded apps                                  |
+| `aximo upload get`           | Poll upload processing status                                  |
+| `aximo upload put`           | Upload binary file to the slot                                 |
+| `aximo upload submit`        | Finalize upload and trigger processing                         |
+| `aximo device list`          | List mobile devices from Device Farm                           |
+| `aximo device setup`         | First-time BYOD onboarding (API + Python + register)           |
+| `aximo device register`      | Register this machine as a BYOD device                         |
+| `aximo device connect`       | Start the BYOD agent and connect to the relay                  |
+| `aximo device status`        | List your organization's BYOD devices                          |
+| `aximo device ping`          | Check your BYOD device's server-side status                    |
+| `aximo device doctor`        | Diagnose BYOD setup (env, Python, relay, status)               |
+| `aximo device logs`          | Show the BYOD agent log                                        |
+| `aximo device unregister`    | Remove a BYOD device server-side + clear local creds           |
+| `aximo device reset`         | Remove BYOD local state (Python, deps, credentials)            |
+| `aximo mobile list`          | List physically-connected phones (Android adb, iOS devicectl)  |
+| `aximo mobile setup`         | Install the Appium drivers used to drive phones                |
+| `aximo mobile doctor`        | Diagnose prerequisites (adb/Xcode/devicectl, signing, driver)  |
+| `aximo mobile register`      | Register a connected Android phone or iPhone                   |
+| `aximo mobile install`       | Install an app (.apk via adb, .ipa auto-re-signed + devicectl) |
+| `aximo mobile connect`       | Start managed Appium + open the tunnel for the phone           |
+| `aximo mobile unregister`    | Remove a local mobile device server-side + local creds         |
+| `aximo schema`               | Show CLI surface as JSON                                       |
+| `aximo mcp`                  | Run a stdio MCP server for agents (see below)                  |
 
 Mutating commands support `--json '<raw body>'` for direct OpenAPI payloads and `--dry-run` to preview requests without executing.
 
@@ -208,9 +210,9 @@ Terminology note: **`aximo device list` returns mobile devices** from Device Far
 
 ### Prerequisites
 
-- **Node.js 20+**, plus `aximo-cli` installed globally (see [Install](#install)).
+- **Node.js 20.18+**, plus `aximo-cli` installed globally (see [Install](#install)).
 - **An Aximo API key**, configured via `aximo configure` or env vars.
-- **Active desktop session** — the agent uses `pyautogui` for screenshots and input, so the screen must be unlocked and awake while tests run.
+- **Active desktop session** — the agent uses `pyautogui` for screenshots and input, so the screen must be unlocked and awake while tests run. On **macOS**, grant the terminal **Accessibility** and **Screen Recording** permissions (System Settings → Privacy & Security) — without them actions silently do nothing.
 - **Outbound WebSocket to port 443** — most corporate firewalls allow this; if yours doesn't, see [Troubleshooting](#byod-troubleshooting).
 
 > Python is **not** a prerequisite. On first `connect` (or via `device setup`), the CLI downloads a self-contained CPython build into `$AXIMO_HOME/python/` (~35 MB download, ~130 MB installed) and installs the required packages. Your system Python is untouched.
@@ -405,20 +407,20 @@ Default `$AXIMO_HOME` is `~/.aximo` on macOS/Linux, `%USERPROFILE%\.aximo` on Wi
 
 The `mobile` commands let you register a **physically-connected Android phone or iPhone** as an Aximo device and drive it locally, over the same gateway tunnel as desktop BYOD. Aximo's agent controls the phone through a CLI-managed [Appium](https://appium.io) server — UiAutomator2 for Android, XCUITest for iOS — useful for running mobile tests against your own handset instead of a Device Farm device.
 
-> **iOS is macOS-only and needs Xcode + an Apple Developer account.** Driving a physical iPhone goes through Appium's XCUITest driver, which builds and code-signs a WebDriverAgent (WDA) runner onto the device. That requires macOS, Xcode, an Apple Developer **Team ID**, and a WDA bundle id backed by a valid provisioning profile — set via the `AXIMO_IOS_*` env vars below. Android has no such requirement, so iOS setup is heavier; everything after setup (`register` → `connect` → run) works the same on both platforms.
+> **iOS is macOS-only and needs Xcode + an Apple ID.** Driving a physical iPhone requires a development-signed WebDriverAgent (WDA) runner on the device — an Apple platform rule, not an Aximo one. The CLI is **zero-config about it**: it discovers your signing identity and Team ID from the keychain, finds or mints provisioning profiles via Xcode automatic signing, and (on iOS 17+) preinstalls a prebuilt WDA with no Xcode build. A free/personal Apple ID works. Android has no signing requirement, so iOS setup is heavier; everything after setup (`register` → `connect` → run) works the same on both platforms.
 
 Terminology note: **`aximo mobile list`** shows phones plugged into _this_ machine; **`aximo device list`** (under [Device / BYOD](#device-byod--bring-your-own-device)) returns mobile devices from AWS Device Farm. Don't confuse the two.
 
 ### Prerequisites
 
-- **Node.js 20+**, plus `aximo-cli` installed globally (see [Install](#install)).
+- **Node.js 20.18+**, plus `aximo-cli` installed globally (see [Install](#install)).
 - **An Aximo API key**, configured via `aximo configure` or env vars.
 - **A USB-connected phone**:
   - **Android** — **USB debugging** enabled and authorized — see [Enable USB debugging on the phone](#enable-usb-debugging-on-the-phone).
   - **iOS** — **Developer Mode** enabled (Settings → Privacy & Security) and the computer trusted.
 - **On the machine that runs `aximo mobile connect`**:
   - **Android** — `adb` and the Android SDK, with `ANDROID_HOME` set — see [Set up your computer (Android)](#set-up-your-computer-android).
-  - **iOS** — macOS with **Xcode** + command line tools, **`idb`**, and the `AXIMO_IOS_*` signing env vars — see [Set up your computer (iOS)](#set-up-your-computer-ios).
+  - **iOS** — macOS with **Xcode** and an Apple ID signed into it — see [Set up your computer (iOS)](#set-up-your-computer-ios).
 
 > The Appium server is bundled with the CLI; `aximo mobile setup` installs the UiAutomator2 (Android) and/or XCUITest (iOS) driver — you don't install or manage Appium yourself.
 
@@ -429,12 +431,13 @@ You only need **`adb`** and the **Android SDK** on the machine running `aximo mo
 **macOS**
 
 ```bash
-# Option A — standalone platform-tools (just adb):
-brew install --cask android-platform-tools
+# Option A — standalone SDK Platform-Tools (no Android Studio): download the zip from
+# https://developer.android.com/tools/releases/platform-tools and unzip it so adb ends up at
+# ~/Library/Android/sdk/platform-tools/adb  (the driver needs this SDK layout, not just adb on PATH)
 # Option B — full Android Studio (also installs the SDK):
 brew install --cask android-studio
 
-# Point ANDROID_HOME at the SDK (Android Studio's default location shown):
+# Point ANDROID_HOME at the SDK (both options above use this location):
 echo 'export ANDROID_HOME="$HOME/Library/Android/sdk"' >> ~/.zshrc
 echo 'export PATH="$PATH:$ANDROID_HOME/platform-tools"'  >> ~/.zshrc
 source ~/.zshrc
@@ -460,30 +463,43 @@ source ~/.bashrc
 
 ### Set up your computer (iOS)
 
-iOS local devices are **macOS-only** (Appium's XCUITest driver delegates to Xcode). You need Xcode, `idb`, and the signing env vars.
+iOS local devices are **macOS-only** (device control delegates to Xcode's toolchain). Setup is two steps — no env vars:
 
 ```bash
-# 1. Xcode + command line tools (XCUITest builds WebDriverAgent with them):
-xcode-select --install          # or install Xcode from the App Store, then: sudo xcodebuild -license accept
-
-# 2. idb — discovers connected iPhones and installs .ipa builds:
-brew tap facebook/fb && brew install idb-companion
-pipx install fb-idb             # or: pip install fb-idb
+# 1. Xcode (full app, from the App Store) + accept the license:
+sudo xcodebuild -license accept
 
-# 3. Signing config for WebDriverAgent (required for a physical iPhone):
-export AXIMO_IOS_TEAM_ID="ABCDE12345"     # your Apple Developer Team ID (developer.apple.com/account → Membership)
-# Optional overrides (sensible defaults shown):
-export AXIMO_IOS_SIGNING_ID="Apple Development"
-export AXIMO_IOS_WDA_BUNDLE_ID="com.facebook.WebDriverAgentRunner"
-# Optional: reuse a prebuilt WDA to skip per-session rebuilds:
-# export AXIMO_IOS_DERIVED_DATA_PATH="$HOME/Library/Developer/Xcode/DerivedData/WebDriverAgent-xxxx"
+# 2. Sign into Xcode with your Apple ID and create a development certificate:
+#    Xcode → Settings → Accounts → + (your Apple ID)
+#    → Manage Certificates… → + → Apple Development
 ```
 
-`AXIMO_IOS_TEAM_ID` is the load-bearing setting: the XCUITest driver uses it (with the signing id and WDA bundle id) to build and sign WebDriverAgent so it can run on the device. The WDA bundle id must be associated with a valid provisioning profile under that team. Run `aximo mobile doctor --platform ios` to confirm Xcode, `idb`, and the signing config are all present.
+Everything else is discovered automatically at `connect`/`install` time:
+
+- **Signing identity & Team ID** — read from the keychain (`security find-identity`); no `AXIMO_IOS_TEAM_ID` needed. On a machine with several teams, set `AXIMO_IOS_TEAM_ID` (or MobileLink's `XCODE_TEAM_ID`) to pick one.
+- **Provisioning profiles** — scanned from disk and matched against the device; when none fits, the CLI **mints one via Xcode automatic signing** (first run takes a minute or two; requires the Apple ID signed into Xcode).
+- **WebDriverAgent** — on **iOS 17+**, a prebuilt WDA matching the bundled driver is downloaded, re-signed with your identity, and **preinstalled — no Xcode build, no iOS platform download**. Older devices fall back to the classic Xcode build (cached per device under `$AXIMO_HOME/ios-wda/<udid>/`). A WDA bundle id is derived per team (existing `*.WebDriverAgentRunner` profiles are reused); override with `AXIMO_IOS_WDA_BUNDLE_ID`.
+- **App installs** — `.ipa` files that aren't signed for your device are **re-signed automatically** (see `aximo mobile install` below).
+- **Device discovery** — via Xcode's `devicectl`; `idb` is only an optional fallback (`brew install idb-companion && pipx install fb-idb`).
+
+Optional overrides / opt-outs:
 
-> Already set up Autify's MobileLink? The CLI also reads MobileLink's names as fallbacks — `XCODE_TEAM_ID`, `XCODE_SIGN_ID`, `WDA_BUNDLE_ID` — so an existing host needs no reconfiguration. `AXIMO_IOS_*` takes precedence when both are set.
+```bash
+# export AXIMO_IOS_TEAM_ID="ABCDE12345"   # pick a team on multi-team machines (else auto-detected)
+# export AXIMO_IOS_SIGNING_ID="Apple Development"
+# export AXIMO_IOS_WDA_BUNDLE_ID="com.<you>.WebDriverAgentRunner"  # else derived/reused automatically
+# export AXIMO_IOS_NO_RESIGN=1            # never re-sign the app under test
+# export AXIMO_IOS_NO_PREINSTALLED_WDA=1  # force the classic Xcode build flow for WDA
+# export AXIMO_IOS_DERIVED_DATA_PATH=...  # pin a prebuilt WDA DerivedData (build flow)
+# export AXIMO_IOS_NO_WDA_CACHE=1         # disable the WDA build cache (build flow)
+# export AXIMO_IOS_SKIP_TUNNEL=1          # don't auto-start the RemoteXPC device tunnel (you manage it)
+```
 
-> First connect to a physical iPhone is slow: Xcode builds and installs WebDriverAgent (a minute or two). If the build fails on signing, open `WebDriverAgent.xcodeproj` in Xcode once, pick your team, and let it auto-manage signing — or set `AXIMO_IOS_DERIVED_DATA_PATH` to a prebuilt WDA.
+Run `aximo mobile doctor --platform ios` to see what was discovered (identity, team, WDA id) and what's missing; failed commands include a `hint` naming the exact fix.
+
+> **On-device steps you can't skip** (Apple requires them once per phone): enable **Developer Mode** (Settings → Privacy & Security → Developer Mode; the phone restarts), tap **Trust This Computer**, and — after the first install of an app signed by your team — **trust the developer certificate** (Settings → General → VPN & Device Management → your "Apple Development" profile → Trust; the phone needs internet). On **free/personal teams** profiles expire every ~7 days; the CLI re-mints them automatically, but a re-mint **resets the certificate trust**, so expect that trust tap to recur weekly. Free teams are also capped at 10 App IDs per week.
+>
+> On **iOS 17+**, `aximo mobile connect` also starts a small **device tunnel that needs admin rights** — it prompts once for your macOS password / Touch ID (reused on later runs, so at most once per boot). The tunnel deliberately keeps running after `connect` exits; stop it anytime with `sudo pkill -f tunnel-creation`. Devices below iOS 17 skip the tunnel entirely, and Android never uses it. If anything mentions "iOS X is not installed", run `xcodebuild -downloadPlatform iOS` (only the classic build flow needs it).
 
 ### Enable USB debugging on the phone
 
@@ -507,10 +523,10 @@ aximo mobile setup                          # installs the Appium driver(s) for
 aximo mobile doctor                         # checks tooling / drivers / bundled server
 # Limit to one platform if you only test on one:
 aximo mobile setup  --platform ios          # installs only the XCUITest driver
-aximo mobile doctor --platform ios          # checks Xcode / idb / signing config
+aximo mobile doctor --platform ios          # checks Xcode / devicectl / discovered signing
 ```
 
-`setup` installs the Appium driver(s) — UiAutomator2 for Android, XCUITest for iOS — then prints what (if anything) is still missing. `doctor` is the first thing to run when anything's off: for Android it reports `adb` and the Android SDK; for iOS it reports `xcrun`/Xcode, `idb`, and your `AXIMO_IOS_TEAM_ID` signing config — alongside the bundled Appium server and driver — and exits non-zero if a required check fails.
+`setup` installs the Appium driver(s) — UiAutomator2 for Android, XCUITest for iOS — then prints what (if anything) is still missing. `doctor` is the first thing to run when anything's off: for Android it reports `adb` and the Android SDK; for iOS it reports `xcrun`/Xcode, the discovered signing identity/team, and whether the iOS device tunnel is running — alongside the bundled Appium server and driver — and exits non-zero if a required check fails.
 
 ### Registering and connecting
 
@@ -526,7 +542,7 @@ aximo mobile connect                                         # starts managed Ap
 # Ctrl+C to disconnect
 ```
 
-`register` writes credentials to `$AXIMO_HOME/mobile-devices/<deviceId>.json` (mode `0600`). It targets the single connected phone by default — pass `--serial` (Android) or `--udid` (iOS) to pick a specific one when several are attached. `connect` re-checks prerequisites, starts the managed Appium server, and opens the tunnel; it runs until Ctrl+C. If you have more than one registered phone, pass `--device-id` to choose which to connect.
+`register` writes credentials to `$AXIMO_HOME/mobile-devices/<deviceId>.json` (mode `0600`). It targets the single connected phone by default — pass `--serial` (Android) or `--udid` (iOS) to pick a specific one when several are attached. `connect` re-checks prerequisites, then — on iOS 17+ — ensures the device tunnel is running (prompting once for admin the first time), starts the managed Appium server, and opens the gateway tunnel to Aximo; it runs until Ctrl+C. If you have more than one registered phone, pass `--device-id` to choose which to connect.
 
 Once connected, create a **mobile session in Aximo targeting this local device** — the agent routes its actions through the tunnel to the phone over Appium.
 
@@ -536,9 +552,11 @@ Unlike Device Farm, a local phone runs the apps already installed on it. To test
 
 ```bash
 aximo mobile install --app ./app-debug.apk    # Android: adb install -r
-aximo mobile install --app ./MyApp.ipa         # iOS: idb install (the .ipa must be signed for the device)
+aximo mobile install --app ./MyApp.ipa         # iOS: auto-re-signed for the device if needed, installed via devicectl
 ```
 
+On iOS the CLI inspects the `.ipa` first: if its embedded profile already covers the device it installs as-is; otherwise it **re-signs it with your discovered identity** (the same thing AWS Device Farm does to every upload — so the exact `.ipa` you upload there works here). When the bundle id has to be remapped (free teams), launches by the original bundle id are translated automatically during `connect` sessions, and the JSON result reports both ids. App Store downloads are FairPlay-encrypted and can't be re-signed — use a development/ad-hoc build. Opt out with `AXIMO_IOS_NO_RESIGN=1`.
+
 Then create the session with the app's bundle id / package name as `--bundle-id` — the agent launches it on startup before the test begins:
 
 ```bash

package/dist/client.js

@@ -94,7 +94,22 @@ export async function requestToFile(path, destPath, deps = {}) {
     const baseUrl = deps.baseUrl ?? getBaseUrl();
     const fetchImpl = deps.fetchImpl ?? fetch;
     const url = buildUrl(baseUrl, path);
-    const res = await fetchImpl(url, { method: "GET", headers: { "x-api-key": apiKey } });
+    // Redirects (e.g. to a presigned S3 URL) are followed manually WITHOUT the
+    // x-api-key header — fetch only strips authorization/cookie on cross-origin
+    // redirects, so auto-follow would leak the org API key to the storage host.
+    let res = await fetchImpl(url, {
+        method: "GET",
+        headers: { "x-api-key": apiKey },
+        redirect: "manual",
+    });
+    // Only true redirects — other 3xx (e.g. 304 Not Modified) carry no Location
+    // and must fall through to normal handling instead of throwing here.
+    if ([301, 302, 303, 307, 308].includes(res.status)) {
+        const location = res.headers.get("location");
+        if (!location)
+            throw new Error(`Redirect from ${path} is missing a Location header`);
+        res = await fetchImpl(new URL(location, url).toString(), { method: "GET" });
+    }
     if (!res.ok) {
         const retryAfter = res.headers.get("retry-after") ?? undefined;
         throw httpError(res.status, await errorMessage(res), retryAfter);

package/dist/commands/mobile/connect-core.d.ts

@@ -1,5 +1,6 @@
 import type { ErrorEnvelope } from "../../types.js";
 import type { MobileController } from "../../mobile-control/controller.js";
+import { type IosSigningConfig } from "../../mobile-control/ios-signing.js";
 import { type MobileDeviceConfig } from "./paths.js";
 export declare function getTunnelOrigin(): string;
 interface ConfigOk {
@@ -7,6 +8,6 @@ interface ConfigOk {
     config: MobileDeviceConfig;
 }
 export declare function resolveDeviceConfig(deviceId: string | undefined): ConfigOk | ErrorEnvelope;
-export declare function buildController(config: MobileDeviceConfig, endpoint: string): MobileController;
+export declare function buildController(config: MobileDeviceConfig, endpoint: string, iosSigning?: IosSigningConfig, wdaLocalPort?: number | (() => Promise<number>)): MobileController;
 export declare function connectWithConfig(config: MobileDeviceConfig): Promise<void>;
 export {};

package/dist/commands/mobile/connect-core.js

@@ -2,8 +2,13 @@ import { getBaseUrl } from "../../client.js";
 import { formatError } from "../../output.js";
 import { AppiumController } from "../../mobile-control/appium-controller.js";
 import { installUploadedApp } from "../../mobile-control/app-install.js";
-import { startAppiumServer } from "../../mobile-control/appium-server.js";
-import { resolveIosSigning } from "../../mobile-control/ios-signing.js";
+import { pickFreePort, startAppiumServer } from "../../mobile-control/appium-server.js";
+import { withBundleIdTranslation } from "../../mobile-control/bundle-id-map.js";
+import { getIosDeviceInfo, iosMajorVersion } from "../../mobile-control/ios-devicectl.js";
+import { ensureIosTunnel, TUNNEL_STOP_COMMAND } from "../../mobile-control/ios-tunnel.js";
+import { resolveIosSigning, resolveIosSigningAuto, } from "../../mobile-control/ios-signing.js";
+import { resolveWdaCaching } from "../../mobile-control/ios-wda-cache.js";
+import { resolvePreinstalledWdaStrategy } from "../../mobile-control/ios-wda-preinstall.js";
 import { runControlTunnel } from "../../mobile-control/tunnel.js";
 import { runMobileDoctor } from "./doctor.js";
 import { listMobileDeviceConfigs, readMobileDeviceConfig, } from "./paths.js";
@@ -23,9 +28,8 @@ export function resolveDeviceConfig(deviceId) {
         return formatError("validation_error", 'No registered devices. Register one first: aximo mobile register --name "My Pixel" --platform android', false);
     }
     if (all.length > 1) {
-        return formatError("validation_error", `Multiple devices registered; pass --device-id. Registered: ${all
-            .map((c) => `${c.name} (${c.deviceId})`)
-            .join(", ")}`, false);
+        const lines = all.map((c) => `  - ${c.name} (${c.platform}) — device-id: ${c.deviceId}`);
+        return formatError("validation_error", `Multiple devices are registered on this machine; pass --device-id to pick one:\n${lines.join("\n")}`, false, `Re-run with --device-id, e.g. --device-id ${all[0]?.deviceId}`);
     }
     const only = all[0];
     if (!only) {
@@ -33,12 +37,14 @@ export function resolveDeviceConfig(deviceId) {
     }
     return { ok: true, config: only };
 }
-export function buildController(config, endpoint) {
+export function buildController(config, endpoint, iosSigning, wdaLocalPort) {
     return new AppiumController({
         endpoint,
         platform: config.platform,
         target: config.target,
-        ...(config.platform === "ios" ? { iosSigning: resolveIosSigning() } : {}),
+        ...(config.platform === "ios"
+            ? { iosSigning: iosSigning ?? resolveIosSigning(), ...(wdaLocalPort ? { wdaLocalPort } : {}) }
+            : {}),
     });
 }
 // A blocking check is any hard failure, plus a missing automation driver
@@ -61,28 +67,125 @@ async function assertPrerequisites(platform) {
     throw new Error(`Missing ${platform} prerequisites:\n${lines.join("\n")}\n` +
         `Run \`${setup}\` and/or fix the above, then re-run. (\`${doctor}\` for details.)`);
 }
+/**
+ * Preflight the physical device state via devicectl and fail with the exact
+ * on-device fix when an onboarding toggle is missing. Returns the device's iOS
+ * major version (null when devicectl can't see the device).
+ */
+async function preflightIosDevice(udid) {
+    const info = await getIosDeviceInfo(udid);
+    if (!info)
+        return null;
+    if (info.developerModeEnabled === false) {
+        throw new Error("Developer Mode is disabled on the iPhone. Enable it on the device: Settings → " +
+            "Privacy & Security → Developer Mode → On (the phone restarts), then re-run.");
+    }
+    if (info.paired === false) {
+        throw new Error("The iPhone is not paired with this Mac. Unlock the phone, reconnect the USB cable, " +
+            "and tap 'Trust This Computer'.");
+    }
+    return iosMajorVersion(info.osVersion);
+}
 export async function connectWithConfig(config) {
     await assertPrerequisites(config.platform);
+    let iosMajor = null;
+    let tunnelRunning = false;
+    if (config.platform === "ios") {
+        iosMajor = await preflightIosDevice(config.target);
+        // Physical iPhones on iOS 17+ need the RemoteXPC tunnel before XCUITest can
+        // reach WebDriverAgent; start it (prompting for admin) unless one is running.
+        // Older devices use the classic lockdown path — no tunnel, no admin prompt.
+        if (iosMajor !== null && iosMajor < 17) {
+            console.error(`iOS ${iosMajor} device — skipping the RemoteXPC tunnel (not needed).`);
+        }
+        else {
+            const tunnel = await ensureIosTunnel();
+            tunnelRunning = tunnel.started || tunnel.reused;
+            if (tunnel.reused)
+                console.error("Reusing the running iOS device tunnel.");
+        }
+    }
     const useDrivers = config.platform === "ios" ? ["xcuitest"] : ["uiautomator2"];
     const server = await startAppiumServer({ useDrivers });
-    const controller = buildController(config, server.endpoint);
+    // WDA strategy ladder: (1) preinstalled prebuilt runner — no xcodebuild at all
+    // (iOS 17+, needs a discovered identity; profiles are minted on demand);
+    // (2) cached xcodebuild output (usePrebuiltWDA) when still valid; (3) full
+    // driver-managed xcodebuild. Everything is discovered from the keychain and
+    // installed profiles; env vars only override.
+    let iosSigning;
+    let wdaLocalPort;
+    if (config.platform === "ios") {
+        const signing = await resolveIosSigningAuto({ udid: config.target });
+        if (signing.teamId) {
+            console.error(`Signing as team ${signing.teamId} (WDA id ${signing.wdaBundleId}).`);
+        }
+        else {
+            console.error("No Apple signing identity found — physical-device WebDriverAgent signing will fail. " +
+                "Open Xcode → Settings → Accounts to add your Apple ID (see `aximo mobile doctor`).");
+        }
+        const preinstalled = await resolvePreinstalledWdaStrategy(signing, {
+            udid: config.target,
+            iosMajor,
+            log: (message) => console.error(message),
+        });
+        if (preinstalled) {
+            iosSigning = preinstalled;
+            console.error("Using the preinstalled WebDriverAgent (no Xcode build needed).");
+        }
+        else {
+            iosSigning = signing.teamId
+                ? await resolveWdaCaching(signing, { udid: config.target })
+                : signing;
+            if (iosSigning.usePrebuiltWDA)
+                console.error("Reusing the cached WebDriverAgent build.");
+        }
+        // Resolved lazily right before the Appium session is created — a port picked
+        // here would sit unbound (and stealable) until the first remote action.
+        wdaLocalPort = pickFreePort;
+    }
+    // Re-signing can remap bundle ids; launches from the backend use the original.
+    const installedBundleIds = new Map();
+    const rawController = buildController(config, server.endpoint, iosSigning, wdaLocalPort);
+    const controller = config.platform === "ios"
+        ? withBundleIdTranslation(rawController, installedBundleIds)
+        : rawController;
     try {
+        // Warm up the device session before connecting to Aximo so WDA build/signing/
+        // trust problems surface here — with a clear, actionable message — instead of
+        // failing opaquely on the first server-driven action.
+        if (config.platform === "ios") {
+            console.error("Preparing WebDriverAgent on the device…");
+            await controller.screenshot();
+            console.error("Device is ready.");
+        }
         await runControlTunnel({
             wsUrl: getTunnelOrigin(),
             deviceToken: config.deviceToken,
             deviceName: config.name,
             controller,
             installApp: async ({ uploadId }) => {
-                await installUploadedApp({
+                const result = await installUploadedApp({
                     uploadId,
                     platform: config.platform,
                     target: config.target,
+                    log: (message) => console.error(message),
                 });
+                if (result.originalBundleId &&
+                    result.installedBundleId &&
+                    result.originalBundleId !== result.installedBundleId) {
+                    installedBundleIds.set(result.originalBundleId, result.installedBundleId);
+                    console.error(`App re-signed for this device: ${result.originalBundleId} installed as ` +
+                        `${result.installedBundleId}.`);
+                }
             },
         });
     }
     finally {
         await controller.close();
         await server.stop();
+        if (tunnelRunning) {
+            console.error("The iOS device tunnel is still running in the background (admin-started; the next " +
+                `connect won't prompt again). Stop it anytime with: ${TUNNEL_STOP_COMMAND}`);
+        }
     }
 }

package/dist/commands/mobile/connect.js

@@ -1,6 +1,8 @@
 import { defineCommand } from "citty";
-import { formatError, printResult } from "../../output.js";
+import { mobileErrorHint } from "../../mobile-control/mobile-errors.js";
+import { formatError } from "../../output.js";
 import { connectWithConfig, resolveDeviceConfig } from "./connect-core.js";
+import { printMobileResult } from "./output.js";
 const IOS_PHYSICAL_WARNING = "Driving a physical iPhone goes through Appium's XCUITest driver, which builds and " +
     "installs a WebDriverAgent runner on the device. The device must have Developer Mode " +
     "enabled (Settings → Privacy & Security) and be trusted, and WDA needs an Apple Developer " +
@@ -19,7 +21,7 @@ export default defineCommand({
     async run({ args }) {
         const resolved = resolveDeviceConfig(args["device-id"]);
         if (!resolved.ok) {
-            printResult(resolved);
+            printMobileResult(resolved);
             return;
         }
         const warning = iosPhysicalWarning(resolved.config);
@@ -29,7 +31,8 @@ export default defineCommand({
             await connectWithConfig(resolved.config);
         }
         catch (error) {
-            printResult(formatError("api_error", error instanceof Error ? error.message : String(error), true));
+            const message = error instanceof Error ? error.message : String(error);
+            printMobileResult(formatError("api_error", message, true, mobileErrorHint(message, resolved.config.platform)));
         }
     },
 });

package/dist/commands/mobile/connect.test.js

@@ -61,7 +61,7 @@ describe("resolveDeviceConfig", () => {
         if (result.ok)
             expect(result.config.deviceId).toBe("only-1");
     });
-    it("requires --device-id when multiple are registered", () => {
+    it("requires --device-id when multiple are registered, listing each candidate", () => {
         for (const id of ["a", "b"]) {
             writeMobileDeviceConfig({
                 deviceId: id,
@@ -73,6 +73,12 @@ describe("resolveDeviceConfig", () => {
         }
         const ambiguous = resolveDeviceConfig(undefined);
         expect(ambiguous.ok).toBe(false);
+        if (!ambiguous.ok) {
+            expect(ambiguous.error.message).toContain("pass --device-id");
+            expect(ambiguous.error.message).toContain("device-id: a");
+            expect(ambiguous.error.message).toContain("device-id: b");
+            expect(ambiguous.error.hint).toContain("--device-id");
+        }
         const picked = resolveDeviceConfig("b");
         expect(picked.ok).toBe(true);
         if (picked.ok)

package/dist/commands/mobile/doctor.d.ts

@@ -15,10 +15,14 @@ export interface MobileDoctorReport {
         info: number;
     };
 }
+export declare function checkIosTunnel(isHealthy?: (port: number) => Promise<boolean>): Promise<Check>;
 export interface RunMobileDoctorOptions {
     platform?: "ios" | "android" | undefined;
+    /** Injectable tunnel probe for tests. */
+    isTunnelHealthy?: (port: number) => Promise<boolean>;
 }
 export declare function runMobileDoctor(options?: RunMobileDoctorOptions): Promise<Envelope<MobileDoctorReport>>;
+export declare function renderDoctorReport(data: MobileDoctorReport): string;
 declare const _default: import("citty").CommandDef<{
     readonly platform: {
         readonly type: "string";