CLI Reference

Overview

Both tools speak to the same automation stack, but they are built for different jobs. Pick mobai when you are exploring, scripting, or debugging on a machine with the desktop app running. Pick mobai-ci when a pipeline needs to boot a device, run a suite, and produce reports without a desktop app anywhere.

Install

mobai

# global install
npm install -g @mobai-app/cli

# one-off, no install
npx @mobai-app/cli devices list

# as a dev dependency of a test project
npm install -D @mobai-app/cli

npm installs the meta package plus the one native binary matching your platform (macOS arm64/x64, Linux x64/arm64, Windows x64). Node 18+ is only needed for the install shim; the CLI itself is a Go binary.

mobai-ci

# GitHub Actions
- uses: MobAI-App/mobai-ci@v1

# anywhere else
curl -fsSL https://raw.githubusercontent.com/MobAI-App/mobai-ci/main/install.sh | sh

Pin a version with MOBAI_CI_VERSION=x.y.z.

Global Flags

Accepted by every mobai subcommand. Each has an environment variable, so a shell session or CI step can set the target once.

# point a whole session at one device on another machine
export MOBAI_URL=http://192.168.1.40:8686
export MOBAI_DEVICE=00008101-000A4D2E1234001E

mobai app launch com.example.app
mobai tap "id:login_btn"

Selectors

Every command that targets an element takes the same selector string: coordinates, percentages, or a predicate built from comma-separated keys.

"300,500"                             # pixel coordinates
"50%,30%"                             # percent of screen size, portable across devices
"id:login_btn"                        # accessibility id
"text-contains:Login,type:button"     # combined predicate

Predicates are the same ones the DSL uses. See the predicate reference for full semantics.

Exit Codes

mobai distinguishes failure kinds so a script can branch on them instead of parsing output.

mobai-ci uses three:

Devices & Bridge

$ mobai devices list
iOS      iPhone 15 Pro          00008101-000A4D2E1234001E   ready
Android  Pixel 7                39061FDJH00CBP              ready

$ mobai devices info --json | jq .platform
"ios"

The bridge auto-starts on the first device request, so bridge start is only needed when you want to pay that cost up front.

Interaction

mobai tap "id:login_btn"
mobai type "[email protected]" --clear --into "id:email_field"
mobai press enter

# scroll a long list until the row shows up, then act on it
mobai scroll down --to "text-contains:Advanced" --max-scrolls 15
mobai toggle "type:switch,near:Advanced" --state on

# drag a card onto another one
mobai drag --from "id:card_a" --to "id:card_b" --duration-ms 800

Observation

# the default: just the UI tree
mobai observe

# visible elements plus a screenshot, as JSON
mobai observe --include ui_tree,screenshot --only-visible true --json

# wait for the screen to settle after a transition
mobai wait --stable --timeout-ms 5000

mobai screenshot --path ./artifacts --name checkout --full

Assertions

Assertions exit with code 6 when they fail, so they drop into shell scripts and CI steps without extra glue.

mobai tap "id:submit"
mobai wait "text-contains:Welcome" --timeout-ms 8000
mobai assert exists "id:home_tab" || { echo "login broke"; exit 1; }

Apps

mobai app install ./build/MyApp.ipa
mobai app launch com.example.myapp
mobai app list --json | jq -r '.[].bundle_id'

Web Automation

Drives page content through Safari WebInspector on iOS and Chrome remote debugging on Android. Browser chrome (address bar, tabs) stays native automation; the DOM is web automation.

mobai web pages
mobai web select 1
mobai web navigate https://example.com/login
mobai web type "#email" "[email protected]"
mobai web click "button[type=submit]"
mobai web js "document.title"

Metrics & Recording

mobai metrics start
mobai app launch com.example.myapp
mobai scroll down --amount full
mobai metrics stop --json > perf.json

Location & Siri

mobai location set --lat 37.7749 --lon -122.4194
mobai siri "Search YouTube for cat videos"

If Siri asks a follow-up question, reformulate the prompt with more detail and run it again.

Debugging

Live lldb control of an iOS app: attach, break, step, and evaluate expressions while automation drives the UI.

mobai debug attach --bundle-id com.example.myapp
mobai debug breakpoint "CheckoutViewModel.submit"
mobai tap "id:pay_button"
mobai debug state --vars
mobai debug eval "po self.cart.total"
mobai debug detach

Running Tests

Runs a whole test file on the target device and reports per-step results. The file extension picks the parser: .mob for MobAI scripts, .yaml or .yml for Maestro flows.

mobai test ./flows/checkout.mob -p [email protected]
mobai test ./flows/login.yaml -P ./flows

A file outside the current directory falls back to using its own directory as the project root. For suites, reports, and CI, use mobai-ci instead.

Desktop & Skills

# bootstrap a fresh machine from the CLI alone
npm install -g @mobai-app/cli
mobai desktop install
mobai desktop launch
mobai skills install ~/.claude/skills

Overview

Runs .mob scripts and Maestro YAML flows against a local device, a machine you own, or a rented cloud device. It writes JUnit, every explicit screenshot step's image, and an automatic screenshot plus UI tree for each failure.

Target flags (test, install, devices)

