@autifyhq/aximo-cli 0.5.0 → 0.7.0

package/README.md

@@ -64,46 +64,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 via adb)     |
-| `aximo mobile setup`         | Install the Appium drivers used to drive phones        |
-| `aximo mobile doctor`        | Diagnose Appium prerequisites (adb, SDK, driver)       |
-| `aximo mobile register`      | Register a connected Android phone as an Aximo device  |
-| `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.
 
@@ -355,16 +356,22 @@ Normal for brief network blips — the agent retries with exponential backoff (1
 - Confirm outbound WebSocket on 443 isn't blocked: `aximo device doctor` runs a handshake probe.
 
 **Python download or pip install fails (corporate proxy).**
-The embedded Python is fetched from `github.com/astral-sh/python-build-standalone/releases`; packages come from PyPI. Behind a proxy:
+The embedded Python is fetched from `github.com/astral-sh/python-build-standalone/releases` and packages come from PyPI, so `aximo device setup` needs outbound access to both. On a network that only reaches the internet through a proxy, set the standard proxy variables — the CLI, pip, and the desktop agent all honor them:
 
 ```bash
 # macOS / Linux
-~/.aximo/python/bin/python3 -m pip config set global.proxy http://your-proxy:port
+export HTTPS_PROXY=http://your-proxy:port
+export HTTP_PROXY=http://your-proxy:port
 
