Skip to content

Latest commit

 

History

History
349 lines (287 loc) · 14.6 KB

cli.md

File metadata and controls

349 lines (287 loc) · 14.6 KB

The command line

mobium is one binary, and every command is one call to one of Mobium's tools — the same tools an MCP client and the five language clients call, so the command line cannot do something they cannot. This guide is how the commands fit together: the loop, sessions and the daemon, the flags every command takes, reading answers from a script, and exit statuses.

Every command and every line of output below is what mobium printed on 2026-09-28 against MobiumApp on an Android 15 emulator. Where output is trimmed or a path shortened, it says so. The full list of commands and what each takes is generated: API.md and FLAGS.md.

Contents

1. Which devices

$ mobium --version
mobium version 0.1.0-dev

$ mobium devices
emulator-5554                          device     (android emulator, model: sdk_gphone64_arm64, Android 15 (API 35), navigation: gestures)

(Trimmed: the Mac also listed its iOS simulators, shut down, and a phone.) To start one, mobium boot <avd | simulator> boots an Android emulator by its AVD's name, or an iOS simulator by its name or UDID, and answers once it has booted. With one device running, no command needs to be told which; with several, --device <serial or udid> picks one, on every command.

2. A session

A session is a device made ready — its automation server started — with, optionally, an app launched fresh:

$ mobium session start --platform android --app dev.mobium.mobiumapp
waiting for the UiAutomator2 server to start...
session started on emulator-5554 (android, uiautomator2); dev.mobium.mobiumapp was launched fresh and is in the foreground

$ mobium session status
open: emulator-5554 (android, uiautomator2)

Every command after it uses that session. session end closes it, and puts back anything it changed for the session — network conditions, accessibility settings — and stops the app it launched:

$ mobium session end
session ended on emulator-5554; anything it changed for the session is put back; dev.mobium.mobiumapp, which the session launched, was stopped

A session is not required: any command opens one on first use. Starting one says which device and app a run is about, and ending it is how a run cleans up after itself.

3. The loop: map, act, map

map lists what on the screen can be acted on, each with a ref:

$ mobium map
@e1 homeList (list)
@e2 WebViews (button)
@e3 Login Demo (button)
@e4 OTP Demo (button)
@e5 Location Demo (button)
@e6 Pager Demo (button)
@e7 Interruption Demo (button)
@e8 Form Demo (button)
@e9 Gestures (button)
@e10 Motion Demo (button)
@e11 Crash Demo (button)
@e12 Storage Demo (button)
@e13 Dialog Demo (button)

Act on one, and map again — the screen has changed, and refs from before belong to the screen that is gone:

$ mobium tap label=Login Demo
tapped label=Login Demo at (540, 814)

$ mobium map
@e1 ScrollView (list)
@e2 Back (button)
@e3 username (input)
@e4 password (password)
@e5 Log In (button)
Before: map lists the buttons After the tap: the fields, and password marked as one
MobiumApp's home screen, a column of demo buttons The Login Demo: username and password fields, and Log In

A password field is labeled by its id and given the role password; what is typed into one is never printed, by map or any other command.

map --diff answers only what changed since the last map of the device — + appeared, - went away, ~ changed label, checked state or place — which is what the action just did; its refs are the new map's either way.

4. Locators and refs

Anything that takes a target takes either:

  • a ref from the last map — @e3 — short, and valid until the screen changes; or
  • a locator — testid=username, label=Login Demo, text=Sign in, role=button — which survives across screens and runs, and is what a script or a test should use. testid= is the one that survives a translation and a redesign.

A string locator matches part of the words, in any case: text=Internet finds "Network & internet". Put the value in double quotes to match the whole of it — text="Internet" finds only an element whose text is Internet, in any case, so Android's capitals still match — which is what a wait after a tap wants, since a part of a word on the screen being left would meet it at once. A quoted value may contain commas; \" is a quote inside it, and ,role= may follow it: label="Allow Paste",role=button.