Running Flows

mobai-ci test ./flows --app ./build/MyApp.app --output reports
mobai-ci test ./flows --shard 2/4 --timeout 20m --test-timeout 3m
mobai-ci validate ./flows        # parse only, no device needed

mobai-ci test attaches to a running device, it does not boot one. Boot first with sim boot / emu boot. With exactly one device running it is auto-detected.

iOS Simulators

sim boot creates a test-ready simulator and prints its UDID as the last line, so a pipeline can capture it. The boot continues in the background: pass the UDID to test with --wait-device and overlap it with your build.

# boot in the background, build meanwhile, then run
UDID=$(mobai-ci sim boot --cache ~/.cache/mobai-sim | tail -1)
xcodebuild -scheme MyApp -destination 'generic/platform=iOS Simulator' build
mobai-ci test ./flows --device "$UDID" --wait-device 4m --app "$APP_PATH"

Run sim boot before any other Xcode or simulator step in the job. sim prepare takes the same flags and builds the reusable image without booting a test simulator, which suits a scheduled job that warms the cache.

Slim Simulators

A stock iOS simulator runs a few hundred background daemons that a test never touches: Siri, Photos analysis, iCloud sync, lock screen posters, News, Spotlight indexing. Turning them off is what lets one machine host several simulators at once. simslim is our open-source tool for that, and mobai-ci applies it for you.

# 1. build a profile once, interactively, and commit it
brew install mobai-app/tap/simslim
simslim profile ./ci/slim.json

# 2. pass it on every run
mobai-ci sim boot --cache ~/.cache/mobai-sim --slim ./ci/slim.json

The profile file is required rather than implied by a bare flag. Disabling services changes what your tests can exercise, and the committed file is the record of exactly which capabilities you gave up. A profile that leaves everything enabled is rejected, and an unknown category or daemon name fails in seconds, before any simulator work starts.

simslim profiles lists every category with its daemon count and what breaks when it is off. simslim doctor <udid> --requires push,storekit checks a booted simulator against the features you depend on and exits non-zero when slimming broke one.

Android Emulators

SERIAL=$(mobai-ci emu boot --api 35 --cache ~/.cache/mobai-emu | tail -1)
mobai-ci test ./flows --device "$SERIAL" --wait-device 4m

--cache is required. The first run prepares a reusable image, which can take several minutes; later runs resume from it in seconds. emu prepare builds the image without leaving an emulator running.

Remote Devices

Point the runner at a machine you own: an office Mac, a lab box, or a self-hosted runner with real devices attached. The runner talks to that host's MobAI HTTP API, and how the address is reachable (Tailscale, cloudflared, SSH tunnel, or the same LAN) is your choice. Pro, needs MOBAI_API_KEY.

mobai-ci test ./flows \
  --mobai-addr https://mac-mini.tailnet.ts.net:8686 \
  --token "$MOBAI_TOKEN" \
  --device "iPhone 15 Pro" --wait

Remote runs claim the device for the duration: the host rejects other runners that try to drive it and frees the claim on release, or after a TTL if the runner dies. --wait queues for a free device instead of failing when every match is leased.

Cloud Device Farms

Run the flows on a device you rent from BrowserStack, Sauce Labs, or AWS Device Farm, from any runner, with no simulator or emulator needed. Pro, needs MOBAI_API_KEY, and uses your own farm account.

mobai-ci devices --cloud saucelabs        # list valid device names

mobai-ci test ./flows \
  --cloud saucelabs \
  --device "iPhone 14" --os 16 \
  --app ./build/MyApp.ipa \
  --output reports

--app takes a local .ipa or .apk, which is uploaded for you, or an already-uploaded provider reference. --timeout defaults to 30m on cloud runs, and the rented session always ends when the run finishes, fails, times out, or is cancelled.

CI Example

A complete GitHub Actions job on a hosted macOS runner. Nothing leaves the runner, and the simulator boot overlaps the app build.

name: Mobile smoke (iOS simulator)
on: [pull_request]

jobs:
  smoke:
    runs-on: macos-14
    steps:
      - uses: actions/checkout@v4
      - uses: MobAI-App/mobai-ci@v1

      # reuse the prepared simulator image across runs
      - uses: actions/cache@v4
        with:
          path: ~/.cache/mobai-sim
          key: mobai-sim-${{ runner.os }}-v1

      # boot first, before any other Xcode step
      - name: Boot simulator
        run: echo "UDID=$(mobai-ci sim boot --cache ~/.cache/mobai-sim --slim ./ci/slim.json | tail -1)" >> "$GITHUB_ENV"

      - name: Build app
        run: |
          xcodebuild -scheme MyApp -destination 'generic/platform=iOS Simulator' \
            -configuration Debug -derivedDataPath build build
          echo "APP_PATH=$(find build/Build/Products -name '*.app' -type d | head -1)" >> "$GITHUB_ENV"

      - name: Run flows
        run: mobai-ci test ./flows --device "$UDID" --wait-device 4m --app "$APP_PATH" --output reports

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: mobai-reports
          path: reports

Ready-to-copy workflows for simulators, remote devices over Tailscale, and cloud farms live in the repo.