@autifyhq/aximo-cli 0.5.0 → 0.6.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 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)           |
 
 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 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.
 
 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,143 @@ 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** + command line tools, **`idb`**, and the `AXIMO_IOS_*` signing env vars — 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** (Appium's XCUITest driver delegates to Xcode). You need Xcode, `idb`, and the signing 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
 
-> The Appium server is bundled with the CLI, and the UiAutomator2 driver is installed by `aximo mobile setup` — you don't manage Appium yourself.
+# 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
+
+# 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"
+```
+
+`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.
+
+> 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.
+
+> 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.
+
+### 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 / idb / signing config
 ```
 
-`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, `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.
 
 ### 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, 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.
 
 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: idb install (the .ipa must be signed for the device)
+```
+
+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 +559,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,21 @@ 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);
+    const res = await fetchImpl(url, { method: "GET", headers: { "x-api-key": apiKey } });
+    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.js

@@ -1,7 +1,9 @@
 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 { runControlTunnel } from "../../mobile-control/tunnel.js";
 import { runMobileDoctor } from "./doctor.js";
 import { listMobileDeviceConfigs, readMobileDeviceConfig, } from "./paths.js";
@@ -32,30 +34,35 @@ export function resolveDeviceConfig(deviceId) {
     return { ok: true, config: only };
 }
 export function buildController(config, endpoint) {
-    return new AppiumController({ endpoint, platform: config.platform, target: config.target });
+    return new AppiumController({
+        endpoint,
+        platform: config.platform,
+        target: config.target,
+        ...(config.platform === "ios" ? { iosSigning: resolveIosSigning() } : {}),
+    });
 }
