by HyunSeob
Let AI agents read and operate any app on a real iPhone through the accessibility tree. No XCUITest, WebDriverAgent or Xcode signing.
# Add to your Claude Code skills
git clone https://github.com/HyunSeob/iphone-cliGuides for using ai agents skills like iphone-cli.
See how iphone-cli compares with popular alternatives.
iphone-cli is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by HyunSeob. Let AI agents read and operate any app on a real iPhone through the accessibility tree. No XCUITest, WebDriverAgent or Xcode signing. It has 54 GitHub stars.
iphone-cli's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.
Clone the repository with "git clone https://github.com/HyunSeob/iphone-cli" and add it to your Claude Code skills directory (see the Installation section above).
iphone-cli is primarily written in Rust. It is open-source under HyunSeob on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh iphone-cli against similar tools.
No comments yet. Be the first to share your thoughts!
Available after the catalog security scan passes.
⚠️ Third-Party Software Notice
This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM is an informational directory and does not control or maintain the underlying repository.
Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.
Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
iph)Let AI agents read and operate any app on a real iPhone — straight from your terminal.
No Xcode. No WebDriverAgent. No app installed on the phone. 100% Rust.
iph script)iph mcp) + safety-first outcomes (done / not_sent / unknown)한국어: README.ko.md

Built on the principle of Poki (a new implementation from its documented behaviour and device experiments, with no Poki code). Device communication relies on idevice (MIT).
$ iph read --human
Settings 430x932 15 elements
application "Settings" @0,0 430x932
header "Settings" @20,119.3 53.7x37
switch "Airplane Mode" = "0" @20,489.3 390x49.3
button "Wi-Fi, HomeNet" @20,538.7 390x49.3
button "General" @20,700 390x49.3
…
$ iph tap "General"
{"ok":true,"outcome":"done","elapsed_ms":1752,"sent":true,"verified":true,"screen_changed":true,…}
| Host | macOS, Windows 10/11 (x64) |
| Device | A real iPhone, iOS 27 or later (verified on one iPhone 15 Pro Max with iOS 27.0.1 only, Korean interface). Touch and text input go through the phone's screen-sharing service (com.apple.coredevice.displayservice, new in iOS 27), so input is not expected to work on iOS 26 or earlier (not tried) |
| Connection | USB or the same LAN (the computer may use Ethernet; verified over USB and Wi-Fi on Windows) |
| Out of scope | Simulators, Android, Linux hosts, landscape |
On Windows, doctor, reading, touch and scripts were checked with one iPhone19,4 on iOS 27.2 over USB.
Neither Rust nor Xcode is needed. On a Mac it is one line in Terminal (it uses only tools macOS ships: curl, tar, shasum).
curl -fsSL https://raw.githubusercontent.com/HyunSeob/iphone-cli/main/install.sh | sh
iph setup # walks through what the phone needs
It downloads the universal binary (Apple silicon and Intel) from the latest release, checks its checksum and puts it at ~/.local/bin/iph. IPH_INSTALL_DIR picks another folder and IPH_VERSION=v0.1.0 a specific version. On Windows, download iph-windows-x86_64.zip from the releases and put iph.exe in a folder on your PATH.
winget install Apple.AppleMobileDeviceSupport. Then plug the phone in and tap Trust.iph doctor installs it. It uses Xcode's copy when the Mac has one, and otherwise fetches one once from the public doronz88/DeveloperDiskImage repository (about 18 MB, pinned commit and SHA-256). The iph repository contains no Apple files.With Rust 1.88 or later, the crate on crates.io installs the same iph (building it takes a few minutes; on Windows it needs Visual Studio Build Tools (C++)):
cargo install iphone-cli # ~/.cargo/bin/iph
Or from a checkout:
git clone https://github.com/HyunSeob/iphone-cli
cd iphone-cli
cargo install --path . # ~/.cargo/bin/iph
iph setup runs iph doctor, says in one line what to do on the phone for each failed check, and checks again. An agent can read checks[].user_action from iph doctor (JSON) and guide the user.
| Check | Required | What it is |
|---|---|---|
pairing |
yes | The Mac holds a pairing record for the phone. If not: connect by USB and tap Trust |
connection |
yes | The phone is visible over USB or the same Wi-Fi |
developer_mode |
yes | Settings → Privacy & Security → Developer Mode. If it is off, iph doctor makes that switch appear |
developer_disk_image |
yes | Source of the accessibility, display and input services. When missing, iph doctor fetches and installs it (see Install) |
screen_unlocked |
yes | The phone is unlocked. Only lockdown's word decides a lock |
settings_in_front |
yes | Settings comes to the front (fails when something covers it). When the screen cannot be read, accessibility_tree fails instead |
accessibility_tree |
yes | Screen elements can really be read |
touch_input |
yes | Scrolls the Settings list down one step and back to see that touch lands (--no-touch-test skips it) |
wifi |
recommended | Wireless lockdown flags and the phone's usbmuxd Network entry (see below) |
auto_lock |
recommended | Auto-Lock → Never for long sessions |
do_not_disturb |
info | Shown only while Do Not Disturb from iph dnd on is still on |
Setup requirements and how to interpret the checks are in docs/onboarding.md (Korean).
Pair by USB first, then keep the iPhone unlocked on the same LAN. The computer may use Ethernet. To enable wireless connections, run this while USB is attached:
iph doctor --fix-wifi
If the phone is still not discovered, register its IP below. Wireless setup details (Korean).
Notification banners take taps near the top of the screen. Banners cover the top of the screen and are not part of the accessibility tree. A tap near the top then lands on the banner and opens another app (this happened once during development). For long unattended work turn Do Not Disturb on with iph dnd on, and put it back with iph dnd off afterwards. Details: Do Not Disturb below.
For a USB-trusted phone missing from discovery, use the IP shown in Settings → Wi-Fi → the network's info button:
iph devices # while USB is attached: note the UDID
iph --udid <UDID> connect --ip <iPhone-IP> # after unplugging USB
iph --udid <UDID> read
The Apple device service is still required. CLI, MCP and scripts share the saved address for the selected UDID; register it again if the IP changes. Connection details (Korean).
Every command prints JSON; add --human for people. The device is chosen by --udid, then IPH_UDID, then udid in ~/.config/iph/config.toml, then the only connected phone. With several phones and none chosen, you get an error with the list.
| Command | Does |
|---|---|
iph connect --ip <IP> |
Verify and save the selected paired phone's IP |
iph devices |
Connected phones, iOS version, connection, readiness |
iph setup / iph doctor |
Preparation and checks |
iph read [--app] [--all] [--full] [--raw] [--max-age ms] |
Elements on screen. --all includes off-screen ones, --full adds identifiers (about 0.5 s more), --raw attaches every numbered attribute |
iph find <selector> |
Elements matching a selector |
iph tap <selector | x,y> [--long ms] [--double] |
Tap the middle of an element, or a point |
iph swipe <up|down|left|right | x1,y1,x2,y2> [--duration ms] [--drag] |
Swipe. --drag slows to a stop before lifting, so nothing coasts |
iph scroll <up|down> [--until selector] [--max N] |
One step, or until an element shows |
iph type <text> [--clear] [--submit] |
Paste text into the field that has the keyboard (any language, emoji). The clipboard is put back and the field's value checked |
iph key <key> |
return, esc, tab, cmd+a … |
iph button <home|lock|volume_up|volume_down> |
Hardware buttons |
iph launch <bundle id | name> [--restart] / iph apps |
Launch an app, list apps |
iph screenshot [-o file] |
PNG capture |
iph batch <file | -> |
A JSON array of steps in one call |
iph script <file | -> [--arg k=v] |
Run JavaScript as given (- reads stdin) |
iph run <name> [--arg k=v] / iph scripts |
Run a saved script, list saved scripts |
iph mcp [--tools a,b] |
MCP server on stdio |
iph dnd <on|off|status> |
Turn Do Not Disturb on, put the earlier Focus back, or show the current state |
iph stop |
Stop the resident process for this phone |
iph tap "General"label="exact", label~="contains", label/regex/role=button (application, button, switch, text_field, search_field, key, tab, header, text, image, link, adjustable, other)id=… matches the accessibility identifier or the element id from iph read; id~= and id/regex/ work toovalue="…", value~=…within="<selector>" only inside that element, index=N the Nth match (from 0)ambiguous_selector error with the candidates; nothing is picked for youRows labelled "name, value" (as in Settings: "Wi-Fi, HomeNet") also match label="Wi-Fi".
Scripts, MCP and batch also take an object: {label, label_contains, label_regex, value, value_contains, value_regex, role, id, id_contains, id_regex, within, index}.
{"ok": true, "outcome": "done", "elapsed_ms": 1752, "sent": true, "verified": true, "screen_changed": true, "element": {…}}
{"ok": false, "outcome": "not_sent", "error": {"code": "not_found", "message": "…", "hint": "…"}, "elapsed_ms": 1210, "screen_summary": {…}}
outcome |
Meaning | Exit code |
|---|---|---|
done |
Ran to the end. W |