mobilecli

mobilecli

A universal command-line tool for managing iOS and Android devices, simulators, emulators and apps from Mobile Next.

Features 🚀

• Device Management: List, manage, interactive with connected mobile devices
• Cross-Platform Support: Works with iOS physical devices, iOS simulators, Android devices, and Android emulators
• Emulator/Simulator Control: Boot and shutdown emulators and simulators programmatically
• Screenshot Capture: Take screenshots from any connected device with format options
• Multiple Output Formats: Save screenshots as PNG or JPEG with quality control
• Screencapture video streaming: Stream mjpeg video directly from device
• Device Control: Reboot devices, tap screen coordinates, press hardware buttons
• App management: Launch app, terminate apps. Install and uninstall coming next ⏭️

Installation 📦

Prerequisites 📋

• Android SDK with adb in PATH (for Android device support)
• Xcode Command Line Tools (for iOS simulator support on macOS)

Run instantly with npx

npx @mobilenext/mobilecli@latest

Install globally with npm

npm install -g @mobilenext/mobilecli@latest

Install from Source 🛠️

git clone https://github.com/mobile-next/mobilecli.git
cd mobilecli
make build

Install Dependencies

🍎 For iOS Simulator Support

Xcode is required. Make sure you have it installed with the runtimes relevant for you installed. You will have to create Simulators and have them booted before mobilecli can use them.

mobilecli will automatically install an agent on the device that is required for functionalities such as opening a url, tapping on buttons and streaming screen capture.

🤖 For Android Support

# Install Android SDK and ensure adb is in PATH
# Download from: https://developer.android.com/studio/command-line/adb
# or
brew install --cask android-platform-tools

Usage

List Connected Devices 🔍

# List all online devices and simulators
mobilecli devices

# List all devices including offline emulators and simulators
mobilecli devices --include-offline

Example output:

[
  {
    "id": "12345678-1234567890ABCDEF",
    "name": "iPhone 15",
    "platform": "ios",
    "type": "real",
    "state": "online"
  },
  {
    "id": "Pixel_6",
    "name": "Pixel 6",
    "platform": "android",
    "type": "emulator",
    "state": "online"
  },
  {
    "id": "iPhone_13",
    "name": "iPhone 13",
    "platform": "ios",
    "type": "simulator",
    "state": "offline"
  }
]

Note: Offline emulators and simulators can be booted using the mobilecli device boot command.

Take Screenshots 📸

# Take a PNG screenshot (default)
mobilecli screenshot --device <device-id>

# Take a JPEG screenshot with custom quality
mobilecli screenshot --device <device-id> --format jpeg --quality 80

# Save to specific path
mobilecli screenshot --device <device-id> --output screenshot.png

# Output to stdout
mobilecli screenshot --device <device-id> --output -

Stream Screen 🎥

mobilecli screencapture --device <device-id> --format mjpeg | ffplay -

Note that screencapture is one way. You will have to use io tap commands to tap on the screen.

Device Control 🎮

# Boot an offline emulator or simulator
mobilecli device boot --device <device-id>

# Shutdown a running emulator or simulator
mobilecli device shutdown --device <device-id>

# Reboot a device
mobilecli device reboot --device <device-id>

# Tap at coordinates (x,y)
mobilecli io tap --device <device-id> 100,200

# Long press at coordinates (x,y) with optional duration in milliseconds
mobilecli io longpress --device <device-id> 100,200
mobilecli io longpress --device <device-id> 100,200 --duration 2000

# Press hardware buttons
mobilecli io button --device <device-id> HOME
mobilecli io button --device <device-id> VOLUME_UP
mobilecli io button --device <device-id> POWER

# Send text
mobilecli io text --device <device-id> 'hello world'

Supported Hardware Buttons

• HOME - Home button
• BACK - Back button (Android only)
• POWER - Power button
• VOLUME_UP, VOLUME_DOWN - Volume up and down
• DPAD_UP, DPAD_DOWN, DPAD_LEFT, DPAD_RIGHT, DPAD_CENTER - D-pad controls (Android only)

Platform-Specific Notes

iOS Real Devices

• Currently requires that you install and run WebDriverAgent manually. You may change the BUNDLE IDENTIFIER, and mobilecli will be able to launch it if needed, as long as the identifier ends with *.WebDriverAgent.

Development 👩‍💻

Building 🛠️

Please refer to (docs/TESTING.md) for further instructions regarding testing mobilecli locally.

make lint
make build
make test

Support 💬

For issues and feature requests, please use the GitHub Issues page.

Be sure to join our slack channel today 💜

To learn more about Mobile Next and what we're building, subscribe to our newsletter.