CLI Usage

Overview

The Mobilerun CLI lets you control Android and iOS devices using natural language commands powered by LLM agents.

Quick Start

# Setup device
mobilerun setup

# Run a command
mobilerun run "Open Spotify and play my Discover Weekly"

Mobilerun creates config.yaml automatically in ~/.config/droidrun on Linux, ~/Library/Application Support/droidrun on macOS, or %LOCALAPPDATA%\droidrun\droidrun on Windows. Set MOBILERUN_CONFIG or pass --config to use another file.

Commands

Run mobilerun --version to print the installed package version.

run
Configure
Cloud Login
Device Management
Macros

Execute natural language commands on your device.

Usage

mobilerun run "<command>" [OPTIONS]

Flags

Flag	Description	Default
`--config`, `-c`	Explicit config file	`MOBILERUN_CONFIG`, then the platform config
`--device`, `-d`	Device serial/IP, iOS local-server URL, or visual-remote URL	From config / auto-detect
`--device-id`	Device to use when a server provides more than one	From config (`auto` initially)
`--agent`, `-a`	Android external agent name	From config (`mobilerun` initially)
`--provider`, `-p`	LLM provider override	From config
`--model`, `-m`	LLM model override	From config
`--temperature`	LLM temperature override	From the selected profile
`--steps`	Maximum execution steps	From config (`15` initially)
`--base_url`, `-u`	Base URL for providers such as Ollama or OpenRouter	Provider profile
`--api_base`	API base for OpenAI-compatible providers	Provider profile
`--vision` / `--no-vision`	Enable or disable screenshots for all agents	From config
`--vision-only` / `--no-vision-only`	Use screenshots without an accessibility tree	From config
`--reasoning` / `--no-reasoning`	Enable or disable Manager-Executor planning	From config
`--stream` / `--no-stream`	Stream LLM responses	From config
`--tracing` / `--no-tracing`	Enable or disable the configured tracing provider (Phoenix by default)	From config
`--debug` / `--no-debug`	Enable verbose logging	From config
`--tcp` / `--no-tcp`	Override Android TCP communication	From config
`--control-backend visual-remote`	Connect to a Visual Remote server	From config
`--save-trajectory`	Save execution at `none`, `step`, or `action` level	From config (`none` initially)
`--ios`	Use an iOS device	From config (`android` initially)

Pass --provider and --model together. Supplying only one causes the run to fail before the agent starts.

Examples

Basic
LLM Providers
Screenshot Only
Advanced

# Simple command
mobilerun run "Open Settings"

# Multi-step task
mobilerun run "Send WhatsApp to John: I'll be late"

# Specific device
mobilerun run "Check battery" --device emulator-5554

# Google Gemini
export GOOGLE_API_KEY=your-key
mobilerun run "Archive old emails" \
  --provider GoogleGenAI \
  --model gemini-3.7-flash

# OpenAI
export OPENAI_API_KEY=your-key
mobilerun run "Create shopping list" \
  --provider OpenAI \
  --model gpt-5.5

# xAI Grok
export XAI_API_KEY=your-key
mobilerun run "Open Settings" \
  --provider XAI \
  --model grok-4.6

# Anthropic Claude
export ANTHROPIC_API_KEY=your-key
mobilerun run "Reply to latest email" \
  --provider Anthropic \
  --model claude-sonnet-4-6

# Local Ollama (free)
mobilerun run "Turn on dark mode" \
  --provider Ollama \
  --model llama3.3:70b \
  --base_url http://localhost:11434

# Use screenshots without an accessibility tree
mobilerun run "Check Wi-Fi" --vision-only

# Use a compatible visual-remote server
mobilerun run "Check Wi-Fi" \
  --vision-only \
  --control-backend visual-remote \
  --device http://localhost:8090

Visual Remote controls the device from screenshots and coordinate-based actions. Some Visual Remote servers may not support opening apps.

# Complex task with planning
mobilerun run "Organize inbox by sender" \
  --reasoning \
  --vision \
  --steps 30

# Debug failing command
mobilerun run "Book Uber to airport" \
  --debug \
  --save-trajectory action

# Wireless execution
mobilerun run "Clear cache" \
  --device 192.168.1.100:5555 \
  --tcp

# Custom config
mobilerun run "Enable 2FA" \
  --config /path/to/config.yaml

Provider Options