-# Windows
-%USERPROFILE%\.aximo\python\python.exe -m pip config set global.proxy http://your-proxy:port
+# Windows (PowerShell)
+$env:HTTPS_PROXY = "http://your-proxy:port"
+$env:HTTP_PROXY  = "http://your-proxy:port"
 ```
 
+Loopback and a private-range `AXIMO_BASE_URL` (e.g. an on-prem `172.30.x.x` server) are always reached directly, so you don't have to list them in `NO_PROXY`. If your proxy performs TLS interception, also point `NODE_EXTRA_CA_CERTS` at the proxy's CA so the download's certificate verifies.
+
+If the proxy cannot reach GitHub at all, ask your network team to allow-list both `github.com` and its release-asset CDN `release-assets.githubusercontent.com` — the download redirects from the former to the latter, so allow-listing only `github.com` is not enough.
+
 To retry from a clean slate: `aximo device reset --python && aximo device setup`.
 
 **Device shows online, but tests fail on screenshot / click.**
@@ -394,11 +401,11 @@ Default `$AXIMO_HOME` is `~/.aximo` on macOS/Linux, `%USERPROFILE%\.aximo` on Wi
 
 > Devices are registered per-environment (see [Configuration](#configuration)) — a device registered against sandbox can't connect to production and vice versa.
 
-## Mobile (local Android phone)
+## Mobile (local Android phone or iPhone)
 
-The `mobile` commands let you register a **physically-connected Android phone** 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) (UiAutomator2) server — useful for running mobile tests against your own handset instead of a Device Farm device.
+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.
 
-> **Android only today.** iOS local devices are not yet supported — `aximo mobile register --platform ios` is blocked, and registration accepts only `--platform android`. (The Appium XCUITest plumbing is partially present but disabled; iOS local devices are planned for a future release.)
+> **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.
 
@@ -406,34 +413,158 @@ Terminology note: **`aximo mobile list`** shows phones plugged into _this_ machi
 
 - **Node.js 20+**, plus `aximo-cli` installed globally (see [Install](#install)).
 - **An Aximo API key**, configured via `aximo configure` or env vars.
-- **A USB-connected Android phone** with **USB debugging** enabled in Developer Options, plugged in, and authorized (accept the "Allow USB debugging?" prompt on the phone).
-- **adb** (Android platform-tools) on your `PATH` — Appium delegates to it. Install via `brew install --cask android-platform-tools` (macOS), your distro's `adb` package (Linux), or the Android Studio SDK Manager (Windows).
-- **The Android SDK**, with `ANDROID_HOME` (or `ANDROID_SDK_ROOT`) set — e.g. installed via Android Studio. Appium's UiAutomator2 driver requires it even though adb is already on PATH.
+- **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** 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.
+
+### Set up your computer (Android)
+
+You only need **`adb`** and the **Android SDK** on the machine running `aximo mobile connect`. Appium delegates to `adb`, and its UiAutomator2 driver needs the SDK (even though `adb` is already on `PATH`).
+
+**macOS**
+
+```bash
+# Option A — standalone platform-tools (just adb):
+brew install --cask android-platform-tools
+# 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):
+echo 'export ANDROID_HOME="$HOME/Library/Android/sdk"' >> ~/.zshrc
+echo 'export PATH="$PATH:$ANDROID_HOME/platform-tools"'  >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Linux**
+
+```bash
+# Debian/Ubuntu — adb from the distro (or download platform-tools from Google):
+sudo apt-get install -y android-tools-adb
+# Install the SDK via Android Studio or sdkmanager, then export its path:
+echo 'export ANDROID_HOME="$HOME/Android/Sdk"' >> ~/.bashrc
+echo 'export PATH="$PATH:$ANDROID_HOME/platform-tools"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+**Windows**
+
+- Install **Android Studio** (bundles the SDK + platform-tools), or download the standalone **SDK Platform-Tools** zip from Google.
+- Set `ANDROID_HOME` to the SDK path (e.g. `%LOCALAPPDATA%\Android\Sdk`) and add `%ANDROID_HOME%\platform-tools` to `PATH` via _System Properties → Environment Variables_.
+
+> `aximo mobile doctor` auto-detects the SDK at the standard locations above, so `ANDROID_HOME` is optional when you use the defaults — but setting it explicitly is the most reliable. Confirm `adb` works with `adb version`.
+
+### Set up your computer (iOS)
+
+iOS local devices are **macOS-only** (device control delegates to Xcode's toolchain). Setup is two steps — no env vars:
+
+```bash
+# 1. Xcode (full app, from the App Store) + accept the license:
+sudo xcodebuild -license accept
+
+# 2. Sign into Xcode with your Apple ID and create a development certificate:
+#    Xcode → Settings → Accounts → + (your Apple ID)
+#    → Manage Certificates… → + → Apple Development
+```
 
-> The Appium server is bundled with the CLI, and the UiAutomator2 driver is installed by `aximo mobile setup` — you don't manage Appium yourself.
+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:
+
+```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)
+```
+
+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). Devices below iOS 17 skip the tunnel entirely. 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
+
+Exact labels vary by manufacturer and Android version, but the flow is:
+
+1. **Unlock Developer options** — open **Settings → About phone** and tap **Build number** seven times until you see "You are now a developer".
+2. **Turn on USB debugging** — open **Settings → System → Developer options** and enable **USB debugging**.
+3. **Connect and authorize** — plug the phone into your computer with a **data-capable** USB cable, then tap **Allow** on the "Allow USB debugging?" prompt on the phone (tick "Always allow from this computer" to skip it next time).
+4. **Verify the computer sees it**:
+   ```bash
+   adb devices        # or: aximo mobile list
+   ```
+   The phone should appear in state **`device`**. **`unauthorized`** → re-accept the prompt on the phone; **`offline`** → re-plug the cable and unlock the screen. Emulators are not supported — connect a physical phone.
+
+> Keep the phone **unlocked** the first time you run a session: the initial command installs Appium's UiAutomator2 helper and creates the automation session on the device.
 
 ### First-time setup
 
 ```bash
-aximo mobile setup                          # installs the UiAutomator2 Appium driver
-aximo mobile doctor                         # checks adb / Android SDK / driver / bundled server
+aximo mobile setup                          # installs the Appium driver(s) for your platform(s)
+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 / devicectl / discovered signing
 ```
 
-`setup` installs the Appium driver, then prints what (if anything) is still missing. `doctor` is the first thing to run when anything's off — it reports the bundled Appium server, the UiAutomator2 driver, `adb`, and the Android SDK in one shot, 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
 
 ```bash
-aximo mobile list                                            # see connected phones + their adb serials
+aximo mobile list                                            # see connected phones (adb serials / iOS udids)
+
+# Android:
 aximo mobile register --name "My Pixel" --platform android   # --platform defaults to android