-// 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.)`);
 }
 export async function connectWithConfig(config) {
-    if (config.platform === "android") {
-        await assertAndroidPrerequisites();
-    }
+    await assertPrerequisites(config.platform);
     const useDrivers = config.platform === "ios" ? ["xcuitest"] : ["uiautomator2"];
     const server = await startAppiumServer({ useDrivers });
     const controller = buildController(config, server.endpoint);
@@ -65,6 +72,13 @@ export async function connectWithConfig(config) {
             deviceToken: config.deviceToken,
             deviceName: config.name,
             controller,
+            installApp: async ({ uploadId }) => {
+                await installUploadedApp({
+                    uploadId,
+                    platform: config.platform,
+                    target: config.target,
+                });
+            },
         });
     }
     finally {

package/dist/commands/mobile/doctor.js

@@ -6,6 +6,7 @@ import { join } from "node:path";
 import { formatSuccess, printResult } from "../../output.js";
 import { importAppium } from "../../mobile-control/appium-import.js";
 import { getAppiumHome, resolveAndroidSdk } from "../../mobile-control/appium-server.js";
+import { resolveIosSigning } from "../../mobile-control/ios-signing.js";
 function which(cmd) {
     const probe = platform() === "win32" ? "where" : "which";
     const result = spawnSync(probe, [cmd], { encoding: "utf-8" });
@@ -97,15 +98,33 @@ function checkIos() {
         ? { name: "xcrun", status: "pass", message: xcrun }
         : {
             name: "xcrun",
-            status: "warn",
+            status: "fail",
             message: "xcrun not found",
-            hint: "Install Xcode command line tools: xcode-select --install. Appium's XCUITest driver delegates to Xcode.",
+            hint: "Install Xcode command line tools: xcode-select --install. Appium's XCUITest driver delegates to Xcode and cannot run without it.",
+        });
+    const idb = which("idb");
+    checks.push(idb
+        ? { name: "idb", status: "pass", message: idb }
+        : {
+            name: "idb",
+            status: "warn",
+            message: "idb not found",
+            hint: "Install idb (brew install idb-companion && pipx install fb-idb). It's used to discover connected iPhones and install .ipa builds.",
+        });
+    const teamId = resolveIosSigning().teamId;
+    checks.push(teamId
+        ? { name: "ios signing", status: "pass", message: `signing team id is set (${teamId})` }
+        : {
+            name: "ios signing",
+            status: "warn",
+            message: "no signing team id is set",
+            hint: "Driving a physical iPhone needs an Apple Developer Team ID to sign WebDriverAgent. Set AXIMO_IOS_TEAM_ID (or MobileLink's XCODE_TEAM_ID), and optionally AXIMO_IOS_SIGNING_ID / AXIMO_IOS_WDA_BUNDLE_ID.",
         });
     checks.push({
         name: "ios webdriveragent",
         status: "info",
         message: "Physical iPhones are driven via Appium's XCUITest driver, which builds and installs a WebDriverAgent runner on the device.",
-        hint: "WDA needs an Apple Developer signing identity; enable Developer Mode (Settings → Privacy & Security) and trust the device.",
+        hint: "Enable Developer Mode (Settings → Privacy & Security), trust this computer, and ensure the WDA bundle id is backed by a valid provisioning profile.",
     });
     return checks;
 }

package/dist/commands/mobile/index.js

@@ -7,6 +7,7 @@ export default defineCommand({
     subCommands: {
         list: () => import("./list.js").then((m) => m.default),
         register: () => import("./register.js").then((m) => m.default),
+        install: () => import("./install.js").then((m) => m.default),
         unregister: () => import("./unregister.js").then((m) => m.default),
         connect: () => import("./connect.js").then((m) => m.default),
         setup: () => import("./setup.js").then((m) => m.default),

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

@@ -0,0 +1,43 @@
+import { type ExecFn } from "../../mobile-control/exec.js";
+import type { Envelope } from "../../types.js";
+import type { MobilePlatform } from "./paths.js";
+export interface MobileInstallResult {
+    platform: MobilePlatform;
+    /** adb serial (Android). */
+    serial?: string;
+    /** device udid (iOS). */
+    udid?: string;
+    app: string;
+    output: string;
+}
+export interface MobileInstallOptions {
+    app?: string | undefined;
+    platform?: string | undefined;
+    serial?: string | undefined;
+    udid?: string | undefined;
+}
+/**
+ * Install an app on the connected phone: Android `.apk` via `adb install -r`,
+ * iOS `.ipa` via `idb install`. The iOS build must be signed for the device.
+ */
+export declare function runMobileInstall(options: MobileInstallOptions, exec?: ExecFn): Promise<Envelope<MobileInstallResult>>;
+declare const _default: import("citty").CommandDef<{
+    readonly app: {
+        readonly type: "string";
+        readonly description: "Path to the .apk or .ipa to install";
+        readonly required: true;
+    };
+    readonly platform: {
+        readonly type: "string";
+        readonly description: "android | ios (inferred from the file extension)";
+    };
+    readonly serial: {
+        readonly type: "string";
+        readonly description: "Android adb serial (defaults to the connected one)";
+    };
+    readonly udid: {
+        readonly type: "string";
+        readonly description: "iOS device udid (defaults to the connected one)";
+    };
+}>;
+export default _default;

package/dist/commands/mobile/install.js

@@ -0,0 +1,76 @@
+import { existsSync } from "node:fs";
+import { extname, resolve } from "node:path";
+import { defineCommand } from "citty";
+import { resolveAndroidSerial, resolveIosUdid } from "../../mobile-control/devices.js";
+import { execBinary } from "../../mobile-control/exec.js";
+import { formatError, formatSuccess, printResult } from "../../output.js";
+import { parsePlatformArg } from "./register-core.js";
+function inferPlatform(appPath) {
+    const ext = extname(appPath).toLowerCase();
+    if (ext === ".apk")
+        return "android";
+    if (ext === ".ipa")
+        return "ios";
+    return null;
+}
+/**
+ * Install an app on the connected phone: Android `.apk` via `adb install -r`,
+ * iOS `.ipa` via `idb install`. The iOS build must be signed for the device.
+ */
+export async function runMobileInstall(options, exec = execBinary) {
+    if (!options.app) {
+        return formatError("validation_error", "App path is required (--app <path-to-.apk|.ipa>).", false);
+    }
+    const appPath = resolve(options.app);
+    if (!existsSync(appPath)) {
+        return formatError("validation_error", `App not found: ${appPath}`, false);
+    }
+    const platform = options.platform ? parsePlatformArg(options.platform) : inferPlatform(appPath);
+    if (!platform) {
+        return formatError("validation_error", "Could not determine platform; pass --platform android|ios (or use a .apk/.ipa file).", false);
+    }
+    let target;
+    try {
+        target =
+            platform === "ios"
+                ? await resolveIosUdid(options.udid, exec)
+                : await resolveAndroidSerial(options.serial, exec);
+    }
+    catch (err) {
+        return formatError("validation_error", err instanceof Error ? err.message : String(err), false);
+    }
+    try {
+        const { stdout } = platform === "ios"
+            ? await exec("idb", ["install", "--udid", target, appPath])
+            : await exec("adb", ["-s", target, "install", "-r", appPath]);
+        return formatSuccess({
+            platform,
+            ...(platform === "ios" ? { udid: target } : { serial: target }),
+            app: appPath,
+            output: stdout.toString("utf-8").trim(),
+        });
+    }
+    catch (err) {
+        return formatError("api_error", err instanceof Error ? err.message : String(err), false);
+    }
+}
+export default defineCommand({
+    meta: {
+        name: "install",
+        description: "Install an app on the connected phone (.apk via adb, .ipa via idb)",
+    },
+    args: {
+        app: { type: "string", description: "Path to the .apk or .ipa to install", required: true },
+        platform: { type: "string", description: "android | ios (inferred from the file extension)" },
+        serial: { type: "string", description: "Android adb serial (defaults to the connected one)" },
+        udid: { type: "string", description: "iOS device udid (defaults to the connected one)" },
+    },
+    async run({ args }) {
+        printResult(await runMobileInstall({
+            app: args.app,
+            platform: args.platform,
+            serial: args.serial,
+            udid: args.udid,
+        }));
+    },
+});

package/dist/commands/mobile/install.test.d.ts

@@ -0,0 +1 @@
+export {};