Provider	Install	Environment Variable
GoogleGenAI	Included by default	`GOOGLE_API_KEY`
OpenAI	Included by default	`OPENAI_API_KEY`
XAI	Included by default	`XAI_API_KEY`
OpenAILike	Included by default	Varies by provider
OpenRouter	Included by default	`OPENROUTER_API_KEY`
Ollama	Included by default	None (local)
Anthropic	`uv pip install 'mobilerun[anthropic]'`	`ANTHROPIC_API_KEY`
DeepSeek	Included by default	`DEEPSEEK_API_KEY`
MiniMax	Included by default	`MINIMAX_API_KEY`
ZAI	Included by default	`ZAI_API_KEY`

The wizard supports API-key and OAuth sign-in. MiniMax uses separate global and Mainland China endpoints, and ZAI also offers Coding API authentication.

`mobilerun configure`

Run the wizard to choose a provider, sign-in method, and model.

# Interactive setup
mobilerun configure

# Skip the wizard questions (OAuth still requires approval if you are not signed in)
mobilerun configure \
  --provider openai \
  --auth-mode oauth \
  --model gpt-5.5

Flag	Description	Default
`--provider`	`gemini`, `openai`, `anthropic`, `xai`, `ollama`, `openai_like`, `minimax`, or `zai`	Prompted
`--auth-mode`	How to sign in to the provider	Prompted
`--model`	Model to save in every built-in agent profile	Prompted
`--api-key`	API key for an API-key provider	Existing saved key or prompt
`--base-url`	Compatible-provider base URL	Provider default or prompt

Use these commands to sign in with OAuth. Run mobilerun configure to change the saved provider or model.

mobilerun configure openai
mobilerun configure anthropic
mobilerun configure gemini
mobilerun configure xai

`mobilerun configure openai`

Authenticate a ChatGPT/OpenAI OAuth profile. The command uses a browser callback on desktop and can use a device-code flow in a headless environment.

Flag	Description	Default
`--credential-path`	OAuth credential file	Default credential file
`--model`	Optional model override for later API calls	Provider default
`--timeout`	Seconds to wait for authorization	`300`
`--callback-host`	Local callback host	`localhost`
`--callback-port`	Local callback port	`1455`
`--callback-path`	Local callback path	`/auth/callback`
`--open-browser` / `--no-browser`	Open the authorization URL automatically	`--open-browser`

`mobilerun configure anthropic`

Authenticate with Anthropic, or save an existing setup token without starting the browser flow.

mobilerun configure anthropic
mobilerun configure anthropic --token <setup-token>

Flag	Description	Default
`--credential-path`	Credential file	Default credential file
`--token`	Setup token to save instead of running OAuth	None
`--timeout`	Seconds to wait for authorization	`300`
`--open-browser` / `--no-browser`	Open the authorization URL automatically	`--open-browser`

`mobilerun configure gemini`

Authenticate a Gemini Code Assist OAuth profile.

Flag	Description	Default
`--credential-path`	OAuth credential file	Default credential file
`--model`	Optional model override for later API calls	Provider default
`--timeout`	Seconds to wait for authorization	`300`
`--callback-host`	Local callback host	`127.0.0.1`
`--callback-port`	Local callback port; `0` selects one automatically	`0`
`--callback-path`	Local callback path	`/oauth2callback`
`--open-browser` / `--no-browser`	Open the authorization URL automatically	`--open-browser`

`mobilerun configure xai`

mobilerun configure xai

# SSH or another headless machine
mobilerun configure xai --device-code --no-browser

For device-code login, open the printed URL, enter the code, and keep the code private.

Flag	Description	Default
`--credential-path`	OAuth credential file	Default credential file
`--model`	xAI model (`grok-4.6` or `grok-4.5`)	`grok-4.6`
`--timeout`	Seconds to wait for authorization	`300`
`--open-browser` / `--no-browser`	Open the authorization URL automatically	`--open-browser`
`--device-code`	Use device-code login	`false`

When you pass --credential-path, use the same path in the corresponding LLM profile.

Use these commands to sign in to Mobilerun Cloud for Cloud device listing and direct actions. LLM provider sign-in uses mobilerun configure.Run mobilerun login, open the verification link, enter the displayed code, and approve the sign-in. Mobilerun saves the session locally.

mobilerun login

# Advanced overrides
mobilerun login \
  --auth-url https://cloud.mobilerun.ai/api/auth \
  --client-id mobilerun-cli

Flag	Description	Default
`--auth-url`	Mobilerun Cloud authentication URL; `MOBILERUN_AUTH_URL` also overrides it	`https://cloud.mobilerun.ai/api/auth`
`--client-id`	OAuth device client id	`mobilerun-cli`

