Install iPhone-use

Install the CLI and its matching precompiled Runner on your Mac.

Requirements

Both modes require an Apple Silicon Mac, full Xcode, a USB-connected trusted iPhone with Developer Mode enabled and an unlocked screen. Standard mode currently requires macOS 27 / iOS 27 and uses Apple PNG screenshots with native HID, without Runner setup or development signing. Only Runner mode additionally requires an Apple Development certificate, private key and matching profile. The binary deployment floor of macOS 15 is not a standard-mode compatibility promise.

Homebrew

brew install HughLee824/tap/iphone-use
command -v iphone-use
iphone-use --version

Homebrew installs the complete package. It does not compile source, run device setup or connect to your iPhone. Restart a client that was running before installation so it inherits the updated PATH.

If Homebrew reports that the agentsoma conflict formula is untrusted, review this project’s legacy formula and, if you trust it, run brew trust --formula HughLee824/tap/agentsoma, then retry the installation. This grants persistent trust only to that formula; trusting the entire Tap is unnecessary. The old formula need not be installed.

Manual download

Check the version on GitHub Releases, then use a new empty directory. The example uses release 0.2.1; replace it with the published version you intend to install. GitHub’s automatic source archives are not the precompiled package.

IPHONE_USE_VERSION=0.2.1
IPHONE_USE_PACKAGE="iphone-use-${IPHONE_USE_VERSION}-macos-arm64"
IPHONE_USE_RELEASE_URL="https://github.com/HughLee824/iphone-use/releases/download/v${IPHONE_USE_VERSION}"
(
  set -e
  curl --fail --location --show-error --output "${IPHONE_USE_PACKAGE}.tar.gz" \
    "${IPHONE_USE_RELEASE_URL}/${IPHONE_USE_PACKAGE}.tar.gz"
  curl --fail --location --show-error --output "${IPHONE_USE_PACKAGE}.tar.gz.sha256" \
    "${IPHONE_USE_RELEASE_URL}/${IPHONE_USE_PACKAGE}.tar.gz.sha256"
  shasum -a 256 -c "${IPHONE_USE_PACKAGE}.tar.gz.sha256"
  tar -xzf "${IPHONE_USE_PACKAGE}.tar.gz"
)

Continue only after the checksum reports OK and extraction succeeds. If verification fails, download again without running package contents. Keep the entire package: bin and libexec must remain in their relative locations.

IPHONE_USE_DEST="$HOME/.local/share/iphone-use/releases/$IPHONE_USE_VERSION"
(
  set -e
  test ! -e "$IPHONE_USE_DEST"
  mkdir -p "$HOME/.local/share/iphone-use/releases" "$HOME/.local/bin"
  mv "$IPHONE_USE_PACKAGE" "$IPHONE_USE_DEST"
  ln -sfn "$IPHONE_USE_DEST/bin/iphone-use" "$HOME/.local/bin/iphone-use"
)
export PATH="$HOME/.local/bin:$PATH"
iphone-use --version

Add the PATH line to your shell configuration (usually ~/.zshrc for zsh). Use command -v iphone-use when switching between Homebrew and a manual install. The destination version directory must not already exist.

macOS signing status

The CLI is ad-hoc signed, without Developer ID signing or notarization. Release 0.2.1 has host/package verification; see its Release notes for the exact evidence and prior-candidate device results. Browser and fresh-Mac first-run installation remain unverified. Do not remove quarantine metadata or disable system protection to bypass a refusal.

When migrating from the old agentsoma formula, disconnect, uninstall it, then install iphone-use: both provide the compatibility command. Preferences use ~/.iphone-use/config.json. Renamed Runner apps require setup again; standard mode does not.

Upgrade and remove

Disconnect active sessions before upgrading.

brew update
brew upgrade iphone-use
iphone-use --version

For manual installations, verify the new package, place it in a new version directory and switch the symlink. Keep the old directory for rollback; do not mix package files. Update the client plugin separately.

brew uninstall iphone-use removes the Homebrew package. Manual users remove their own symlink and version directory. Both leave local device preparation and the iPhone Runner in place. For complete removal, also remove ~/Library/Application Support/iphone-use and uninstall iPhone-use Runner on the phone. Keychain certificates and Xcode signing material are separate.