> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Usage

> Command-line interface for controlling devices with natural language

## Overview

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

### Quick Start

```bash theme={null}
# Setup device
mobilerun setup

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

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

***

## Commands

<Tabs>
  <Tab title="run">
    Execute natural language commands on your device.

    ### Usage

    ```bash theme={null}
    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

    <Tabs>
      <Tab title="Basic">
        ```bash theme={null}
        # 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
        ```
      </Tab>

      <Tab title="LLM Providers">
        ```bash theme={null}
        # 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
        ```
      </Tab>

      <Tab title="Advanced">
        ```bash theme={null}
        # 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
        ```
      </Tab>
    </Tabs>

    ### 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`   |
  </Tab>

  <Tab title="Device Management">
    ### `mobilerun devices`

    List connected devices.

    ```bash theme={null}
    mobilerun devices
    # Output:
    # Found 2 connected device(s):
    #   • emulator-5554
    #   • 192.168.1.100:5555
    ```

    ***

    ### `mobilerun setup`

    Install Portal APK on device.

    ```bash theme={null}
    # Auto-detect device
    mobilerun setup

    # Specific device
    mobilerun setup --device emulator-5554

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

    **What it does:**

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

    ***

    ### `mobilerun ping`

    Test Portal connection.

    ```bash theme={null}
    # 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.

    ```bash theme={null}
    mobilerun connect 192.168.1.100:5555
    ```

    **Prerequisites:**

    ```bash theme={null}
    # 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.

    ```bash theme={null}
    mobilerun disconnect 192.168.1.100:5555
    ```

    ***

    ### `mobilerun device`

    Direct device actions that bypass the LLM agent.

    ```bash theme={null}
    # 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.
  </Tab>

  <Tab title="Macros">
    Record and replay automation sequences.

    ### `mobilerun macro list`

    List saved trajectories.

    ```bash theme={null}
    # 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.

    ```bash theme={null}
    # 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

    ```bash theme={null}
    # 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
    └── ...
    ```
  </Tab>
</Tabs>

***

## Configuration

### Override Priority

1. **CLI flags** (highest)
2. **Config file** (`~/.config/mobilerun/config.yaml`)
3. **Defaults** (lowest)

### Common Patterns

<CodeGroup>
  ```bash Quick Test theme={null}
  mobilerun run "Turn on dark mode" \
    --provider GoogleGenAI \
    --model gemini-3.1-flash-lite-preview
  ```

  ```bash Debug Task theme={null}
  mobilerun run "Book ride to airport" \
    --debug \
    --reasoning \
    --vision \
    --save-trajectory action
  ```

  ```bash Cost Optimization theme={null}
  mobilerun run "Set alarm" \
    --provider GoogleGenAI \
    --model gemini-3.1-flash-lite-preview \
    --no-vision
  ```

  ```bash Multiple Devices theme={null}
  for device in $(adb devices | awk 'NR>1 {print $1}'); do
    mobilerun run "Clear notifications" --device $device
  done
  ```
</CodeGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="No devices found">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Portal not accessible">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="LLM provider errors">
    ```bash theme={null}
    # Install provider
    uv pip install 'mobilerun[anthropic]'

    # Check API key
    echo $GOOGLE_API_KEY

    # Set if missing
    export GOOGLE_API_KEY=your-key
    ```
  </Accordion>

  <Accordion title="Command times out">
    ```bash theme={null}
    # Increase steps
    mobilerun run "Complex task" --steps 50

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

    # Try reasoning mode
    mobilerun run "Multi-step task" --reasoning
    ```
  </Accordion>

  <Accordion title="TCP connection fails">
    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

***

## Environment Variables

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

| 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:**

<CodeGroup>
  ```bash Linux/macOS theme={null}
  export GOOGLE_API_KEY=your-key
  ```

  ```bash Windows PowerShell theme={null}
  $env:GOOGLE_API_KEY="your-key"
  ```

  ```bash Permanent (Linux/macOS) theme={null}
  echo 'export GOOGLE_API_KEY=your-key' >> ~/.bashrc
  source ~/.bashrc
  ```
</CodeGroup>

***

## Next Steps

* [Configuration Guide](/framework/sdk/configuration) - Customize behavior
* [Device Setup](/framework/guides/device-setup) - Detailed setup instructions
* [Agent Architecture](/framework/concepts/architecture) - How it works
* [Custom Tools](/framework/features/custom-tools) - Extend functionality