+# iOS:
+aximo mobile register --name "My iPhone" --platform ios      # targets the single connected iPhone
+
 aximo mobile connect                                         # starts managed Appium + opens the tunnel
 # 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` 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.
 
+### Testing your own app
+
+Unlike Device Farm, a local phone runs the apps already installed on it. To test your own build, install it first:
+
+```bash
+aximo mobile install --app ./app-debug.apk    # Android: adb install -r
+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
+# Android:
+aximo session create --platform ANDROID --user-device-id DEVICE_ID --bundle-id com.example.app \
+  --project-id PROJECT_ID --title "Smoke" --prompt "Sign in and open settings"
+# iOS:
+aximo session create --platform IOS --user-device-id DEVICE_ID --bundle-id com.example.MyApp \
+  --project-id PROJECT_ID --title "Smoke" --prompt "Sign in and open settings"
+```
+
 ### Managing devices
 
 ```bash
@@ -443,14 +574,15 @@ aximo mobile unregister --device-id DEVICE_ID # target a specific device when se
 
 ### Flags reference
 
-| Command                   | Flags                                                                               |
-| ------------------------- | ----------------------------------------------------------------------------------- |
-| `aximo mobile list`       | _(none)_                                                                            |
-| `aximo mobile setup`      | _(none)_                                                                            |
-| `aximo mobile doctor`     | _(none)_                                                                            |
-| `aximo mobile register`   | `--name <name>` (required), `--platform android` (default), `--serial <adb-serial>` |
-| `aximo mobile connect`    | `--device-id <id>` (required only if multiple devices are registered)               |
-| `aximo mobile unregister` | `--device-id <id>` (defaults to the locally registered device)                      |
+| Command                   | Flags                                                                                                |
+| ------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `aximo mobile list`       | _(none)_                                                                                             |
+| `aximo mobile setup`      | `--platform android \| ios` (optional; installs both drivers by default)                             |
+| `aximo mobile doctor`     | `--platform android \| ios` (optional; checks both by default)                                       |
+| `aximo mobile register`   | `--name <name>` (required), `--platform android \| ios` (default android), `--serial`/`--udid`       |
+| `aximo mobile install`    | `--app <path-to-.apk\|.ipa>` (required), `--platform android \| ios` (inferred), `--serial`/`--udid` |
+| `aximo mobile connect`    | `--device-id <id>` (required only if multiple devices are registered)                                |
+| `aximo mobile unregister` | `--device-id <id>` (defaults to the locally registered device)                                       |
 
 ## MCP server
 

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { defineCommand, runMain } from "citty";
 import pkg from "../package.json" with { type: "json" };
+import { installProxySupport } from "./proxy.js";
 // citty's --help prints to stdout; route to stderr for `mcp` since its stdout
 // is JSON-RPC.
 const args = process.argv.slice(2);
@@ -34,4 +35,7 @@ const main = defineCommand({
         mcp: () => import("./commands/mcp/index.js").then((m) => m.default),
     },
 });
+// Honor HTTP_PROXY / HTTPS_PROXY / NO_PROXY for every fetch the CLI makes (the
+// embedded-Python download, API calls). No-op unless a proxy is configured.
+await installProxySupport();
 runMain(main);

package/dist/client.d.ts

@@ -16,3 +16,5 @@ export interface ClientDeps {
 }
 export declare function request<T>(path: string, options?: RequestOptions, deps?: ClientDeps): Promise<T>;
 export declare function requestBuffer(path: string, deps?: ClientDeps): Promise<Buffer>;
+/** Authenticated GET that streams the response body to a file (no full-buffering). */
+export declare function requestToFile(path: string, destPath: string, deps?: ClientDeps): Promise<void>;

package/dist/client.js

@@ -88,3 +88,36 @@ export async function requestBuffer(path, deps = {}) {
     }
     return Buffer.from(await res.arrayBuffer());
 }
+/** Authenticated GET that streams the response body to a file (no full-buffering). */
+export async function requestToFile(path, destPath, deps = {}) {
+    const apiKey = deps.apiKey ?? getApiKey();
+    const baseUrl = deps.baseUrl ?? getBaseUrl();
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const url = buildUrl(baseUrl, path);
+    // 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);
+    }
+    if (!res.body)
+        throw new Error(`Empty response body from ${path}`);
+    const { Readable } = await import("node:stream");
+    const { pipeline } = await import("node:stream/promises");
+    const { createWriteStream } = await import("node:fs");
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
+}

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

@@ -1,7 +1,14 @@
 import { getBaseUrl } from "../../client.js";
 import { formatError } from "../../output.js";
 import { AppiumController } from "../../mobile-control/appium-controller.js";
-import { startAppiumServer } from "../../mobile-control/appium-server.js";
+import { installUploadedApp } from "../../mobile-control/app-install.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 } 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";
@@ -31,40 +38,145 @@ export function resolveDeviceConfig(deviceId) {
     }
     return { ok: true, config: only };
 }
-export function buildController(config, endpoint) {
-    return new AppiumController({ endpoint, platform: config.platform, target: config.target });
+export function buildController(config, endpoint, iosSigning, wdaLocalPort) {
+    return new AppiumController({
+        endpoint,
+        platform: config.platform,
+        target: config.target,
+        ...(config.platform === "ios"
+            ? { iosSigning: iosSigning ?? resolveIosSigning(), ...(wdaLocalPort ? { wdaLocalPort } : {}) }
+            : {}),
+    });
 }
-// A blocking check is any hard failure, plus a missing UiAutomator2 driver
+// A blocking check is any hard failure, plus a missing automation driver
 // (only a warning for `doctor`, but a hard prerequisite for connecting).
-function isBlockingCheck(check) {
+function isBlockingCheck(check, driverName) {
     if (check.status === "fail")
         return true;
-    return check.name === "uiautomator2 driver" && check.status === "warn";
+    return check.name === driverName && check.status === "warn";
 }
-async function assertAndroidPrerequisites() {
-    const report = await runMobileDoctor({ platform: "android" });
+async function assertPrerequisites(platform) {
+    const driverName = platform === "ios" ? "xcuitest driver" : "uiautomator2 driver";
+    const report = await runMobileDoctor({ platform });
     const checks = report.ok ? report.data.checks : [];
-    const blockers = checks.filter(isBlockingCheck);
+    const blockers = checks.filter((c) => isBlockingCheck(c, driverName));
     if (blockers.length === 0)
         return;
     const lines = blockers.map((c) => `  - ${c.message}${c.hint ? `\n      ${c.hint}` : ""}`);
-    throw new Error(`Missing Appium prerequisites:\n${lines.join("\n")}\n` +
-        "Run `aximo mobile setup` and/or fix the above, then re-run. " +
-        "(`aximo mobile doctor` for details.)");
+    const setup = platform === "ios" ? "aximo mobile setup --platform ios" : "aximo mobile setup";
+    const doctor = platform === "ios" ? "aximo mobile doctor --platform ios" : "aximo mobile doctor";
+    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) {
-    if (config.platform === "android") {
-        await assertAndroidPrerequisites();
+    await assertPrerequisites(config.platform);
+    let iosMajor = null;
+    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();
+            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 }) => {
+                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 {

package/dist/commands/mobile/connect.js

@@ -1,4 +1,5 @@
 import { defineCommand } from "citty";
+import { mobileErrorHint } from "../../mobile-control/mobile-errors.js";
 import { formatError, printResult } from "../../output.js";
 import { connectWithConfig, resolveDeviceConfig } from "./connect-core.js";
 const IOS_PHYSICAL_WARNING = "Driving a physical iPhone goes through Appium's XCUITest driver, which builds and " +
@@ -29,7 +30,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);
+            printResult(formatError("api_error", message, true, mobileErrorHint(message, resolved.config.platform)));
         }
     },
 });

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

@@ -15,8 +15,11 @@ 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>>;
 declare const _default: import("citty").CommandDef<{