within scopes a locator to a row: label=More within text=Card 8 is the More in the row that says Card 8. Of the target's matches it keeps the one nearest the anchor, and never reaches past the list holding the anchor, so a row without the target finds nothing rather than the target of the row beside it. Both sides are whole locators — text="Delete",role=button within label="Draft 2" — and are resolved again on every read, since a list reuses its rows as it scrolls. This is what a test file uses on a list, where a ref is gone with the map it came from; a value containing the word "within" is quoted.

,nth= picks one of several on purpose: label=Delete,nth=3 is the third Delete shown, counted as a person reads the screen — top to bottom, then left to right along a row — from 1. Only what is shown counts, so the count does not move with rows kept off screen; past the last, nothing matches. It comes last, after any ,role=. It is brittle, since a row added above moves it: prefer within where a row says which.

Inside a WebView, after mobium context WEBVIEW_…, a locator matches what map reads of the page: text= and label= an element's accessible name, testid= its data-testid or id, role= its role — quotes and ,nth= as above, counted down the page. css= takes a CSS selector: mobium tap 'css=button.save', with a frame's path before it as map prints one, 'css=iframe#f >> button'. Only what map lists can be named, since that is what an action can touch. within is for native screens; a selector says what is inside what.

A locator that matches more than one element is refused, never guessed at; append a role — label=Apps,role=button — or use a ref. Every action waits for its target to be ready before it touches it — auto-wait is the whole story.

5. Answers for a script: --json

Every command's answer has a text half, for a person, and a structured half, which --json prints instead:

$ mobium fill testid=username mobium
typed "mobium" into testid=username

$ mobium --json find testid=username
{
  "context": "NATIVE_APP",
  "device": "emulator-5554",
  "elements": [
    {
      "bounds": {
        "x1": 42,
        "x2": 1038,
        "y1": 1027,
        "y2": 1153
      },
      "label": "mobium",
      "locator": {
        "exact": true,
        "kind": "testid",
        "value": "username"
      },
      "ref": "@e3",
      "role": "input"
    }
  ]
}

Bounds are device pixels. Read the structured half from code, never the text, which is written for a person and may change.

6. When a command fails

A failure says what happened and what to do about it, and exits with a status that says what kind of failure it was:

$ mobium tap testid=noSuchButton
error: no element matches testid=noSuchButton on the current screen — the screen may have changed, run app_map again

With --json, the same failure as data — its code, its remedy, whether retrying could help:

$ mobium --json tap testid=noSuchButton; echo $?
{
  "error": "no element matches testid=noSuchButton on the current screen — the screen may have changed, run app_map again",
  "code": "no_such_element",
  "message": "no element matches testid=noSuchButton on the current screen — the screen may have changed, run app_map again",
  "remedy": "run app_map again, or app_scroll_to if it may be off screen",
  "retryable": false,
  "details": {
    "locator": "testid=noSuchButton"
  }
}
4
Exit status Codes Meaning
0 — it did what was asked, and checked
2 invalid_argument the command was wrong — nothing on any device could make it work
3 no_device, device_not_ready, toolchain_missing no device, or one not ready: locked, not answering, a tool missing
4 no_such_element, ambiguous_locator, element_not_reachable, no_such_context, no_such_alert the target was not there, was two things, or could not be reached — a dialog or the keyboard over it included
5 unsupported this device or driver cannot do it — retrying will not help
6 timeout it did not happen in time — the one kind worth retrying as it is
7 not_confirmed the command ran and reading back says it did not take — a finding
8 not_permitted whoever started Mobium does not allow it: read-only, or an app outside its app list — only they can change that
1 device_server, internal, error the device side failed, Mobium has a bug, or the failure is unclassified — read the message

The codes are the same in every client, as exceptions, and on the MCP wire, in structuredContent. Adding a code is safe; renaming or removing one would break every client that catches it, so they do not change:

