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"

Auto-configuration: If no config exists, Mobilerun creates a default config.yaml at ~/.config/mobilerun/config.yaml automatically.

Commands

run
Device Management
Macros

Execute natural language commands on your device.

Usage

mobilerun run "<command>" [OPTIONS]

Common Flags

Flag	Description	Default
`--agent`, `-a`	External agent to use (not yet supported — reserved for future use)	None
`--provider`, `-p`	LLM provider (GoogleGenAI, OpenAI, Anthropic, etc.)	From config
`--model`, `-m`	Model name	From config
`--device`, `-d`	Device serial or IP	Auto-detect
`--steps`	Max execution steps	`15`
`--reasoning`	Enable planning mode	`false`
`--vision`	Enable vision for all agents	From config
`--tcp`	Use TCP instead of content provider	`false`
`--debug`	Verbose logging	`false`
`--save-trajectory`	Save execution (`none`, `step`, `action`)	`none`
`--config`, `-c`	Custom config path	`~/.config/mobilerun/config.yaml`

Examples

Basic
LLM Providers
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.1-flash-lite-preview

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

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

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

# 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`
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	`uv pip install 'mobilerun[deepseek]'`	`DEEPSEEK_API_KEY`

`mobilerun devices`

List connected devices.

mobilerun devices
# Output:
# Found 2 connected device(s):
#   • emulator-5554
#   • 192.168.1.100:5555

`mobilerun setup`

Install Portal APK on device.

# Auto-detect device
mobilerun setup

# Specific device
mobilerun setup --device emulator-5554

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

What it does:

Downloads compatible Portal APK for your SDK version
Installs with all permissions
Auto-enables accessibility service
Opens settings if manual enable needed

`mobilerun ping`

Test Portal connection.

# 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!

`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 device subcommands support --device, --config, --tcp, and --ios flags.

Record and replay automation sequences.

`mobilerun macro list`

List saved trajectories.

# Default directory
mobilerun macro list

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

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

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`

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)
Config file (~/.config/mobilerun/config.yaml)
Defaults (lowest)

Common Patterns

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

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

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

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
`ANTHROPIC_API_KEY`	Anthropic API key	None
`DEEPSEEK_API_KEY`	DeepSeek API key	None
`MOBILERUN_CONFIG`	Config file path	`~/.config/mobilerun/config.yaml`

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

Common Flags

Examples

Provider Options

`mobilerun devices`

`mobilerun setup`

`mobilerun ping`

`mobilerun connect`

`mobilerun disconnect`

`mobilerun device`

`mobilerun macro list`

`mobilerun macro replay`

Recording Trajectories

Configuration

Override Priority

Common Patterns

Troubleshooting

Environment Variables

Next Steps

​Overview

​Quick Start

​Commands

​Usage

​Common Flags

​Examples

​Provider Options

​mobilerun devices

​mobilerun setup

​mobilerun ping

​mobilerun connect

​mobilerun disconnect

​mobilerun device

​mobilerun macro list

​mobilerun macro replay

​Recording Trajectories

​Configuration

​Override Priority

​Common Patterns

​Troubleshooting

​Environment Variables

​Next Steps

Overview

Quick Start

Commands

Usage

Common Flags

Examples

Provider Options

`mobilerun devices`

`mobilerun setup`

`mobilerun ping`

`mobilerun connect`

`mobilerun disconnect`

`mobilerun device`

`mobilerun macro list`

`mobilerun macro replay`

Recording Trajectories

Configuration

Override Priority

Common Patterns

Troubleshooting

Environment Variables

Next Steps