# mobilecli
**English** | [日本語](README.ja.md) | [简体中文](README.zh-CN.md)
A universal command-line tool for managing iOS and Android devices, simulators, emulators and apps from [Mobile Next](https://github.com/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/avc (H.264) video directly from device
- **Device Control**: Reboot devices, tap screen coordinates, press hardware buttons
- **App Management**: Launch, terminate, install, uninstall, clear data, list, and get foreground apps
- **Filesystem**: Push, pull, list, mkdir, and rm files on-device or in app containers (Android, iOS Simulator)
- **Location Override**: Fake the GPS location reported by a device
- **Crash Reports**: List and fetch crash reports from iOS and Android devices
- **Device Logs**: Stream real-time device logs with filtering from iOS and Android devices
- **Webview Inspection**: List, navigate, query DOM, and evaluate JavaScript in embedded webviews
### 🎯 Platform Support
| Platform | Supported |
|----------|:---------:|
| iOS Real Device | ✅ |
| iOS Simulator | ✅ |
| Android Real Device | ✅ |
| Android Emulator | ✅ |
## Installation 📦
#### Prerequisites 📋
- **Android SDK** with `adb` in PATH (for Android device support)
- **Xcode Command Line Tools** (for iOS simulator support on macOS)
#### Install globally with npm
```bash
npm install -g mobilecli@latest
```
#### Shell Completion ⌨️
```bash
# zsh
echo 'source <(mobilecli completion zsh)' >> ~/.zshrc
# bash 4.1+ (requires bash-completion; macOS ships bash 3.2)
echo 'source <(mobilecli completion bash)' >> ~/.bashrc
# fish
mobilecli completion fish > ~/.config/fish/completions/mobilecli.fish
```
Run `mobilecli completion --help` for PowerShell and other options.
### Agent Setup 🤖
Install `mobilecli` and add the skill so your coding agent knows how to use it:
```bash
npm install -g mobilecli@latest
npx skills add https://github.com/mobile-next/mobilecli
```
## CLI Reference
### List Connected Devices 🔍
```bash
# List all online devices and simulators
mobilecli devices
# List all devices including offline emulators and simulators
mobilecli devices --include-offline
```
**Note**: Offline emulators and simulators can be booted using the `mobilecli device boot` command.
### Default Device 🎯
When only one device is online, mobilecli selects it automatically and `--device` isn't needed.
With several devices online, set `MOBILECLI_DEVICE` to skip `--device` on every command. An explicit `--device` still takes precedence.
```bash
export MOBILECLI_DEVICE=
# Taps on $MOBILECLI_DEVICE
mobilecli io tap 100,200
# Overrides $MOBILECLI_DEVICE for this command only
mobilecli io tap --device 100,200
```
### Take Screenshots 📸
```bash
# Take a PNG screenshot (default)
mobilecli screenshot --device
# Take a JPEG screenshot with custom quality
mobilecli screenshot --device --format jpeg --quality 80
# Scale the screenshot down to half size
mobilecli screenshot --device --scale 0.5
# Limit the largest dimension to 800 pixels, keeping aspect ratio
mobilecli screenshot --device --max-size 800
# Crop to a region (x,y,width,height in screen points), applied before scaling
mobilecli screenshot --device --clip 10,80,300,200
# Save to specific path
mobilecli screenshot --device --output screenshot.png
# Output to stdout
mobilecli screenshot --device --output -
```
### UI Tree 🌳
```bash
# Dump the UI tree as indented text, each element with a ref like @e5
mobilecli snapshot --device
# Same as snapshot
mobilecli dump ui --device --format text
# Dump the UI tree as JSON, including each element's rect
mobilecli dump ui --device
# Tap an element by its ref from the latest dump
mobilecli io tap --device @e5
```
### Stream Screen 🎥
```bash
mobilecli screencapture --device --format mjpeg | ffplay -
```
Note that screencapture is one way. You will have to use `io tap` commands to tap on the screen.
### Device Control 🎮
```bash
# Boot an offline emulator or simulator
mobilecli device boot --device
# Boot it with a visible window
mobilecli device boot --device --headed
# Shutdown a running emulator or simulator
mobilecli device shutdown --device
# Reboot a device
mobilecli device reboot --device
# Tap at coordinates (x,y)
mobilecli io tap --device 100,200
# Double tap at coordinates (x,y)
mobilecli io doubletap --device 100,200
# Drag from one point or element ref to another; --hold keeps the finger still before it moves
mobilecli io drag --device 100,200,300,400
mobilecli io drag --device @e1,@e2 --hold 500 --duration 1000
# Long press at coordinates (x,y) with optional duration in milliseconds
mobilecli io longpress --device 100,200
mobilecli io longpress --device 100,200 --duration 2000
# Press hardware buttons
mobilecli io button --device HOME
mobilecli io button --device VOLUME_UP
mobilecli io button --device POWER
# Check whether the on-screen keyboard is showing
mobilecli io keyboard status --device
# Hide the on-screen keyboard (on real iOS devices only in debuggable apps, on simulators only in apps you installed)
mobilecli io keyboard hide --device
# Send text
mobilecli io text --device 'hello world'
# Replace the focused field's text in one step ('' clears it)
mobilecli io fill --device 'hello world'
# Read device clipboard
mobilecli io clipboard get --device
# Write device clipboard
mobilecli io clipboard set --device 'hello world'
# Send keys combination to paste (cmd+v for iOS, ctrl+v for Android)
mobilecli io keys --device "cmd+v"
```
### Location Override 📍
```bash
# Fake the device location (latitude,longitude)
mobilecli device location set --device 37.7749,-122.4194
# Hold the override until Ctrl-C, then clear it automatically
mobilecli device location set --device 37.7749,-122.4194 --wait
# Restore the real location
mobilecli device location clear --device
```
Caveats per platform:
| Platform | Notes |
|----------|-------|
| iOS Simulator | Works out of the box, the override survives mobilecli exiting |
| iOS Real Device | The override only lives as long as the mobilecli process that set it, so `--wait` is required. `clear` has to come from that same process |
| Android Emulator | Uses the emulator console. It has no way to undo a fix, so `clear` sets the location back to the coordinates an emulator boots with (the Googleplex), not to a real one |
| Android Real Device | Runs an on-device agent as a mock location provider, granting the `mock_location` appop to `com.android.shell`. Some OEM ROMs ignore mock providers, and apps checking `Location.isFromMockProvider()` or Play Integrity can tell |
### VoiceOver ♿
Drive VoiceOver and read what it speaks, to check an app's accessibility labels and focus order. Needs iOS 27 or later, on a simulator or a real device.
```bash
# Turn VoiceOver on or off, or read its state
mobilecli device voiceover set --device on
mobilecli device voiceover get --device
# What VoiceOver speaks for the focused element, e.g. "Add Favorites, button"
mobilecli device voiceover speech --device
# Move to the next or previous element and print what VoiceOver speaks there
mobilecli device voiceover move --device next
mobilecli device voiceover move --device previous
mobilecli device voiceover set --device off
```
VoiceOver stays on after mobilecli exits, so turn it off when done. While it is on, `io tap` focuses an element instead of activating it. `move in` and `move out` need VoiceOver's Navigation Style set to Groups.
### Supported Hardware Buttons
- `HOME` - Home button
- `POWER` - Power (side) button. `LOCK` is an alias
- `VOLUME_UP`, `VOLUME_DOWN` - Volume up and down
- `ENTER` - Enter key
- `BACK` - Back button (Android only)
- `APP_SWITCH` - Recent apps (Android only)
- `BACKSPACE` - Delete the character before the cursor (Android only)
- `DPAD_UP`, `DPAD_DOWN`, `DPAD_LEFT`, `DPAD_RIGHT`, `DPAD_CENTER` - D-pad controls (Android only)
Names are case-insensitive. `mobilecli io button --help` prints the list for each platform, and an unknown name fails with the supported names.
### App Management 📱
```bash
# List installed apps on device
mobilecli apps list --device
# Get currently foreground app
mobilecli apps foreground --device
# Launch an app
mobilecli apps launch --device
# Launch an app with arguments and environment variables (iOS)
mobilecli apps launch --device --arg -FeatureX --arg YES --env API_URL=https://staging.example.com
# Launch an app with string intent extras (Android, each --arg is key=value and becomes --es key value)
mobilecli apps launch --device --arg featureX=true --arg apiUrl=https://staging.example.com
# Terminate an app
mobilecli apps terminate --device
# Install an app (.apk for Android, .ipa for iOS, .zip for iOS Simulator)
mobilecli apps install --device
# Uninstall an app
mobilecli apps uninstall --device
# Clear app data (cache, preferences, databases) and reset permissions, without uninstalling
# Supported on Android and iOS Simulator
mobilecli apps clear --device
```
### Filesystem 📂
Access files on the device or inside an app's data container. Currently supported on **Android** and **iOS Simulator**.
```bash
# Get the data container path of an app (Android)
mobilecli apps path --device
# List files at any absolute path (defaults to device root if omitted)
mobilecli fs ls --device
mobilecli fs ls --device /sdcard
mobilecli fs ls --device /sdcard/Download
# List files inside an app's data container
mobilecli fs ls --device com.example.app
mobilecli fs ls --device com.example.app /Documents
# Pull a file from the device to local disk
mobilecli fs pull --device /sdcard/recording.mp4 ./recording.mp4
# Pull a file from an app's private container
mobilecli fs pull --device /data/user/0/com.example.app/files/db.sqlite ./db.sqlite
# Push a file to the device
mobilecli fs push --device ./config.json /sdcard/config.json
# Push a file into an app's private container
mobilecli fs push --device ./config.json /data/user/0/com.example.app/files/config.json
# Create a directory
mobilecli fs mkdir --device /sdcard/myfolder
# Create a directory and all parent directories
mobilecli fs mkdir --device -p /sdcard/a/b/c
mobilecli fs mkdir --device -p /data/user/0/com.example.app/files/cache/v2
# Remove a file
mobilecli fs rm --device /sdcard/old_file.txt
# Remove a directory recursively
mobilecli fs rm --device -r /sdcard/myfolder
mobilecli fs rm --device -r /data/user/0/com.example.app/files/cache
```
**Notes:**
- Paths under `/data/user/` are accessed via `run-as`, so the app must be debuggable.
- Pushing to `/data/user/` stages the file through `/data/local/tmp/` then copies it into the container.
- Pulling binary files (images, databases, DEX files) is fully supported and binary-safe on all platforms.
### Agent Management 🤖
On **iOS**, the on-device agent is required for touch input (taps, swipes, button presses), screen capture streaming, and UI tree inspection. These capabilities are not available through standard iOS tooling without an agent running on the device.
On **Android**, no agent is needed. Running `mobilecli agent status` on an Android device simply reports that.
```bash
# Check if the agent is installed on a device
mobilecli agent status --device
# Install the agent
mobilecli agent install --device
# Force reinstall the agent
mobilecli agent install --device --force
# Install on a real iOS device (requires provisioning profile)
mobilecli agent install --device --provisioning-profile /path/to/profile.mobileprovision
```
Example output for `agent status`:
```json
{
"status": "ok",
"data": {
"message": "Agent version 0.0.12 is installed on device",
"agent": {
"version": "0.0.12",
"bundleId": "com.mobilenext.devicekit-iosUITests.xctrunner"
}
}
}
```
### Webview Inspection 🌐
Inspect and interact with embedded webviews (`WKWebView` on iOS, `android.webkit.WebView` on Android) running inside native apps.
On Android the same commands also drive the tabs of Chrome when it is the foreground app, over the Chrome DevTools Protocol. Chrome freezes the tabs it is not showing, so only the visible tab (`isVisible: true`) answers `eval` and the commands built on it.
On iOS, real devices and simulators alike, the same commands also drive the tabs of Safari when it is the foreground app, through the device's Web Inspector service. A real device needs **Settings > Apps > Safari > Advanced > Web Inspector** turned on. Safari does not keep the tabs it is not showing running: a command on such a tab fails after 2 seconds, so use the tab listed with `isVisible: true`.
```bash
# List embedded webviews in the foreground app
mobilecli webview list --device
# Navigate a webview to a URL
mobilecli webview goto https://example.com --device
# Reload, go back or forward
mobilecli webview reload --device
mobilecli webview back --device
mobilecli webview forward --device
# Get current URL and page title
mobilecli webview url --device
mobilecli webview title --device
# Dump the full HTML content of the page
mobilecli webview content --device
# Query DOM elements by CSS selector
mobilecli webview query "button" --device
mobilecli webview query "[data-testid='submit']" --device
# Evaluate arbitrary JavaScript
mobilecli webview eval "document.querySelectorAll('a').length" --device
# Wait for the page to finish loading
mobilecli webview wait --state load --device
mobilecli webview wait --state domcontentloaded --timeout 5000 --device
```
Example output for `webview list`:
```json
{
"status": "ok",
"data": [
{
"id": "1",
"url": "https://example.com",
"title": "Example Domain"
}
]
}
```
Example output for `webview query "button"`:
```json
{
"status": "ok",
"data": [
{ "tag": "button", "text": "Sign In", "id": "login-btn", "class": "btn-primary", "value": null, "href": null },
{ "tag": "button", "text": "Cancel", "id": null, "class": "btn-secondary", "value": null, "href": null }
]
}
```
### Crash Reports 💥
```bash
# List crash reports from a device
mobilecli device crashes list --device
# Get a specific crash report by ID
mobilecli device crashes get --device
```
Example output for `crashes list`:
```json
{
"status": "ok",
"data": [
{
"processName": "ShareExtension",
"timestamp": "2026-01-24-195529",
"id": "ShareExtension-2026-01-24-195529.ips"
}
]
}
```
**Note**: On iOS real devices, crash reports are fetched via the Apple crashreport service. On iOS simulators, they are read from `~/Library/Logs/DiagnosticReports/`. On Android, crashes are parsed from `adb logcat -b crash`.
### Device Logs 📋
```bash
# Stream logs from a device (Ctrl+C to stop)
mobilecli device logs --device
# Stop after 100 entries
mobilecli device logs --device --limit 100
# Filter by field (exact match)
mobilecli device logs --filter process=SpringBoard
mobilecli device logs --filter tag=ActivityManager
# Exclude by field
mobilecli device logs --filter process!=SpringBoard
# Combine filters (AND logic)
mobilecli device logs --filter level=Error --filter process!=SpringBoard
```
Supported filter keys: `pid`, `process`, `tag`, `level`, `subsystem`, `category`, `message`
Each log entry is printed as a JSON line:
```json
{"timestamp":"2026-04-15 12:17:14.224451+0300","message":"Start proc...","level":"Default","subsystem":"com.apple.UIKit","category":"EventDispatch","pid":54052,"process":"SpringBoard"}
```
Logs are also available over the [HTTP API](#http-api-) via the `device.logs` method, which takes the same `limit` and `filters` and returns a URL to stream from:
```bash
curl -X POST http://localhost:12000/rpc -H "Content-Type: application/json" -d '{
"jsonrpc": "2.0", "method": "device.logs", "id": 1,
"params": { "deviceId": "", "limit": 100, "filters": ["level=Error", "process!=SpringBoard"] }
}'
# => {"jsonrpc":"2.0","id":1,"result":{"sessionUrl":"/sessions//logs"}}
curl -N http://localhost:12000/sessions//logs
```
The session expires one minute after creation and accepts a single connection. Disconnecting stops the log stream on the device.
### Remote Devices ☁️
```bash
# Allocate a remote iOS device
mobilecli remote allocate --platform ios --version ">=18" --name "iPhone*" --wait
# Allocate a remote Android device (exact OS version)
mobilecli remote allocate --platform android --version 14 --wait
# List remote device models
mobilecli remote list-devices
# Release an allocated remote device
mobilecli remote release --device
```
## Claude Code Skill 🤖
This repo includes an agent skill ([skills/mobilecli/SKILL.md](skills/mobilecli/SKILL.md)) that teaches Claude Code (or any SKILL.md-compatible agent) how to drive `mobilecli` — listing devices, tapping and typing, dumping UI trees, managing apps, and using the JSON-RPC server for fast automation.
Install it with [skills](https://github.com/vercel-labs/skills):
```bash
# current project only
npx skills add mobile-next/mobilecli
# or globally, for all projects
npx skills add mobile-next/mobilecli -g
```
Then ask your agent things like "take a screenshot of my emulator" or "tap the login button" — the skill triggers automatically.
## Daemon ⚙️
Every device command talks to a per-user background daemon that keeps discovered devices, iOS tunnels and on-device agents alive between invocations, so only the first command pays the discovery cost. The daemon starts automatically on the first device command (`mobilecli --help` and `--version` never start it) and exits after 30 minutes without requests.
```bash
# Inspect or control it explicitly
mobilecli daemon status
mobilecli daemon stop
# Run it in the foreground (e.g. under a service manager), with a custom idle timeout
mobilecli daemon start --idle-timeout 0
```
The CLI and daemon talk JSON-RPC over a unix domain socket in `~/.mobilecli/` (override with `MOBILECLI_HOME`); the daemon's log is `~/.mobilecli/daemon.log`. A daemon left over from an older mobilecli version is restarted automatically. `auth login` and `auth logout` stop a running daemon so it picks up the new credentials.
On Android, the daemon keeps a small server running on the device (`com.mobilenext.mobilecli.DeviceServer`) that holds the device's only UiAutomation connection, so other UiAutomator clients such as `uiautomator dump` or Appium cannot run alongside it. The daemon stops that server when it exits, so `mobilecli daemon stop` hands the device back to other tools; the server also exits by itself after 30 minutes without requests (`MOBILECLI_DEVICE_SERVER_IDLE_TIMEOUT=5m` shortens that).
## HTTP API 🔌
***mobilecli*** provides an http interface for all the functionality that is available through command line. The server is a thin front for the daemon above, so HTTP clients and the CLI share one set of devices and tunnels.
For the full list of available JSON-RPC methods and their parameters, see the [OpenRPC specification](https://github.com/mobile-next/mobile-openrpc/blob/main/mobilecli/openrpc.md).
```bash
# Start the server (default port 12000)
mobilecli server start
curl http://localhost:12000/rpc -XPOST -d '{"jsonrpc":"2.0", "id": 1, "method": "devices.list", "params": {}}'
curl http://localhost:12000/rpc -XPOST -d '{"jsonrpc":"2.0", "id": 1, "method": "device.screenshot", "params": {"deviceId": "your-device-id"}}'
```
## WebSocket Support 🔌
***mobilecli*** includes a WebSocket server that allows multiple requests over a single connection using the same JSON-RPC 2.0 format as the HTTP API.
```bash
# Start the server (default port 12000)
mobilecli server start
# Connect and send requests using wscat
wscat -c ws://localhost:12000/ws
> {"jsonrpc":"2.0","id":1,"method":"devices.list","params":{}}
< {"jsonrpc":"2.0","id":1,"result":[...]}
> {"jsonrpc":"2.0","id":2,"method":"device.screenshot","params":{"deviceId":"your-device-id"}}
< {"jsonrpc":"2.0","id":2,"result":{...}}
```
**Note**: `screencapture` is not supported over WebSocket - use the HTTP `/rpc` endpoint for video streaming.
## Platform-Specific Notes
### iOS Real Devices
The on-device agent requires a valid development provisioning profile for your device and a corresponding signing certificate with its private key in your Mac's keychain:
```bash
mobilecli agent install --device \
--provisioning-profile "/path/to/profile.mobileprovision"
```
Wildcard profiles (`TEAMID.*`) keep the agent's default bundle ID. Explicit App ID profiles (e.g. Xcode-managed) are supported too: the agent is renamed to the profile's bundle ID, which must end with `com.mobilenext.devicekit-iosUITests.xctrunner`.
## Development 👩💻
### Repository layout
- `main.go` is the executable entry point; `go.mod` stays at the repository root.
- `internal/` contains the Go implementation and its unit tests, including the private `avc2mp4` package.
- `agents/android/` and `agents/ios/injected/` contain native agent sources and their Makefiles.
- `internal/agentassets/` embeds the generated binaries from its ignored `data/` directory. Run `make agents` before building or testing a fresh checkout; it requires the Android SDK/NDK, a JDK, and Xcode for the iOS agents.
- `test/` contains the end-to-end tests, and `publish/` contains npm packaging.
### Building 🛠️
Please refer to [docs/TESTING.md](docs/TESTING.md) for further instructions regarding testing *mobilecli* locally.
```bash
make lint
make build
make test
```
## Support 💬
Something not working? Check [docs/troubleshooting.md](docs/troubleshooting.md) first.
For issues and feature requests, please use the [GitHub Issues](https://github.com/mobile-next/mobilecli/issues) page.
Be sure to join our slack channel today 💜
To learn more about Mobile Next and what we're building.