`mobilerun whoami`

Show the email and user ID for the current Cloud session.

mobilerun whoami

`mobilerun logout`

Sign out and remove the saved Cloud credential.

mobilerun logout

mobilerun devices and Cloud direct actions use MOBILERUN_CLOUD_API_KEY when it is set. Otherwise, they use the credential saved by mobilerun login. mobilerun whoami and mobilerun logout operate on the saved login. These commands do not use MOBILERUN_API_KEY.

`mobilerun devices`

List local Android devices and, when a Cloud credential is available, Mobilerun Cloud devices.

# Local devices, plus Cloud devices when a credential is available
mobilerun devices

# Only Mobilerun Cloud devices
mobilerun devices --cloud

Flag	Description	Default
`--cloud`	Skip ADB and list only cloud devices	`false`
`--base-url`	Cloud API base URL	`https://api.mobilerun.ai/v1`

Use --cloud to list only Cloud devices. It returns an error if authentication is missing or Cloud cannot be reached.

`mobilerun setup`

Install the Portal APK on an Android device. Without a version flag, Mobilerun selects the Portal release compatible with the installed Mobilerun version.

# Auto-detect device
mobilerun setup

# Specific device
mobilerun setup --device emulator-5554

# Custom APK
mobilerun setup --path /path/to/portal.apk

# Newest available Portal release
mobilerun setup --latest

# Pin a release
mobilerun setup --portal-version 0.7.1

Flag	Description	Default
`--device`, `-d`	Android serial or IP	Auto-detect
`--path`	Install an APK from a local path	Compatible download
`--portal-version`, `-pv`	Download a specific Portal version	Compatible version
`--latest`	Download the latest Portal instead of the compatible version	`false`
`--debug`	Enable verbose setup logging	`false`

What it does:

Downloads the compatible Portal APK
Installs it and grants the Android permissions allowed during installation
Attempts to enable the accessibility service
Opens settings if manual enable needed

To use Android through ADB without Portal, set device.portal_mode: disabled.

`mobilerun ping`

Test Portal with mobilerun ping. For an ADB-only setup, use adb devices -l.

# Test default communication
mobilerun ping

# Test TCP mode
mobilerun ping --tcp

# Specific device
mobilerun ping --device 192.168.1.100:5555

Success output: Portal is installed and accessible. You're good to go!

Flag	Description	Default
`--device`, `-d`	Android serial or IP	Auto-detect
`--tcp` / `--no-tcp`	Select Portal TCP communication	`false`
`--debug` / `--no-debug`	Enable verbose connection logging	`false`

`mobilerun doctor`

Run system and device diagnostics.

mobilerun doctor
mobilerun doctor --device emulator-5554 --debug

Flag	Description	Default
`--device`, `-d`	Device serial or IP	Auto-detect
`--debug` / `--no-debug`	Enable verbose diagnostic output	`false`

`mobilerun connect`

Connect to device via TCP/IP.

mobilerun connect 192.168.1.100:5555

Prerequisites:

# Enable wireless debugging (Android 11+)
# Settings > Developer options > Wireless debugging

# Or via USB:
adb tcpip 5555
adb shell ip route | awk '{print $9}'  # Get IP
mobilerun connect <IP>:5555

`mobilerun disconnect`

Disconnect from device.

mobilerun disconnect 192.168.1.100:5555

`mobilerun device`

Direct device actions that bypass the LLM agent.

# Take a screenshot
mobilerun device screenshot

# Print the UI accessibility tree
mobilerun device ui

# Tap at coordinates
mobilerun device tap 500 500

# Swipe from point to point
mobilerun device swipe 100 500 100 200 --duration 0.5

# Long press at coordinates
mobilerun device long-press 500 500

# Type text into focused field
mobilerun device type "Hello world" --clear

# Press a system button (back, home, enter)
mobilerun device press back

# List installed apps
mobilerun device apps --system

# Launch an app by package name
mobilerun device start com.example.app

All direct-action subcommands accept these common flags:

Flag	Description	Default
`--device`, `-d`	Local device serial/IP or Cloud device UUID	From config / auto-detect
`--config`, `-c`	Explicit Framework config file	`MOBILERUN_CONFIG`, then platform config
`--tcp` / `--no-tcp`	Override local Android TCP communication	From config
`--ios`	Target a local iOS device	`false`
`--cloud`	Target a Mobilerun Cloud device	`false`
`--device-id`	Cloud device id; `-d` also accepts it	None
`--base-url`	Cloud API base URL	`https://api.mobilerun.ai/v1`

