Skip to main content

Quick start: Command line

Start a session on a device, launch Settings, tap a row, take a screenshot, and quit — from the command line. Starts with mobium session start --platform android --app com.android.settings; ends with mobium session end.

Before this page: install mobium and prepare a device.

1. What you need​

Nothing beyond mobium itself on your PATH.

2. The code​

Save this as quickstart.sh — it is examples/cli/quickstart.sh.

#!/bin/sh
# Mobium quick start from the command line: start a session, drive Settings,
# quit.
#
# MOBIUM_PLATFORM=android sh quickstart.sh # or ios
set -e
PLATFORM="${MOBIUM_PLATFORM:-android}"
if [ "$PLATFORM" = ios ]; then
APP=com.apple.Preferences ROW=General NEXT="label=About,role=button"
else
APP=com.android.settings ROW="Network & internet" NEXT="text=Airplane mode"
fi
# With one device running, no --device is needed; MOBIUM_DEVICE picks one of several.
if [ -n "$MOBIUM_DEVICE" ]; then set -- --device "$MOBIUM_DEVICE"; else set --; fi

# 1. Start the session: the driver is started on the device and Settings is
# launched. Every command after it uses this session. Quit it however the
# script ends.
mobium session start --platform "$PLATFORM" --app "$APP" "$@"
trap 'mobium session end "$@"' EXIT

# 2. Map the screen: every element you can act on, each with a @ref.
mobium map "$@" | head -5

# 3. Tap a row by its ref, then wait for the screen it opens. A row's label can
# carry its summary too ("Network & internet Mobile, Wi-Fi, ..."), so match
# its start: the label begins right after the ref.
REF=$(mobium map "$@" | awk -v row="$ROW" 'index($0, $1 " " row) == 1 {print $1; exit}')
mobium tap "$REF" "$@"
mobium wait "$NEXT" "$@"

# 4. Take a screenshot.
mobium screenshot -o "quickstart-$PLATFORM.png" "$@"

Settings is on every Android and iOS device with nothing to install. The row and the screen after it are the only things that differ by platform.

3. Run it​

Android​

MOBIUM_PLATFORM=android sh quickstart.sh

What it printed on an Android 17 emulator:

waiting for the UiAutomator2 server to start...
session started on emulator-5556 (android, uiautomator2); com.android.settings was launched fresh and is in the foreground
@e1 Search Settings (button)
@e2 main_content_scrollable_container (list)
@e3 Google Services & preferences (button)
@e4 Network & internet Mobile, Wi‑Fi, hotspot (button)
@e5 Connected devices Bluetooth, pairing (button)
tapped @e4 at (540, 713)
text=Airplane mode is visible after 1.156s — @e5 Airplane mode (switch, unchecked)
saved /tmp/quickstart/quickstart-android.png (131411 bytes)
session ended on emulator-5556; anything it changed for the session is put back; com.android.settings, which the session launched, was stopped
After startAfter the tap
Settings, as start left itThe screen the tap opened

iOS​

MOBIUM_PLATFORM=ios sh quickstart.sh

What it printed on an iOS 27.0 simulator:

waiting for WebDriverAgent to start...
the simulator is on its home screen: a new session starts WebDriverAgent, whose runner takes the foreground and leaves it to the home screen, not to the app that was in front — app_launch brings an app back...
session started on B2580DC0-1C76-4B2E-ADD3-802A58033078 (ios, wda); com.apple.Preferences was launched fresh and is in the foreground
@e1 com.apple.settings.sidebar.collectionView (list)
@e2 Apple Account, Sign in to access your iCloud data, the App Store, Apple services, and more. (button)
@e3 Optimizing Search and Siri (button)
@e4 General (button)
@e5 Accessibility (button)
tapped @e4 at (603, 1219)
label=About,role=button is visible after 447ms — @e2 About (button)
saved /tmp/quickstart/quickstart-ios.png (309298 bytes)
session ended on B2580DC0-1C76-4B2E-ADD3-802A58033078; anything it changed for the session is put back; com.apple.Preferences, which the session launched, was stopped
After startAfter the tap
Settings, as start left itThe screen the tap opened

The first start on a device is slow: it installs the UiAutomator2 server on Android, and on a real iPhone builds WebDriverAgent. Later starts take seconds.

Notes​

  • Every command after session start uses that session, so none of them needs --driver. With more than one device attached, pass the same --device to each.
  • mobium session status lists the sessions open. mobium daemon stop ends all of them at once.
  • With more than one device of the session's platform running — two Android devices, or two among the booted simulators and attached iPhones — start refuses to guess and lists them. One Android device and one iOS device are not ambiguous: the platform picks. Name one with MOBIUM_DEVICE=<serial or UDID>, which the example passes on as the device.

Next: the rest of the tool surface, and setting up phones and simulators. Changing the client itself? DEVELOPMENT.md is the contributor's guide.