Phone Use CLI

---
name: phoneuse
description: See and operate the user's iPhone from this PC (Linux or Windows) with the `phoneuse` CLI (AirPlay mirror for the screen, Bluetooth mouse/keyboard for input). Use when a task needs the iPhone: open or use an app, read what is on the phone screen, tap, type, swipe, check a notification, change a phone setting, or test something on the device. Also use when the mirror or the Bluetooth link needs starting or fixing.
---

# Operating the iPhone with Phone Use

The `phoneuse` command drives a real, unmodified iPhone. Its screen arrives over
AirPlay as a mirror window on this PC and as a live page at
http://localhost:8777, and input goes in as a Bluetooth mouse and keyboard.
Everything an agent does is a `phoneuse` subcommand; run `phoneuse --help` for
the full list.

## Before acting

1. Run `phoneuse status`. You need `iPhone app: 1 paired` (or more), `HID service:
   active`, `connected=True`, and `Mirror window: ... showing the phone` (Windows:
   `Mirror: showing the phone`). "not paired": stop and ask the user to pair the Phone
   Use app (Pair iPhone in the Phone Use window); every action is refused until they
   do. If something is off and you don't see why, `phoneuse doctor` checks the whole
   setup and prints the fix for each problem.
2. No mirror window: check whether `phoneuse up` is running. If it isn't, start it
   somewhere the user can see it (a terminal or tmux window they use), not hidden in
   the background. "not mirroring" (or no window): ask the user to start Screen
   Mirroring to this PC's receiver ("Phone Use on <computer>"; `phoneuse status`
   names it) from the iPhone's Control Center. You can't start
   mirroring from the PC, and every input command refuses until it runs.
3. **Show the user the phone** before your first action, so they can watch what
   you do: open http://localhost:8777 (`phoneuse view --print` prints the address).
   If you have a browser of your own, such as a built-in browser pane, open it
   there. Otherwise run `phoneuse view`, which opens it in the user's default
   browser. Do this once per task; if the page is already open, leave it. The page
   is for the user to watch: act through `phoneuse` commands, never by clicking in
   the page.
4. `connected=False`: run `phoneuse status` again after a few seconds (the daemon
   reconnects), then ask the user to tap "Phone Use" in the iPhone's Bluetooth settings
   (Windows: the PC's name, which `phoneuse status` shows as `name=`).
5. HID service not active: on Linux `phoneuse install` (needs sudo) sets it up; on
   Windows `phoneuse up` starts it (it keeps running after `up` stops).