Action-specific options are swipe --duration <seconds> (default 1.0), type --clear, and apps --system / --no-system.mobilerun device long-press is not available for local iOS devices.

Target a cloud device

Pass a Cloud device UUID with --cloud --device-id. When a Cloud credential is available, you can also pass the UUID with -d.

# Use --cloud explicitly
mobilerun device screenshot \
  --cloud \
  --device-id 7f1c1d2e-4b8a-4a3a-9a4d-1234567890ab

# Use an available Cloud credential
mobilerun device tap 500 500 \
  -d 7f1c1d2e-4b8a-4a3a-9a4d-1234567890ab

ADB serials target local devices.

Cloud direct actions support Android only.

Record and replay automation sequences.

`mobilerun macro list`

List saved trajectories.

# Default directory
mobilerun macro list

# Custom directory
mobilerun macro list /path/to/trajectories

Pass --debug to include load errors and other diagnostic output.Output:

Found 3 trajectory(s):

┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Folder           ┃ Description               ┃ Actions ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ open-settings    │ Opens settings app        │ 3       │
│ enable-dark-mode │ Navigate to display...    │ 8       │
└──────────────────┴───────────────────────────┴─────────┘

`mobilerun macro replay`

Replay recorded macro.

# Basic replay
mobilerun macro replay trajectories/open-settings

# Custom device and timing
mobilerun macro replay trajectories/login-flow \
  --device emulator-5554 \
  --delay 0.5

# Start from specific step
mobilerun macro replay trajectories/checkout \
  --start-from 5 \
  --max-steps 10

# Preview without executing
mobilerun macro replay trajectories/test --dry-run

# Continue with the agent if the replay no longer matches the screen
mobilerun macro replay trajectories/checkout \
  --on-mismatch agent \
  --config /path/to/config.yaml

Flags:

Flag	Description	Default
`--device`, `-d`	Device serial	Auto-detect
`--delay`, `-t`	Seconds between actions	`1.0`
`--start-from`, `-s`	Start step (1-based)	`1`
`--max-steps`, `-m`	Max steps to run	All
`--dry-run`	Preview only	`false`
`--debug`	Enable replay debug logging	`false`
`--on-mismatch`	`stop`, or `agent` to continue when the screen no longer matches the recording	`stop`
`--state-timeout`	Seconds to wait for the recorded screen state before each action	`5.0`
`--state-threshold`	Minimum similarity score (0–1) between the current and recorded UI state	`0.85`
`--config`	Config used by `--on-mismatch agent`	Default config
`--provider`	LLM provider used by `--on-mismatch agent`	From config
`--model`	LLM model used by `--on-mismatch agent`	From config

With --on-mismatch agent, Mobilerun uses your default configuration unless you pass --config or both --provider and --model.

Recording Trajectories

# Record at action level (most detailed)
mobilerun run "Create alarm for 7am" --save-trajectory action

# Record at step level
mobilerun run "Export contacts" --save-trajectory step

Trajectory structure:

trajectories/2025-10-16_14-30-45/
├── macro.json       # Action sequence
├── step_0.png       # Screenshots
├── step_1.png
└── ...

Configuration

Override Priority

CLI flags (highest)
Explicit --config file
MOBILERUN_CONFIG environment variable
Platform config file (for example, ~/.config/droidrun/config.yaml on Linux)
Built-in defaults (lowest)

Common Patterns

mobilerun run "Turn on dark mode" \
  --provider GoogleGenAI \
  --model gemini-3.5-flash-lite

mobilerun run "Book ride to airport" \
  --debug \
  --reasoning \
  --vision \
  --save-trajectory action

mobilerun run "Set alarm" \
  --provider GoogleGenAI \
  --model gemini-3.5-flash-lite \
  --no-vision

mobilerun run "Check Wi-Fi" \
  --vision-only \
  --control-backend visual-remote \
  --device http://localhost:8090

for device in $(adb devices | awk 'NR>1 {print $1}'); do
  mobilerun run "Clear notifications" --device $device
done

Troubleshooting

No devices found

# Check ADB
adb devices

# If unauthorized: Accept prompt on device
# If not listed: Try different USB port/cable
# Restart ADB
adb kill-server && adb start-server

Portal not accessible

# Verify installation
adb shell pm list packages | grep mobilerun

# Reinstall
mobilerun setup

