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

> Prepare, configure, and operate your own iPhones with the mobilerun-ios CLI.

`mobilerun-ios` runs on the host connected to your iPhone. It prepares the device and exposes its controls and screen to Mobilerun cloud, or serves a local HTTP portal.

This reference covers **mobilerun-ios v0.4.0**. Check `mobilerun-ios --version` and the installed command's `--help` if an option is unavailable. Start with [Connect an iPhone](/guides/connect-iphone) for the complete first-device walkthrough.

## Choose a workflow

| Workflow                          | Command                        | Use it when                                                            |
| --------------------------------- | ------------------------------ | ---------------------------------------------------------------------- |
| Prepare one phone                 | `mobilerun-ios setup [udid]`   | First-time setup or repair, with prompts for manual steps and signing. |
| Check readiness                   | `mobilerun-ios verify <udid>`  | Diagnose missing prerequisites without repairing them.                 |
| Connect prepared phones           | `mobilerun-ios [udid...]`      | Serve selected devices, or all devices attached at startup.            |
| Background connection             | `mobilerun-ios -d [udid...]`   | Run a separate background portal per device.                           |
| Discover and prepare continuously | `mobilerun-ios auto`           | Onboard USB phones as they arrive, then serve them.                    |
| Local connection                  | `mobilerun-ios --local <udid>` | Serve the device's HTTP control API without the cloud relay.           |

<CardGroup cols={2}>
  <Card title="Setup and verification" icon="check" href="/mobilerun-ios/setup-and-verify">
    Device preparation, command flags, control modes, and readiness checks.
  </Card>

  <Card title="Configuration" icon="settings" href="/mobilerun-ios/configuration">
    Every config.yaml key, environment overrides, and runtime tuning.
  </Card>

  <Card title="Automatic onboarding" icon="usb" href="/mobilerun-ios/auto">
    USB discovery, concurrency, factory-state onboarding, and recovery.
  </Card>

  <Card title="Automatic WDA signing" icon="key" href="/mobilerun-ios/wda-signing">
    App Store Connect, local Xcode identities, and pre-signed runners.
  </Card>
</CardGroup>

## Connect and operate

```bash theme={null}
mobilerun-ios login
mobilerun-ios whoami
mobilerun-ios list
mobilerun-ios setup <udid>
mobilerun-ios verify <udid>
mobilerun-ios <udid>
```

Replace `<udid>` with the identifier from `list`. `setup` does not log in or start the cloud connection; successful verification is a prerequisite check, not proof that cloud streaming works. Confirm the device appears online in the dashboard and run a task.

### Background portals

```bash theme={null}
mobilerun-ios -d <udid>
mobilerun-ios list
mobilerun-ios stop <udid>
```

Detached portals write PID and log files under `~/.mobilerun-ios/portals/`. `stop` without a UDID stops all detached portals. Foreground sessions, including `auto`, are stopped with **Ctrl+C** or SIGTERM, not with `stop`.

Foreground cloud connections default to a five-attempt retry budget; detached connections retry for up to 30 minutes. Both use exponential backoff. Override with `--retry-attempts`, `--retry-duration`, `--retry-base-delay`, and `--retry-max-delay`. A zero attempt or duration limit disables that limit. Authentication failures are not fixed by retrying; check `whoami`, log in again, or replace the API key.

### Local HTTP portal

```bash theme={null}
mobilerun-ios --local --local-addr 127.0.0.1:8080 <udid>
```

Local mode does not require a Mobilerun cloud token. For multiple devices, the port increments from the base address. To bind beyond loopback, provide a bearer token:

```bash theme={null}
export MOBILERUN_IOS_LOCAL_TOKEN='replace-with-a-long-random-secret'
mobilerun-ios --local --local-addr 0.0.0.0:8080 <udid>
```

Clients send `Authorization: Bearer <token>`. This is a device-control endpoint, not a public website. Keep it on a trusted network; do not expose it directly to the internet.

## WDA and native control

* **iOS versions below 27:** use WebDriverAgent (WDA).
* **iOS 27+:** without a saved choice or installed runner, setup selects native RemoteXPC control. An existing runner keeps WDA as the default.
* **Saved choice:** successful setup saves the mode per device; subsequent setup, verify, and portal sessions reuse it.
* **Explicit WDA:** use `mobilerun-ios setup <udid> --wda`.

Native mode still needs Developer Mode and a compatible developer disk image (DDI). It is not feature-equivalent to WDA: system audio, deep links, the on-device SOCKS proxy, the virtual `/mobilerun` app folder, and factory reset do not have native parity in this release.

For native video, use the separate privileged tunnel process. Run only the tunnel with `sudo`; keep the portal under your normal desktop user so it uses your login and configuration:

```bash Terminal 1 theme={null}
sudo mobilerun-ios tunnel start
```

```bash Terminal 2 theme={null}
mobilerun-ios --remote-xpc-only --tunnel-mode external <udid>
```

The default userspace tunnel supports native input, but should not be treated as equivalent to this external-tunnel video layout. The host RemoteXPC tunnel is separate from the `WebDriverAgentTunnel` app extension used by WDA.

## Other commands

Use `mobilerun-ios --help` for the command inventory and `mobilerun-ios <command> --help` for command-specific syntax. `logout` clears the saved session token; an exported `MOBILERUN_IOS_TOKEN` still overrides the file.

<Warning>
  `mobilerun-ios reset <udid>` is a separate, destructive factory-reset operation. It erases device data, requires reset configuration and explicit confirmation (or `--yes` for non-interactive execution), and must not run alongside a portal or `auto`. It is not a troubleshooting substitute for `setup --reinstall`. Automatic onboarding never authorizes a factory reset.
</Warning>