Code Means
no_device nothing to drive
device_not_ready there, and not drivable yet: locked, not trusted, Developer Mode off, not answering — the device only
toolchain_missing missing on this machine: adb, Xcode, a signing certificate, a device agent that would not download or build
no_such_element a locator or ref matched nothing on screen; worth scrolling for
ambiguous_locator matched more than one; narrow it — Mobium never guesses
element_not_reachable not touchable where it is: off the screen, or covered — by a dialog, the keyboard, another screen or a control, each named in details with check: receivesEvents
no_such_context a WebView context that is not there
no_such_alert a dialog was expected and none is up
unsupported this backend or platform cannot, and says why
timeout a wait ran out
not_confirmed the command said it worked and reading the state back disagreed
invalid_argument the request itself is wrong, or the command line was refused
not_permitted the policy Mobium was started with refuses it: MOBIUM_READ_ONLY, MOBIUM_APPS, or mobium mcp --read-only/--apps
device_server the device side failed — a device server, or adb, simctl, devicectl, lockdown — in a way no narrower code names; a server's own W3C code is in details.w3c
internal a bug in Mobium
error unclassified: a daemon too old to send a code, or a code a client does not know

Decide by the code, never by matching the message's words: the wording can improve, the code is the contract.

7. Several steps in one call: batch

A known sequence can go as one call — from a file, or - for stdin. Every step is checked before the first runs, and it stops at the first failure, with that step's own error:

[
  {"name": "app_tap", "arguments": {"target": "label=Login Demo"}},
  {"name": "app_fill", "arguments": {"target": "testid=username", "text": "mobium"}},
  {"name": "app_fill", "arguments": {"target": "testid=password", "text": "hunter2"}},
  {"name": "app_tap", "arguments": {"target": "testid=loginBtn"}},
  {"name": "app_wait_for", "arguments": {"target": "testid=welcomeText"}}
]
$ mobium batch steps.json
1. app_tap: tapped label=Login Demo at (540, 814)
2. app_fill: typed "mobium" into testid=username
3. app_fill: typed 7 characters into testid=password, a password field — not echoed
4. app_tap: tapped testid=loginBtn at (540, 1457)
5. app_wait_for: testid=welcomeText is visible after 1.637s — (no ref) Welcome, mobium! [42,334][1038,412]

The Login Demo after the batch: "Welcome, mobium! You are logged in."

The same steps, with assertions and a report, are a test: mobium test.

8. The daemon, and running several at once

The first command starts a daemon in the background, which holds the device sessions and the refs between commands, and exits after 30 idle minutes:

$ mobium daemon status
Daemon running (pid 4156, up 8s)
  version 0.1.0-dev
  socket  ~/.mobium/daemon/mobium.sock

(The home directory is shortened to ~ here and below.) One daemon serves one call at a time. Two runs at once — two terminals, two CI jobs, two devices — should each have their own, named by MOBIUM_SESSION:

$ MOBIUM_SESSION=ci-android mobium current
waiting for the UiAutomator2 server to start...
dev.mobium.mobiumapp

$ MOBIUM_SESSION=ci-android mobium daemon status
Daemon running (pid 4384, up 1s)
  version 0.1.0-dev
  socket  ~/.mobium/daemon/mobium-ci-android.sock
  session ci-android

mobium daemon stop stops one, ending its sessions — stop it before shutting a device down, never after (SHUTDOWN.md). mobium shutdown <serial | avd | udid | simulator> ends this daemon's session on the device, then shuts the emulator or simulator down and returns once it is gone; a real phone is refused. It ends only its own daemon's session, so stop any other daemon on the device first. Keep session names short: a name is part of a socket path, which the OS caps at about 104 bytes.

The flags every command takes

Flag Does
--device <serial or udid> which device, when more than one is running
--driver <name> uiautomator2 (Android's default), uiautomator (Android, installs nothing on the device), wda (iOS simulators and iPhones), or a third-party driver
--json the structured answer instead of the text
--remote <[user@]host> drive another machine's devices, over SSH — the grid guide
-v, --verbose what mobium is doing, on stderr

mobium <command> --help has each command's own flags and examples, and mobium doctor checks the setup — the Android and iOS tools, the devices, the daemon — and names the fix for anything wrong.