install-ios

An npx-runnable CLI to build an iOS Xcode project, install the built .app on a connected physical iPhone or iPad, and launch it.

The CLI uses:

• xcodebuild for project inspection and device builds
• xcrun devicectl for physical-device discovery, install, and launch
• @clack/prompts for interactive device and scheme selection

Simulators are intentionally excluded from the device list.

Install And Run

Run without installing:

npx @nocdn/install-ios

Or run from a local checkout:

npm install
npm start -- /path/to/MyApp

Usage

install-ios [project-path] [options]
install-ios doctor [project-path] [options]
install-ios list

By default, install-ios inspects the current directory, finds a top-level .xcworkspace or .xcodeproj, validates that the selected scheme can produce an installable physical-iOS .app, lists connected physical iOS devices, then builds, installs, and launches on the selected device.

If the project has one obvious app scheme, it is selected automatically. If the scheme, project, workspace, or device is ambiguous, the CLI prompts for it when running in an interactive terminal.

The last selected physical device is remembered per project in ~/.config/install-ios/config.json, so repeat installs do not need --device.

Examples

install-ios
install-ios /Users/me/src/MyApp
install-ios --device 00008120-000275180C10201E
install-ios /Users/me/src/MyApp --scheme MyApp --configuration Debug
install-ios --list
install-ios doctor /Users/me/src/MyApp
install-ios /Users/me/src/MyApp --build-only
install-ios --install-only /Users/me/src/MyApp.app --device 00008120-000275180C10201E
install-ios --launch-only com.example.MyApp --logs --log-timeout 60
install-ios --no-launch

Options

| flag | description | | --- | --- | | [project-path] | Directory containing a top-level .xcodeproj or .xcworkspace. | | -C, --cwd <path> | Project directory. Defaults to the current directory. | | --project <path> | Explicit .xcodeproj path. | | --workspace <path> | Explicit .xcworkspace path. | | --scheme <name> | Xcode scheme to build. Auto-detected when unambiguous. | | --configuration <name> | Xcode configuration. Defaults to Debug. | | --device <udid\|name> | Physical iOS device to install on. Prompts when omitted. | | --derived-data <path> | DerivedData path. Defaults to a temporary directory. | | --list, --list-devices | List connected physical iOS devices and exit. | | doctor, --doctor | Run environment, device, project, and signing checks. | | --json | Print machine-readable JSON. Cannot be combined with --logs. | | --verbose | Print underlying command output on success too. | | --clean | Run xcodebuild clean before building. | | --build-only | Build the app but do not install or launch it. | | --install-only <path> | Install an existing .app bundle without building. | | --launch-only <bundle-id> | Launch an already installed app without building or installing. | | --no-launch | Install the app but do not launch it. | | --wait-for-unlock | Retry launch while the selected device is locked. | | --wait-timeout <seconds> | Maximum --wait-for-unlock time. Defaults to 120. | | --logs | Launch with devicectl --console and stream app output. | | --log-timeout <seconds> | Stop --logs after this many seconds. Defaults to no timeout. | | --open, --payload-url <url> | Pass a URL to the app at launch. | | --no-remember-device | Do not save or reuse the last selected device for this project. | | -h, --help | Show help. | | -v, --version | Show version. |

Commands

install-ios list and install-ios --list list connected, booted physical iOS devices only. Simulators are filtered out.

install-ios doctor checks Node.js, npm, Xcode, xcodebuild, devicectl, connected physical devices, and the selected project when one is present. It also reports the detected app product and signing summary.

Shortcut Flows

Use --build-only when you want to compile and inspect the produced .app without installing it.

Use --install-only /path/to/App.app to skip Xcode entirely and install an existing app bundle. It launches by default unless --no-launch is passed.

Use --launch-only com.example.App to relaunch an app that is already installed on the selected device.

Use --logs to launch through devicectl --console. Without --log-timeout, the command streams until the app exits or you stop the CLI.

Use --open <url> to pass a payload URL into the app at launch.

Project Requirements

The project should have:

• one top-level .xcworkspace or .xcodeproj, unless --workspace or --project is passed
• at least one shared Xcode scheme
• a scheme that builds an installable .app
• support for physical iOS builds (iphoneos)

The CLI does not install to simulators.

If the install succeeds but launch fails with a locked-device error, unlock the iPhone or iPad, keep it awake, and run the command again. iOS denies remote app launch requests while the device is locked. --wait-for-unlock retries that launch until the device is unlocked or --wait-timeout is reached.

Develop

npm install
npm start -- --help

The CLI entry point lives in bin/cli.js. The package is built with plain Node.js ESM and npm, with no transpilation step.

Publishing

This project includes a GitHub Actions workflow at .github/workflows/publish.yml that publishes the package to npm with trusted publishing on every push, as long as the version in package.json is not already on npm. package.json sets publishConfig.access to public, so scoped packages are published publicly by default.

To enable it once:

1. Push the repository to GitHub.
2. On npmjs.com, configure the package as a trusted publisher pointing at the publish.yml workflow in this repository.
3. Bump the version in package.json and push; the workflow will publish.