mobitru-mobile-cli

CLI for AI agents to automate mobile app testing on the Mobitru cloud platform.

Drives a real Android phone or iOS device on Mobitru cloud via Appium. Session state (active booking, Appium session) persists across short-lived CLI invocations so each command stays cheap. No local emulator.

Installation

npm install -g mobitru-mobile-cli

Quick start

# 1. Configure once (env vars OR ~/.mobitru-cli/config.json)
export DEVICE_FARM_BASE_URL=app.mobitru.com
export DEVICE_FARM_API_KEY=mobitru_ak_...
export DEVICE_FARM_SLUG=your-slug

# 2. Automate
mobitru-mobile-cli device-list android
mobitru-mobile-cli device-use <serial>
mobitru-mobile-cli snapshot
mobitru-mobile-cli tap e3
mobitru-mobile-cli type "[email protected]" --submit
mobitru-mobile-cli screenshot
mobitru-mobile-cli device-release

Configuration

Credentials are resolved in order: env vars → ~/.mobitru-cli/config.json.

| Field | Env var | Description | |---|---|---| | baseUrl | DEVICE_FARM_BASE_URL | Mobitru REST API host | | apiKey | DEVICE_FARM_API_KEY | API key (mobitru_ak_...) | | slug | DEVICE_FARM_SLUG | Billing/workspace slug | | wid | DEVICE_FARM_WID | Workspace ID (default "0") |

mobitru-mobile-cli config          # inspect resolved credentials (api key redacted)

Session lifecycle

mobitru-mobile-cli device-list android                # ios | android
mobitru-mobile-cli device-use <serial>                # native session, 180-min lease
mobitru-mobile-cli device-use <serial> --duration=30  # custom lease in minutes
mobitru-mobile-cli device-use <serial> --web          # browser (web) session

mobitru-mobile-cli device-release                     # release cloud slot (always do this)
mobitru-mobile-cli stop                               # release + reset session state

⚠️ One active booking at a time. Switching devices requires device-release first, then a 30-60s cloud cleanup window before the released serial is re-bookable. Pick a different serial to recover faster.

Switching between native and web sessions on the same device is fast (~5-10s, booking preserved). Switching to a different device incurs the cleanup window.

Parallel devices

Drive multiple cloud devices in parallel by naming each session with -s/--session. Each session has its own daemon and its own active booking.

# Terminal 1 — Android
mobitru-mobile-cli -s android device-use <serial-a>
mobitru-mobile-cli -s android snapshot

# Terminal 2 — iOS, in parallel
mobitru-mobile-cli -s ios device-use <serial-b>
mobitru-mobile-cli -s ios snapshot

MOBITRU_CLI_SESSION=<name> sets a per-shell default so you don't have to type -s on every command. The -s flag overrides the env for a single invocation. Without either, commands resolve to the default session — fully backward-compatible.

mobitru-mobile-cli session-list        # what's running, on what device
mobitru-mobile-cli session-current     # which session this shell resolves to
mobitru-mobile-cli stop                # stop the current session (releases its device + cleans up)
mobitru-mobile-cli stop --all          # stop every session (releases every device)

Works on Linux, macOS, and Windows.

Commands

Observation

screenshot [--output=<path>]               # PNG to disk; stdout: { path, bytes }
snapshot [--output=<path>]                 # AX tree to disk; stdout: { path, refCount }
screen-size                                # device pixel dimensions

Interaction

tap <ref>                                  # tap an element by snapshot ref (e1..eN)
tap-at <x> <y>                             # tap raw pixel coordinates
type <text> [--submit]                     # type into focused field; --submit presses ENTER
swipe <up|down|left|right> [--force=0.5]   # full-screen directional gesture
continuous-swipe <x,y> <x,y> [...]         # multi-point drag (2..20 points)
press <HOME|BACK|VOLUME_UP|VOLUME_DOWN|ENTER|DPAD_*>
get-orientation | set-orientation <portrait|landscape>

Web session

open-url <url>                             # navigate the device browser (--web sessions only)
click-web-element <selector>               # CSS selector click

Apps

launch <app-id>                            # com.android.chrome / com.apple.mobilesafari
terminate <app-id>
is-installed <app-id>
install-app <artifact-id>                  # blocks until installation completes
install-app-ota <ota-url>                  # iOS only — install from OTA manifest
uninstall-app <app-id>

Artifacts

artifacts-list
artifacts-info <id>
artifacts-upload <file> [--alias=<name>]   # APK or IPA; target auto-detected by extension
artifacts-download <id> [--output=<path>]

Bookings (future reservations)

bookings-list [--till=<iso>]
bookings-info <id>
booking-create --name=<n> --start=<iso> --end=<iso> --devices=<serial>[,<serial>...] [--private]
booking-cancel <id>

Recording, logs, crashlogs

recording-start                            # screen video; returns max-duration
recording-stop                             # returns recordingId
recording-download <recordingId> [--output=<path>]
logs-start | logs-stop                     # device logs (logcat / syslog)
crashlogs [--output=<path>]                # zip of crash reports

Network conditions

throttling-presets                         # list named presets
throttling-status
throttling-enable <preset>                 # 3g, 4g, edge, custom, ...
throttling-enable custom --download=<kbps> --upload=<kbps> --latency=<ms>
throttling-disable

geolocation-get | geolocation-set <lat> <lng>
ip-location-list | ip-location-set <country-code|DEFAULT>

HTTP traffic, profiler, mock injection

http-inspection-start [--capture-binary] [--no-capture-response-content]   # Android only
http-inspection-stop
har-download <har-id> [--output=<path>]

profiler-start <appPackage>                # target must be running
profiler-stop [--output=<path>]

inject-image <path> [--content-type=<mime>] [--name=<file>]   # camera frame mock
inject-touch <valid|invalid>                                  # biometric mock

Test runs

espresso-run --app=<id> --test=<id> --runner=<class> [--serial=<s>] [--filter=...] [--shards=N]
xcuitest-run --serial=<s> --app=<id> --test=<id> [--no-resign]
espresso-list | espresso-status <run-id> | espresso-cancel <run-id>
xcuitest-list | xcuitest-status <run-id> | xcuitest-cancel <run-id>

Appium scripts (custom WebDriver tests)

appium-run <script.js> [--timeout=<ms>] [--capabilities=<json>]
appium-status | appium-logs | appium-cancel

Lifecycle

status                                     # show session state
stop                                       # release device + reset session
config                                     # inspect resolved credentials

Artifacts

Auto-generated files (screenshots, snapshots, recordings, logs, …) land in the artifact directory:

| Setting | Path | |---|---| | Default | <CWD>/.mobitru-mobile-cli/ | | Override | MOBILE_CLI_OUTPUT_DIR=/your/path mobitru-mobile-cli ... |

The artifact dir is resolved per-invocation from the shell CWD. If you cd between commands, files land relative to the new CWD. Pass --output=<absolute-path> for unambiguous placement, or stay in one directory for the duration of a session.

Agent skill

Install the bundled skill so your agent knows how to use the CLI:

mobitru-mobile-cli install --skills=claude     # → .claude/skills/mobitru-mobile-cli/
mobitru-mobile-cli install --skills=agents     # → .agents/skills/mobitru-mobile-cli/