@debugswift/ios-simulator-cli 1.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Joshua Yoes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# iOS Simulator CLI
+
+[![NPM Version](https://img.shields.io/npm/v/ios-simulator-cli)](https://www.npmjs.com/package/ios-simulator-cli)
+
+A command-line tool for interacting with iOS simulators. Control UI, capture screenshots and video, install apps, and inspect accessibility elements from your terminal or automation scripts.
+
+> **Security Notice**: Command injection vulnerabilities present in versions < 1.3.3 have been fixed. Please update to v1.3.3 or later. See [SECURITY.md](SECURITY.md) for details.
+
+## Installation
+
+### Homebrew (recommended)
+
+```bash
+brew install DebugSwift/ios-simulator-cli/ios-simulator-cli
+```
+
+To install the latest from `main`:
+
+```bash
+brew install --HEAD DebugSwift/ios-simulator-cli/ios-simulator-cli
+```
+
+### npm
+
+```bash
+npm install -g ios-simulator-cli
+```
+
+### From source
+
+```bash
+git clone https://github.com/DebugSwift/ios-simulator-cli
+cd ios-simulator-cli
+npm install
+npm run build
+npm link
+```
+
+## Prerequisites
+
+- macOS (iOS simulators are only available on macOS)
+- [Xcode](https://developer.apple.com/xcode/resources/) and iOS simulators installed
+- Facebook [IDB](https://fbidb.io/) tool ([install guide](https://fbidb.io/docs/installation))
+
+## Usage
+
+```bash
+ios-simulator-cli --help
+ios-simulator-cli --version
+```
+
+### Commands
+
+| Command | Description |
+| --- | --- |
+| `get-booted-sim-id` | Get the booted simulator UUID |
+| `open` | Open Simulator.app |
+| `ui describe-all` | Describe all UI accessibility elements |
+| `ui tap` | Tap at coordinates |
+| `ui type` | Input text |
+| `ui swipe` | Swipe gesture |
+| `ui describe-point` | Get element at coordinates |
+| `ui find-element` | Search accessibility tree |
+| `ui view` | Capture compressed screenshot (JPEG base64 or file) |
+| `screenshot` | Save screenshot to file |
+| `record-video` | Start video recording |
+| `stop-recording` | Stop video recording |
+| `install-app` | Install an app bundle (.app or .ipa) |
+| `launch-app` | Launch an app by bundle identifier |
+
+### Examples
+
+```bash
+# Get the booted simulator
+ios-simulator-cli get-booted-sim-id
+
+# Open Simulator.app
+ios-simulator-cli open
+
+# Describe the current screen
+ios-simulator-cli ui describe-all
+
+# Tap at coordinates
+ios-simulator-cli ui tap --x 200 --y 400
+
+# Type text
+ios-simulator-cli ui type "Hello World"
+
+# Swipe down
+ios-simulator-cli ui swipe --x-start 200 --y-start 600 --x-end 200 --y-end 200
+
+# Find a button by label
+ios-simulator-cli ui find-element --search "Search" --type Button
+
+# Save a screenshot
+ios-simulator-cli screenshot --output home.png
+
+# Capture a compressed view to a file
+ios-simulator-cli ui view --output screen.jpg
+
+# Start and stop recording
+ios-simulator-cli record-video --output demo.mp4
+ios-simulator-cli stop-recording
+
+# Install and launch an app
+ios-simulator-cli install-app --app-path ./MyApp.app
+ios-simulator-cli launch-app --bundle-id com.apple.mobilesafari --terminate-running
+ios-simulator-cli launch-app --bundle-id com.example.app --env FOO=bar --env BAZ=qux
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Example |
+| --- | --- | --- |
+| `IOS_SIMULATOR_CLI_DEFAULT_OUTPUT_DIR` | Default directory for relative output paths (screenshots, recordings). Defaults to `~/Downloads`. | `~/Code/project/tmp` |
+| `IOS_SIMULATOR_CLI_IDB_PATH` | Custom path to the IDB executable. Defaults to `idb` on PATH. | `~/bin/idb` |
+
+Legacy `IOS_SIMULATOR_MCP_*` environment variables are still supported for output directory and IDB path.
+
+## License
+
+MIT

package/build/index.js

@@ -0,0 +1,694 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildLaunchArgs = buildLaunchArgs;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const node_util_1 = require("node:util");
+const zod_1 = require("zod");
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const fs_1 = __importDefault(require("fs"));
+const VERSION = require("../package.json").version;
+function buildLaunchArgs({ udid, bundleId, terminateRunning, env, }) {
+    const args = ["launch"];
+    if (terminateRunning) {
+        args.push("--terminate-running-process");
+    }
+    const simctlEnv = {};
+    if (env) {
+        const entries = Object.entries(env)
+            .map(([key, value]) => [key.trim(), value])
+            .sort(([a], [b]) => a.localeCompare(b));
+        for (const [key, value] of entries) {
+            if (!key) {
+                throw new Error("Environment variable keys must be non-empty.");
+            }
+            simctlEnv[`SIMCTL_CHILD_${key}`] = value;
+        }
+    }
+    args.push(udid, bundleId);
+    return { args, env: simctlEnv };
+}
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const UDID_REGEX = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/;
+const udidSchema = zod_1.z.string().regex(UDID_REGEX).optional();
+const TMP_ROOT_DIR = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), "ios-simulator-cli-"));
+async function run(cmd, args, options = {}) {
+    const mergedEnv = options.env
+        ? { ...process.env, ...options.env }
+        : process.env;
+    const { stdout, stderr } = await execFileAsync(cmd, args, {
+        shell: false,
+        env: mergedEnv,
+    });
+    return {
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+    };
+}
+function getIdbPath() {
+    const customPath = process.env.IOS_SIMULATOR_CLI_IDB_PATH ??
+        process.env.IOS_SIMULATOR_MCP_IDB_PATH;
+    if (customPath) {
+        const expandedPath = customPath.startsWith("~/")
+            ? path_1.default.join(os_1.default.homedir(), customPath.slice(2))
+            : customPath;
+        if (!fs_1.default.existsSync(expandedPath)) {
+            throw new Error(`Custom IDB path specified in IOS_SIMULATOR_CLI_IDB_PATH does not exist: ${expandedPath}`);
+        }
+        return expandedPath;
+    }
+    return "idb";
+}
+async function idb(...args) {
+    return run(getIdbPath(), args);
+}
+function toError(input) {
+    if (input instanceof Error)
+        return input;
+    if (typeof input === "object" &&
+        input &&
+        "message" in input &&
+        typeof input.message === "string")
+        return new Error(input.message);
+    return new Error(JSON.stringify(input));
+}
+function troubleshootingLink() {
+    return "https://github.com/DebugSwift/ios-simulator-cli/blob/main/TROUBLESHOOTING.md";
+}
+function errorWithTroubleshooting(message) {
+    return `${message}\n\nFor help, see ${troubleshootingLink()}`;
+}
+async function getBootedDevice() {
+    const { stdout, stderr } = await run("xcrun", ["simctl", "list", "devices"]);
+    if (stderr)
+        throw new Error(stderr);
+    const lines = stdout.split("\n");
+    for (const line of lines) {
+        if (line.includes("Booted")) {
+            const match = line.match(/\(([-0-9A-F]+)\)/);
+            if (match) {
+                const deviceId = match[1];
+                const deviceName = line.split("(")[0].trim();
+                return {
+                    name: deviceName,
+                    id: deviceId,
+                };
+            }
+        }
+    }
+    throw Error("No booted simulator found");
+}
+async function getBootedDeviceId(deviceId) {
+    let actualDeviceId = deviceId;
+    if (!actualDeviceId) {
+        const { id } = await getBootedDevice();
+        actualDeviceId = id;
+    }
+    if (!actualDeviceId) {
+        throw new Error("No booted simulator found and no deviceId provided");
+    }
+    return actualDeviceId;
+}
+function ensureAbsolutePath(filePath) {
+    if (path_1.default.isAbsolute(filePath)) {
+        return filePath;
+    }
+    if (filePath.startsWith("~/")) {
+        return path_1.default.join(os_1.default.homedir(), filePath.slice(2));
+    }
+    let defaultDir = path_1.default.join(os_1.default.homedir(), "Downloads");
+    const customDefaultDir = process.env.IOS_SIMULATOR_CLI_DEFAULT_OUTPUT_DIR ??
+        process.env.IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR;
+    if (customDefaultDir) {
+        if (customDefaultDir.startsWith("~/")) {
+            defaultDir = path_1.default.join(os_1.default.homedir(), customDefaultDir.slice(2));
+        }
+        else {
+            defaultDir = customDefaultDir;
+        }
+    }
+    return path_1.default.join(defaultDir, filePath);
+}
+function parseEnvPairs(values) {
+    const env = {};
+    for (const pair of values ?? []) {
+        const separator = pair.indexOf("=");
+        if (separator <= 0) {
+            throw new Error(`Invalid env pair "${pair}". Expected format KEY=VALUE.`);
+        }
+        env[pair.slice(0, separator)] = pair.slice(separator + 1);
+    }
+    return env;
+}
+async function cmdGetBootedSimId() {
+    const { id, name } = await getBootedDevice();
+    console.log(`Booted Simulator: "${name}". UUID: "${id}"`);
+}
+async function cmdOpenSimulator() {
+    await run("open", ["-a", "Simulator.app"]);
+    console.log("Simulator.app opened successfully");
+}
+async function cmdUiDescribeAll(udid) {
+    const actualUdid = await getBootedDeviceId(udidSchema.parse(udid));
+    const { stdout } = await idb("ui", "describe-all", "--udid", actualUdid, "--json", "--nested");
+    console.log(stdout);
+}
+async function cmdUiTap(options) {
+    const actualUdid = await getBootedDeviceId(udidSchema.parse(options.udid));
+    const { stderr } = await idb("ui", "tap", "--udid", actualUdid, ...(options.duration ? ["--duration", options.duration] : []), "--json", "--", String(options.x), String(options.y));
+    if (stderr)
+        throw new Error(stderr);
+    console.log("Tapped successfully");
+}
+async function cmdUiType(text, udid) {
+    zod_1.z.string().max(500).regex(/^[\x20-\x7E]+$/).parse(text);
+    const actualUdid = await getBootedDeviceId(udidSchema.parse(udid));
+    const { stderr } = await idb("ui", "text", "--udid", actualUdid, "--", text);
+    if (stderr)
+        throw new Error(stderr);
+    console.log("Typed successfully");
+}
+async function cmdUiSwipe(options) {
+    const actualUdid = await getBootedDeviceId(udidSchema.parse(options.udid));
+    const { stderr } = await idb("ui", "swipe", "--udid", actualUdid, ...(options.duration ? ["--duration", options.duration] : []), ...(options.delta != null ? ["--delta", String(options.delta)] : []), "--json", "--", String(options.xStart), String(options.yStart), String(options.xEnd), String(options.yEnd));
+    if (stderr)
+        throw new Error(stderr);
+    console.log("Swiped successfully");
+}
+async function cmdUiDescribePoint(options) {
+    const actualUdid = await getBootedDeviceId(udidSchema.parse(options.udid));
+    const { stdout, stderr } = await idb("ui", "describe-point", "--udid", actualUdid, "--json", "--", String(options.x), String(options.y));
+    if (stderr)
+        throw new Error(stderr);
+    console.log(stdout);
+}
+async function cmdUiFindElement(options) {
+    const actualUdid = await getBootedDeviceId(udidSchema.parse(options.udid));
+    const { stdout } = await idb("ui", "describe-all", "--udid", actualUdid, "--json", "--nested");
+    const uiData = JSON.parse(stdout);
+    function matchesSearch(value, term, mode, sensitive) {
+        if (value == null)
+            return false;
+        const v = sensitive ? value : value.toLowerCase();
+        const t = sensitive ? term : term.toLowerCase();
+        return mode === "exact" ? v === t : v.includes(t);
+    }
+    function findElements(elements) {
+        const results = [];
+        for (const element of elements) {
+            const label = element.AXLabel;
+            const uniqueId = element.AXUniqueId;
+            const elementType = element.type;
+            const matchesAnySearch = options.search.some((term) => matchesSearch(label, term, options.matchMode, options.caseSensitive) ||
+                matchesSearch(uniqueId, term, options.matchMode, options.caseSensitive));
+            const matchesType = options.type == null ||
+                (elementType != null &&
+                    elementType.toLowerCase() === options.type.toLowerCase());
+            if (matchesAnySearch && matchesType) {
+                results.push(element);
+            }
+            const children = element.children;
+            if (children && children.length > 0) {
+                results.push(...findElements(children));
+            }
+        }
+        return results;
+    }
+    console.log(JSON.stringify(findElements(uiData)));
+}
+async function cmdUiView(options) {
+    const actualUdid = await getBootedDeviceId(udidSchema.parse(options.udid));
+    const { stdout: uiDescribeOutput } = await idb("ui", "describe-all", "--udid", actualUdid, "--json", "--nested");
+    let uiData;
+    try {
+        uiData = JSON.parse(uiDescribeOutput);
+    }
+    catch {
+        throw new Error("Failed to parse screen dimensions: idb returned invalid JSON");
+    }
+    const screenFrame = uiData[0]?.frame;
+    if (!screenFrame ||
+        typeof screenFrame.width !== "number" ||
+        typeof screenFrame.height !== "number" ||
+        screenFrame.width <= 0 ||
+        screenFrame.height <= 0) {
+        throw new Error("Could not determine valid screen dimensions from idb output");
+    }
+    const ts = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const rawPng = path_1.default.join(TMP_ROOT_DIR, `ui-view-${ts}-raw.png`);
+    const compressedJpg = path_1.default.join(TMP_ROOT_DIR, `ui-view-${ts}-compressed.jpg`);
+    await run("xcrun", [
+        "simctl",
+        "io",
+        actualUdid,
+        "screenshot",
+        "--type=png",
+        "--",
+        rawPng,
+    ]);
+    await run("sips", [
+        "-z",
+        String(screenFrame.height),
+        String(screenFrame.width),
+        "-s",
+        "format",
+        "jpeg",
+        "-s",
+        "formatOptions",
+        "80",
+        rawPng,
+        "--out",
+        compressedJpg,
+    ]);
+    if (options.output) {
+        const outputPath = ensureAbsolutePath(options.output);
+        fs_1.default.copyFileSync(compressedJpg, outputPath);
+        console.log(`Screenshot saved to ${outputPath}`);
+    }
+    else {
+        const base64Data = fs_1.default.readFileSync(compressedJpg).toString("base64");
+        console.log(base64Data);
+    }
+    try {
+        fs_1.default.unlinkSync(rawPng);
+        fs_1.default.unlinkSync(compressedJpg);
+    }
+    catch {
+        // ignore cleanup errors
+    }
+}
+async function cmdScreenshot(options) {
+    const actualUdid = await getBootedDeviceId(udidSchema.parse(options.udid));
+    const absolutePath = ensureAbsolutePath(options.outputPath);
+    const { stderr: stdout } = await run("xcrun", [
+        "simctl",
+        "io",
+        actualUdid,
+        "screenshot",
+        ...(options.type ? [`--type=${options.type}`] : []),
+        ...(options.display ? [`--display=${options.display}`] : []),
+        ...(options.mask ? [`--mask=${options.mask}`] : []),
+        "--",
+        absolutePath,
+    ]);
+    if (stdout && !stdout.includes("Wrote screenshot to")) {
+        throw new Error(stdout);
+    }
+    console.log(stdout || `Screenshot saved to ${absolutePath}`);
+}
+async function cmdRecordVideo(options) {
+    const actualUdid = await getBootedDeviceId(udidSchema.parse(options.udid));
+    const defaultFileName = `simulator_recording_${Date.now()}.mp4`;
+    const outputFile = ensureAbsolutePath(options.outputPath ?? defaultFileName);
+    const recordingProcess = (0, child_process_1.spawn)("xcrun", [
+        "simctl",
+        "io",
+        actualUdid,
+        "recordVideo",
+        ...(options.codec ? [`--codec=${options.codec}`] : []),
+        ...(options.display ? [`--display=${options.display}`] : []),
+        ...(options.mask ? [`--mask=${options.mask}`] : []),
+        ...(options.force ? ["--force"] : []),
+        "--",
+        outputFile,
+    ]);
+    await new Promise((resolve, reject) => {
+        let errorOutput = "";
+        let resolved = false;
+        recordingProcess.stderr.on("data", (data) => {
+            const message = data.toString();
+            if (message.includes("Recording started")) {
+                resolved = true;
+                resolve(true);
+            }
+            else {
+                errorOutput += message;
+            }
+        });
+        recordingProcess.on("exit", (code) => {
+            if (!resolved) {
+                reject(new Error(errorOutput.trim() ||
+                    `Recording process exited early with code ${code}`));
+            }
+        });
+        setTimeout(() => {
+            if (!resolved) {
+                if (recordingProcess.killed || recordingProcess.exitCode !== null) {
+                    reject(new Error(errorOutput.trim() ||
+                        "Recording process terminated unexpectedly"));
+                }
+                else {
+                    resolve(true);
+                }
+            }
+        }, 5000);
+    });
+    console.log(`Recording started. The video will be saved to: ${outputFile}\nTo stop recording, run: ios-simulator-cli stop-recording`);
+}
+async function cmdStopRecording() {
+    await run("pkill", ["-SIGINT", "-f", "simctl.*recordVideo"]);
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    console.log("Recording stopped successfully.");
+}
+async function cmdInstallApp(appPath, udid) {
+    const actualUdid = await getBootedDeviceId(udidSchema.parse(udid));
+    const absolutePath = path_1.default.isAbsolute(appPath)
+        ? appPath
+        : path_1.default.resolve(appPath);
+    if (!fs_1.default.existsSync(absolutePath)) {
+        throw new Error(`App bundle not found at: ${absolutePath}`);
+    }
+    await run("xcrun", ["simctl", "install", actualUdid, absolutePath]);
+    console.log(`App installed successfully from: ${absolutePath}`);
+}
+async function cmdLaunchApp(options) {
+    const actualUdid = await getBootedDeviceId(udidSchema.parse(options.udid));
+    const { args, env: simctlEnv } = buildLaunchArgs({
+        udid: actualUdid,
+        bundleId: options.bundleId,
+        terminateRunning: options.terminateRunning,
+        env: options.env,
+    });
+    const { stdout } = await run("xcrun", ["simctl", ...args], {
+        env: simctlEnv,
+    });
+    const pidMatch = stdout.match(/^(\d+)/);
+    const pid = pidMatch ? pidMatch[1] : null;
+    console.log(pid
+        ? `App ${options.bundleId} launched successfully with PID: ${pid}`
+        : `App ${options.bundleId} launched successfully`);
+}
+function printHelp() {
+    console.log(`ios-simulator-cli v${VERSION}
+
+A command-line tool for interacting with iOS simulators.
+
+Usage:
+  ios-simulator-cli <command> [options]
+
+Commands:
+  get-booted-sim-id                     Get the booted simulator UUID
+  open                                  Open Simulator.app
+  ui describe-all [--udid <uuid>]       Describe all UI elements
+  ui tap --x <n> --y <n> [--duration <s>] [--udid <uuid>]
+  ui type <text> [--udid <uuid>]        Type text into the simulator
+  ui swipe --x-start <n> --y-start <n> --x-end <n> --y-end <n> [--duration <s>] [--delta <n>] [--udid <uuid>]
+  ui describe-point --x <n> --y <n> [--udid <uuid>]
+  ui find-element --search <term> [--search <term>] [--type <type>] [--match-mode substring|exact] [--case-sensitive] [--udid <uuid>]
+  ui view [--output <path>] [--udid <uuid>]
+  screenshot --output <path> [--type png|jpeg|...] [--display internal|external] [--mask ignored|alpha|black] [--udid <uuid>]
+  record-video [--output <path>] [--codec h264|hevc] [--display internal|external] [--mask ignored|alpha|black] [--force] [--udid <uuid>]
+  stop-recording                        Stop an active simulator recording
+  install-app --app-path <path> [--udid <uuid>]
+  launch-app --bundle-id <id> [--terminate-running] [--env KEY=VALUE] [--udid <uuid>]
+
+Global options:
+  -h, --help                            Show this help
+  -v, --version                         Show version
+
+Environment variables:
+  IOS_SIMULATOR_CLI_DEFAULT_OUTPUT_DIR  Default directory for relative output paths (default: ~/Downloads)
+  IOS_SIMULATOR_CLI_IDB_PATH            Custom path to the idb executable
+
+Examples:
+  ios-simulator-cli get-booted-sim-id
+  ios-simulator-cli ui tap --x 200 --y 400
+  ios-simulator-cli screenshot --output home.png
+  ios-simulator-cli launch-app --bundle-id com.apple.mobilesafari
+`);
+}
+async function handleUiCommand(args) {
+    const subcommand = args[0];
+    const rest = args.slice(1);
+    switch (subcommand) {
+        case "describe-all": {
+            const { values } = (0, node_util_1.parseArgs)({
+                args: rest,
+                options: { udid: { type: "string" } },
+                allowPositionals: false,
+            });
+            await cmdUiDescribeAll(values.udid);
+            return;
+        }
+        case "tap": {
+            const { values } = (0, node_util_1.parseArgs)({
+                args: rest,
+                options: {
+                    udid: { type: "string" },
+                    x: { type: "string" },
+                    y: { type: "string" },
+                    duration: { type: "string" },
+                },
+                allowPositionals: false,
+            });
+            if (!values.x || !values.y) {
+                throw new Error("ui tap requires --x and --y");
+            }
+            if (values.duration) {
+                zod_1.z.string().regex(/^\d+(\.\d+)?$/).parse(values.duration);
+            }
+            await cmdUiTap({
+                udid: values.udid,
+                x: Number(values.x),
+                y: Number(values.y),
+                duration: values.duration,
+            });
+            return;
+        }
+        case "type": {
+            const { values, positionals } = (0, node_util_1.parseArgs)({
+                args: rest,
+                options: { udid: { type: "string" } },
+                allowPositionals: true,
+            });
+            const text = positionals.join(" ");
+            if (!text) {
+                throw new Error("ui type requires text");
+            }
+            await cmdUiType(text, values.udid);
+            return;
+        }
+        case "swipe": {
+            const { values } = (0, node_util_1.parseArgs)({
+                args: rest,
+                options: {
+                    udid: { type: "string" },
+                    "x-start": { type: "string" },
+                    "y-start": { type: "string" },
+                    "x-end": { type: "string" },
+                    "y-end": { type: "string" },
+                    duration: { type: "string" },
+                    delta: { type: "string" },
+                },
+                allowPositionals: false,
+            });
+            if (!values["x-start"] || !values["y-start"] || !values["x-end"] || !values["y-end"]) {
+                throw new Error("ui swipe requires --x-start, --y-start, --x-end, and --y-end");
+            }
+            await cmdUiSwipe({
+                udid: values.udid,
+                xStart: Number(values["x-start"]),
+                yStart: Number(values["y-start"]),
+                xEnd: Number(values["x-end"]),
+                yEnd: Number(values["y-end"]),
+                duration: values.duration,
+                delta: values.delta ? Number(values.delta) : undefined,
+            });
+            return;
+        }
+        case "describe-point": {
+            const { values } = (0, node_util_1.parseArgs)({
+                args: rest,
+                options: {
+                    udid: { type: "string" },
+                    x: { type: "string" },
+                    y: { type: "string" },
+                },
+                allowPositionals: false,
+            });
+            if (!values.x || !values.y) {
+                throw new Error("ui describe-point requires --x and --y");
+            }
+            await cmdUiDescribePoint({
+                udid: values.udid,
+                x: Number(values.x),
+                y: Number(values.y),
+            });
+            return;
+        }
+        case "find-element": {
+            const { values } = (0, node_util_1.parseArgs)({
+                args: rest,
+                options: {
+                    udid: { type: "string" },
+                    search: { type: "string", multiple: true },
+                    type: { type: "string" },
+                    "match-mode": { type: "string" },
+                    "case-sensitive": { type: "boolean", default: false },
+                },
+                allowPositionals: false,
+            });
+            if (!values.search || values.search.length === 0) {
+                throw new Error("ui find-element requires at least one --search value");
+            }
+            const matchMode = zod_1.z.enum(["substring", "exact"]).parse(values["match-mode"] ?? "substring");
+            await cmdUiFindElement({
+                udid: values.udid,
+                search: values.search,
+                type: values.type,
+                matchMode,
+                caseSensitive: values["case-sensitive"] ?? false,
+            });
+            return;
+        }
+        case "view": {
+            const { values } = (0, node_util_1.parseArgs)({
+                args: rest,
+                options: {
+                    udid: { type: "string" },
+                    output: { type: "string" },
+                },
+                allowPositionals: false,
+            });
+            await cmdUiView({ udid: values.udid, output: values.output });
+            return;
+        }
+        default:
+            throw new Error(`Unknown ui subcommand: ${subcommand ?? "(none)"}. Run ios-simulator-cli --help for usage.`);
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+        printHelp();
+        return;
+    }
+    if (args.includes("--version") || args.includes("-v")) {
+        console.log(VERSION);
+        return;
+    }
+    const command = args[0];
+    const rest = args.slice(1);
+    switch (command) {
+        case "get-booted-sim-id":
+            await cmdGetBootedSimId();
+            return;
+        case "open":
+            await cmdOpenSimulator();
+            return;
+        case "ui":
+            await handleUiCommand(rest);
+            return;
+        case "screenshot": {
+            const { values } = (0, node_util_1.parseArgs)({
+                args: rest,
+                options: {
+                    udid: { type: "string" },
+                    output: { type: "string" },
+                    type: { type: "string" },
+                    display: { type: "string" },
+                    mask: { type: "string" },
+                },
+                allowPositionals: false,
+            });
+            if (!values.output) {
+                throw new Error("screenshot requires --output");
+            }
+            await cmdScreenshot({
+                udid: values.udid,
+                outputPath: values.output,
+                type: zod_1.z
+                    .enum(["png", "tiff", "bmp", "gif", "jpeg"])
+                    .optional()
+                    .parse(values.type),
+                display: zod_1.z.enum(["internal", "external"]).optional().parse(values.display),
+                mask: zod_1.z.enum(["ignored", "alpha", "black"]).optional().parse(values.mask),
+            });
+            return;
+        }
+        case "record-video": {
+            const { values } = (0, node_util_1.parseArgs)({
+                args: rest,
+                options: {
+                    udid: { type: "string" },
+                    output: { type: "string" },
+                    codec: { type: "string" },
+                    display: { type: "string" },
+                    mask: { type: "string" },
+                    force: { type: "boolean", default: false },
+                },
+                allowPositionals: false,
+            });
+            await cmdRecordVideo({
+                udid: values.udid,
+                outputPath: values.output,
+                codec: zod_1.z.enum(["h264", "hevc"]).optional().parse(values.codec),
+                display: zod_1.z.enum(["internal", "external"]).optional().parse(values.display),
+                mask: zod_1.z.enum(["ignored", "alpha", "black"]).optional().parse(values.mask),
+                force: values.force,
+            });
+            return;
+        }
+        case "stop-recording":
+            await cmdStopRecording();
+            return;
+        case "install-app": {
+            const { values } = (0, node_util_1.parseArgs)({
+                args: rest,
+                options: {
+                    udid: { type: "string" },
+                    "app-path": { type: "string" },
+                },
+                allowPositionals: false,
+            });
+            if (!values["app-path"]) {
+                throw new Error("install-app requires --app-path");
+            }
+            await cmdInstallApp(values["app-path"], values.udid);
+            return;
+        }
+        case "launch-app": {
+            const { values } = (0, node_util_1.parseArgs)({
+                args: rest,
+                options: {
+                    udid: { type: "string" },
+                    "bundle-id": { type: "string" },
+                    "terminate-running": { type: "boolean", default: false },
+                    env: { type: "string", multiple: true },
+                },
+                allowPositionals: false,
+            });
+            if (!values["bundle-id"]) {
+                throw new Error("launch-app requires --bundle-id");
+            }
+            await cmdLaunchApp({
+                udid: values.udid,
+                bundleId: values["bundle-id"],
+                terminateRunning: values["terminate-running"],
+                env: parseEnvPairs(values.env),
+            });
+            return;
+        }
+        default:
+            throw new Error(`Unknown command: ${command}. Run ios-simulator-cli --help for usage.`);
+    }
+}
+function cleanup() {
+    try {
+        fs_1.default.rmSync(TMP_ROOT_DIR, { recursive: true, force: true });
+    }
+    catch {
+        // ignore cleanup errors
+    }
+}
+main()
+    .catch((error) => {
+    console.error(errorWithTroubleshooting(`Error: ${toError(error).message}`));
+    process.exitCode = 1;
+})
+    .finally(cleanup);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@debugswift/ios-simulator-cli",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.6.0",
+  "description": "CLI for interacting with the iOS simulator",
+  "bin": {
+    "ios-simulator-cli": "build/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DebugSwift/ios-simulator-cli.git"
+  },
+  "files": [
+    "build",
+    "package.json"
+  ],
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "start": "node build/index.js",
+    "watch": "tsc --watch"
+  },
+  "keywords": [
+    "ios",
+    "simulator",
+    "cli",
+    "simctl",
+    "idb"
+  ],
+  "author": {
+    "name": "Joshua Yoes",
+    "url": "https://joshuayoes.com"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.12.0",
+    "typescript": "^5.5.4"
+  }
+}