# Enable accessibility manually
adb shell settings put secure enabled_accessibility_services \
  com.mobilerun.portal/com.mobilerun.portal.service.MobilerunAccessibilityService

LLM provider errors

# Install provider
uv pip install 'mobilerun[anthropic]'

# Check API key
echo $GOOGLE_API_KEY

# Set if missing
export GOOGLE_API_KEY=your-key

Command times out

# Increase steps
mobilerun run "Complex task" --steps 50

# Enable debug mode
mobilerun run "Task" --debug

# Try reasoning mode
mobilerun run "Multi-step task" --reasoning

TCP connection fails

# Enable TCP mode (USB connected first)
adb tcpip 5555

# Get device IP
adb shell ip route | awk '{print $9}'

# Connect
mobilerun connect <IP>:5555

# Verify
mobilerun ping --tcp

Environment Variables

For first-time setup, use mobilerun configure to interactively choose your provider and credentials. Environment variables below are useful for overrides and CI/CD.

Variable	Description	Default
`GOOGLE_API_KEY`	Google Gemini API key	None
`OPENAI_API_KEY`	OpenAI API key	None
`XAI_API_KEY`	xAI API key for Grok	None
`ANTHROPIC_API_KEY`	Anthropic API key	None
`DEEPSEEK_API_KEY`	DeepSeek API key	None
`OPENROUTER_API_KEY`	OpenRouter API key	None
`MINIMAX_API_KEY`	MiniMax API key	None
`ZAI_API_KEY`	ZAI API key	None
`MOBILERUN_CLOUD_API_KEY`	Cloud key for `devices --cloud` and cloud direct actions	None
`MOBILERUN_AUTH_URL`	Auth server used by `mobilerun login`	`https://cloud.mobilerun.ai/api/auth`
`MOBILERUN_CONFIG`	Override the Framework config path	Unset (platform config is used)
`MOBILERUN_DEVICE_TOKEN`	Bearer token for an authenticated `mobilerun-ios --local` server	None

Cloud device commands use MOBILERUN_CLOUD_API_KEY, not MOBILERUN_API_KEY.

Setting variables:

export GOOGLE_API_KEY=your-key

$env:GOOGLE_API_KEY="your-key"

echo 'export GOOGLE_API_KEY=your-key' >> ~/.bashrc
source ~/.bashrc

Next Steps

Configuration Guide - Customize behavior
Device Setup - Detailed setup instructions
Agent Architecture - How it works
Custom Tools - Extend functionality

Introduction

Features

Guides

Concepts

SDK Reference

Overview

Quick Start

Commands

Usage

Flags

Examples

Provider Options

`mobilerun configure`

`mobilerun configure openai`

`mobilerun configure anthropic`

`mobilerun configure gemini`

`mobilerun configure xai`

`mobilerun devices`

`mobilerun setup`

`mobilerun ping`

`mobilerun doctor`

`mobilerun connect`

`mobilerun disconnect`

`mobilerun device`

Target a cloud device

`mobilerun macro list`

`mobilerun macro replay`

Recording Trajectories

Configuration

Override Priority

Common Patterns

Troubleshooting

Environment Variables

Next Steps

​Overview

​Quick Start

​Commands

​Usage

​Flags

​Examples

​Provider Options

​mobilerun configure

​Provider OAuth login commands

​mobilerun configure openai

​mobilerun configure anthropic

​mobilerun configure gemini

​mobilerun configure xai

​mobilerun login

​mobilerun whoami

​mobilerun logout

​mobilerun devices

​mobilerun setup

​mobilerun ping

​mobilerun doctor

​mobilerun connect

​mobilerun disconnect

​mobilerun device

​Target a cloud device

​mobilerun macro list

​mobilerun macro replay

​Recording Trajectories

​Configuration

​Override Priority

​Common Patterns

​Troubleshooting

​Environment Variables

​Next Steps

Overview

Quick Start

Commands

Usage

Flags

Examples

Provider Options

`mobilerun configure`

Provider OAuth login commands

`mobilerun configure openai`

`mobilerun configure anthropic`

`mobilerun configure gemini`

`mobilerun configure xai`

`mobilerun login`

`mobilerun whoami`

`mobilerun logout`

`mobilerun devices`

`mobilerun setup`

`mobilerun ping`

`mobilerun doctor`

`mobilerun connect`

`mobilerun disconnect`

`mobilerun device`

Target a cloud device

`mobilerun macro list`

`mobilerun macro replay`

Recording Trajectories

Configuration

Override Priority

Common Patterns

Troubleshooting

Environment Variables

Next Steps