native-run

2.0.3 verified Sat Apr 25 auth: no javascript

A cross-platform CLI for deploying native app binaries (.ipa/.apk) to iOS and Android devices and simulators/emulators. Current stable version v2.0.3 requires Node >=16. Maintained by the Ionic team with regular releases (semantic-release). Key differentiators: written entirely in TypeScript without native NodeJS addons, supports both hardware and virtual devices, automatically handles provisioning profiles and emulator creation. Commonly used as part of Cordova/Ionic workflows, but works standalone.

Common errors

error Error: Unsupported platform: ios ↓

cause Missing Xcode or iOS platform tools

fix

Ensure Xcode is installed: xcode-select --install

error Error: No devices or emulators found ↓

cause No connected devices or running emulators

fix

Check connections with adb devices (Android) or xcrun xctrace (iOS)

error Error: APP_PATH does not exist: /path/to/app.apk ↓

cause Incorrect path to APK/IPA file

fix

Provide absolute path or verify relative path

Warnings

breaking Dropped support for Node <16 in v2.0.0 ↓

fix Upgrade Node.js to v16 or later.

deprecated iOS 17 support requires Xcode 15 or later ↓

fix Update Xcode to version 15+.

gotcha Android emulator creation may fail on M1 Macs if ARM64 system image not used ↓

fix Upgrade to v1.7.1+ or manually specify arm64 architecture.

breaking v2.0.0 removed support for Node 14 ↓

fix Ensure Node v16 or higher is installed.

gotcha Non-ASCII characters in file paths cause errors (<2.0.1) ↓

fix Upgrade to v2.0.1 or use only ASCII paths.

Install

npm install native-run

yarn add native-run

pnpm add native-run

Imports

default
wrong
```
native-run ios --target alien-device
```
correct
```
npx native-run android --app myapp.apk --verbose
```
CLI tool invoked via npx or global install. No programmatic API intended.

Quickstart

Deploys an APK to a connected Android device or emulator with verbose logging.

npx native-run android --app /path/to/app.apk --verbose