iPhone-use
浏览文档

CLI 0.2.1

本页目录

安装 iPhone-use

在 Mac 上安装 CLI 与配套的预编译 Runner。

前置条件

两种模式都需要 Apple Silicon Mac、完整 Xcode，以及通过 USB 信任 Mac、开启开发者模式并保持解锁的 iPhone。标准模式当前要求 macOS 27 / iOS 27，采用 Apple PNG 截图与原生 HID，无需 Runner setup 或开发签名。仅 Runner 模式额外需要 Apple Development 证书、私钥与匹配的描述文件。二进制 macOS 15 编译下限不代表标准模式支持旧系统。

Homebrew 安装

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

Homebrew 安装完整发布包，不编译源码、不执行 setup，也不连接 iPhone。安装前已经运行的客户端需要重启，以取得更新后的 PATH。

如果 Homebrew 报告冲突检查中的旧 agentsoma formula 未受信任，请先查看该项目的旧公式；确认信任后执行 brew trust --formula HughLee824/tap/agentsoma，再重试安装。这会持久信任该单个公式，无需信任整个 Tap，也无需安装旧公式。

手动下载安装

先在 GitHub Releases 确认版本，再在新的空目录中执行命令。示例使用 0.2.1，请替换为你要安装的已发布版本。GitHub 自动生成的源码压缩包不是预编译安装包。

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"
)

仅在校验显示 OK 且解压成功后继续。校验失败时重新下载，不运行包中的文件。必须保留完整目录，以及 bin 与 libexec 的相对位置。

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

将 PATH 设置加入 shell 配置，zsh 通常使用 ~/.zshrc。在 Homebrew 与手动安装之间切换时，用 command -v iphone-use 核对实际入口。目标版本目录必须尚不存在。

macOS 签名状态

CLI 使用 ad-hoc 签名，未做 Developer ID 签名或公证。0.2.1 已完成宿主与安装包核验；精确范围与此前候选包真机结果见 Release 说明。浏览器及全新 Mac 首次安装仍未验收，不应通过删除隔离标记或关闭系统保护绕过拒绝。

从旧 agentsoma formula 迁移时，先断开会话、卸载旧 formula，再安装 iphone-use，避免兼容命令冲突。模式偏好保存在 ~/.iphone-use/config.json。更名后的 Runner 需重新 setup，标准模式不需要。

升级与卸载

升级前先断开活跃会话。

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

手动安装用户需要校验新包、安装到新的版本目录，再切换软链接。保留旧目录可供回退，不要混合新旧包文件。客户端插件需要单独更新。

brew uninstall iphone-use 卸载 Homebrew 包；手动用户删除自己创建的软链接和版本目录。两种方式均保留本机设备准备状态和手机 Runner。完全移除时，再删除 ~/Library/Application Support/iphone-use 并在手机上卸载 iPhone-use Runner。Keychain 证书和 Xcode 签名资料独立保留。