100% Rust · macOS & Windows · Real iPhone (iOS 27+)

Control a real iPhone from any AI agent.

A single native CLI & MCP binary that reads Apple's accessibility tree and drives any app over USB or Wi-Fi. No Xcode. No WebDriverAgent. No app installed on the phone.

$curl -fsSL https://raw.githubusercontent.com/HyunSeob/iphone-cli/main/install.sh | sh && iph setup
iphone-cli (iph) terminal driving a real iPhone Calculator app directly without Xcode or WebDriverAgent
Live session: terminal driving a stock iPhone via native accessibility tree + CoreDevice HID MIT · Zero phone-side app
Structured UI + Safety Contract

Accessibility tree in. Verified outcomes out.

Every command outputs compact JSON. Selectors target labels, roles, values, and identifiers — and never silently retry an ambiguous touch.

iph read · iph tap exit 0 · done
$ 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
}
Click an outcome to inspect its JSON contract ↓
Engineered for Agents

Built to replace fragile OCR hacks and heavy WDA stacks.

Everything ships inside a single native Rust binary with zero Node.js, Python, Appium, or Xcode dependency.

Embedded QuickJS Scripting (iph script)

Collapse 10 model turns into one call. Write loops, conditions, waitFor, readField, and auto-stitched scrolling readList inside a sandboxed JS engine built right into iph.

launch("com.apple.Preferences", { restart: true });
scroll("down", { until: "General" });
tap("General");
tap("About");
return { ios: readField({ selector: { label: "iOS Version" } }) };

First-Class MCP Server & Agent Skill

Run iph mcp over stdio to expose 19 tools (iph_read, iph_tap, iph_pinch, iph_script, iph_dnd, …) to Claude Code or Codex — or link skills/iph/SKILL.md for shell-native driving.

claude mcp add iph -- iph mcp
codex  mcp add iph -- iph mcp
iph mcp --tools read,find,script

Zero Xcode, Zero WDA

Connects straight to Apple's developer services via idevice. No signing certificates, no 7-day re-signing, and nothing installed on the phone.

macOS, Windows & EU Ready

Never depends on macOS iPhone Mirroring. Runs natively on macOS (universal binary) and Windows 10/11 x64 — anywhere in the world, including the EU.

USB, Wi-Fi & Resident Daemon

iph daemon keeps tunnels, AX subscriptions, and HID sessions warm per UDID — plus iph doctor, direct IP fallback, and iph dnd banner protection.

Tradeoffs & Positioning

How iphone-cli compares to alternatives

Why direct CoreDevice + Accessibility Tree beats screenshot/OCR mirroring and legacy WebDriverAgent setups on iOS 27+.

Capability iphone-cli (iph) iPhone Mirroring + OCR Appium / WebDriverAgent
Native Accessibility Tree ✓ Structured JSON ✗ Screenshots / Vision OCR ✓ Yes
No Xcode / No Code Signing ✓ Zero signing ✓ Yes ✗ Requires Xcode & signing
No App Installed on iPhone ✓ Stock phone ✓ Yes ✗ Installs WDA runner
Windows Host Support ✓ macOS & Windows ✗ macOS Sequoia+ only ✗ Needs macOS to build WDA
Works in the EU ✓ No Mirroring needed ✗ Mirroring unavailable ✓ Yes
Unicode / Clipboard Input ✓ Paste + clipboard restore ✗ Simulated keystrokes ✓ Yes
Embedded Multi-Step Runtime ✓ Built-in QuickJS ✗ External / per-turn ✗ External SDK
Safety Outcome Contract done / not_sent / unknown Varies Standard exceptions
Target Scope Real iPhone, iOS 27+ iOS 18+ (macOS 15+) Broad iOS versions
Under the Hood

Direct Apple developer services over a userspace tunnel.

One resident daemon per UDID multiplexes CLI and MCP requests onto Apple's CoreDevice RSD services without Xcode running.

iph (CLI) Terminal, scripts, batch
iph mcp 19 stdio MCP tools
iph daemon lockdown → CoreDeviceProxy → userspace TCP tunnel (jktcp) → RSD
axAuditDaemon.remoteAXService Structured accessibility tree
displayservice + universalhid Touch, swipe, pinch, keyboard (iOS 27+)
pasteboard · appservice · screencapture Clipboard, app launch/env, PNG capture

Written in 100% Rust on top of idevice (MIT) and jktcp (MIT), built on the documented principles of Poki.

FAQ

Common questions

How can Claude Code or Codex control a real iPhone without Xcode or WebDriverAgent?
Install iph, plug in your iOS 27+ iPhone, run iph setup, and register the MCP server via claude mcp add iph -- iph mcp or codex mcp add iph -- iph mcp. You can also link skills/iph so the agent uses iph directly from the shell.
Why use the accessibility tree instead of screenshots and OCR?
The native accessibility tree returns structured roles, labels, values, enabled states, and frames in compact JSON. Agents use a fraction of the tokens required for repeated screenshots and target controls semantically (iph tap "General", role=button label~="Save") rather than brittle pixel coordinates.
Does iphone-cli work on Windows or in the EU without macOS iPhone Mirroring?
Yes. iph talks directly to the phone's developer services over USB or LAN/Wi-Fi. It runs natively on both macOS and Windows 10/11 (x64) and is completely unaffected by EU iPhone Mirroring restrictions.
Which iOS versions and devices are supported?
Real physical iPhones running iOS 27 or later over USB or the same LAN/Wi-Fi. Touch and keyboard input rely on com.apple.coredevice.displayservice introduced in iOS 27. iOS Simulators, Android devices, Linux hosts, and landscape orientation are currently out of scope.
How does iphone-cli prevent accidental double taps or duplicate orders?
Because iOS never confirms HID touch packets, every command returns outcome (done, not_sent, or unknown) alongside sent, verified, and screen_changed. An unknown outcome exits with code 2 and halts scripts immediately so agents inspect the screen before resending input.