pymobiledevice3-device-operator

name

pymobiledevice3-device-operator

description

Operate iOS and iPadOS devices with pymobiledevice3, from a local checkout or straight from PyPI via uvx on a fresh workstation. Use when an agent needs to inspect a connected device, collect logs or crash data, browse or copy files, manage apps, profiles, or backups, use developer services such as DDI/DVT/tunnels/sysmon/screenshots/simulated location, automate Safari or WebViews through WebInspector or WDA, write Python scripts against the pymobiledevice3 library, or add a thin repo-native device command on top of existing services. Prefer existing CLI and service modules, choose USB vs --rsd/--tunnel correctly, and require explicit user intent before state-changing or destructive actions.

PyMobileDevice3 Device Operator

Overview

Use this skill to translate a user goal into the smallest correct pymobiledevice3 action, then execute it — from a local checkout when one is present, or via the PyPI release (uvx pymobiledevice3) on a fresh workstation — or extend the repo with a thin CLI wrapper when the capability already exists in services.

Default Operating Pattern

Inside a pymobiledevice3 checkout, run commands from the repository root with uvx --from . pymobiledevice3 ... so the local checkout is used. On a workstation without a checkout, run uvx pymobiledevice3 ... instead — uvx fetches the released package from PyPI on first use, so nothing needs to be installed beforehand except uv itself (uv tool install pymobiledevice3 gives a persistent install). Everywhere this skill's references show uvx --from . pymobiledevice3 ..., drop the --from . when there is no checkout. Fall back to python3 -m pymobiledevice3 ... only if uvx is unavailable or the user explicitly wants the current interpreter environment.

If uv itself is missing, bootstrap one of the two paths first (neither needs root):

• Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows), then use uvx as above.
• Or skip uv entirely: python3 -m pip install -U pymobiledevice3, then run python3 -m pymobiledevice3 ... everywhere the references show uvx ... pymobiledevice3 .... If pip refuses with externally-managed-environment (PEP 668 — Debian/Ubuntu, Homebrew Python, Fedora), create a venv instead of forcing it: python3 -m venv ~/.pmd3-venv && ~/.pmd3-venv/bin/pip install -U pymobiledevice3, then use ~/.pmd3-venv/bin/pymobiledevice3 .... Never use --break-system-packages.

Start with the least invasive command that proves connectivity or surfaces missing prerequisites:

uvx --from . pymobiledevice3 usbmux list
uvx --from . pymobiledevice3 lockdown info

Prefer existing CLI commands first. Prefer reading local docs and CLI source over invoking --help. Only write code when the library already exposes the underlying service but lacks the exact CLI/API path needed.

Workflow

1. Classify the request as one of: inspect, collect, modify, automate, developer-instrument, or extend-the-repo.
2. Confirm transport before doing anything expensive. USB is the default. For iOS 17+ developer services, read references/transport-and-safety.md.
3. Discover the narrowest command by checking docs/guides/cli-recipes.md, pymobiledevice3/__main__.py, and the relevant CLI module under pymobiledevice3/cli/. Use rg to locate command names, options, and transport flags quickly. Without a checkout, use --help discovery and the published docs (https://doronz88.github.io/pymobiledevice3/) instead.
4. Use uvx --from . pymobiledevice3 <group> --help only as a fallback when code and docs are ambiguous, or as a final verification step before suggesting an exact command to the user.
5. Execute a reversible or read-only step first, then escalate to state-changing actions only if the user asked for them.
6. For long-lived streams or interactive shells, keep the process attached instead of replacing it with one-shot polling.
7. If the CLI is missing a path that clearly exists in services, add a thin command using ServiceProviderDep, @async_command, and a service class under pymobiledevice3/services/ — commands live on an InjectingTyper app (from typer_injector). Read docs/guides/writing-commands-with-service-provider.md.

Parsing Command Output

Prefer machine-readable output over scraping human text — the contract is documented in docs/guides/machine-readable-output.md (published on the docs site):

• Data goes to stdout; logging and diagnostics go to stderr. Parse stdout only.
• Most query commands print JSON unconditionally. Binary values appear as single-key {"$hex": "..."} objects (decode with bytes.fromhex); timestamps are ISO 8601.
• Streaming commands emit NDJSON (one JSON object per line): dict-record streams (dvt energy/notifications/graphics, diagnostics battery monitor, notification observe/observe-all) always; human-rendered streams (syslog live, dvt oslog, dvt netstat, accessibility notifications, crash watch) with --format json.

Safety Rules

Require explicit user intent before any command that changes device state, including:

• restore, erase, recovery, reboot, restart, unpair, pair-supervised
• app install or uninstall
• file push, rm, or app container mutation
• profile or provisioning changes
• developer mode toggles, mounting, simulated location, signals, kill/pkill, or automation that taps/types/swipes

Do not invent prerequisites. If a developer service fails, inspect developer-mode, DDI, and tunnel requirements before changing code.

Do not expose or commit pair records, crash artifacts, backups, or other device-identifying material.

Task Routing

Read references/quick-recipes.md for the exact invocation of the most common tasks (screenshot, syslog search, crash pull, file copy, app listing) and for the syslog-first troubleshooting technique.

Read references/python-scripting.md before writing Python code against the library — the API went async incrementally over many releases, so memorized/older API shapes are usually stale.

Read references/task-map.md when you need to map a user goal to a command group or service module.

Read references/transport-and-safety.md when the task touches iOS 17+ developer services, tunnels, --rsd, --tunnel, or destructive operations.

Source Files To Prefer

These paths are relative to a pymobiledevice3 checkout; without one, use the published docs site (https://doronz88.github.io/pymobiledevice3/) and --help output instead.

• docs/guides/cli-recipes.md for common end-user commands
• docs/guides/ios17-tunnels.md for tunnel setup and --rsd usage
• docs/guides/writing-commands-with-service-provider.md for repo-native command additions
• pymobiledevice3/__main__.py for top-level CLI groups
• pymobiledevice3/cli/cli_common.py for transport resolution and dependency injection

Typical Triggers

• "Pull crash logs from the connected iPhone."
• "List installed apps and copy an app container file."
• "Take a screenshot with developer services."
• "Start a tunnel and run DVT sysmon on an iOS 17 device."
• "Open Safari automation and inspect tabs."
• "Add a new CLI command for an existing service."