{"id":50252986,"url":"https://github.com/xhzq233/ios-use","last_synced_at":"2026-05-27T03:04:25.231Z","repository":{"id":355251510,"uuid":"1227320488","full_name":"xhzq233/ios-use","owner":"xhzq233","description":"CLI tool to automate iOS devices via custom TCP XCTest driver","archived":false,"fork":false,"pushed_at":"2026-05-20T06:53:44.000Z","size":5279,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T08:48:47.824Z","etag":null,"topics":["cli","ios"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xhzq233.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-02T14:18:40.000Z","updated_at":"2026-05-20T06:49:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xhzq233/ios-use","commit_stats":null,"previous_names":["xhzq233/ios-use"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/xhzq233/ios-use","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xhzq233%2Fios-use","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xhzq233%2Fios-use/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xhzq233%2Fios-use/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xhzq233%2Fios-use/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xhzq233","download_url":"https://codeload.github.com/xhzq233/ios-use/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xhzq233%2Fios-use/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33548247,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","ios"],"created_at":"2026-05-27T03:04:24.242Z","updated_at":"2026-05-27T03:04:25.213Z","avatar_url":"https://github.com/xhzq233.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ios-use\n\n\u003e Fast iOS UI automation from the terminal, powered by a lightweight XCTest TCP driver.\n\n[![Release](https://img.shields.io/github/v/release/xhzq233/ios-use?sort=semver)](https://github.com/xhzq233/ios-use/releases)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20iOS-lightgrey.svg)](#dependency-matrix)\n\n`ios-use` drives real iPhones and Simulators directly from a Swift CLI. It avoids the usual Appium Server -\u003e WebDriverAgent HTTP stack, so agents and scripts can inspect UI state, find labels, tap, swipe, capture logs, and run YAML flows with much lower overhead.\n\n![ios-use demo](docs/media/demo.gif)\n\n## Quick Start\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/xhzq233/ios-use/main/scripts/install.sh | bash -s --\n\nios-use devices\nios-use config --udid \u003cdevice-udid\u003e\nios-use start \u003cdevice-udid\u003e\nios-use activateApp com.apple.Preferences\nios-use dom\n```\n\nAfter `start`, screen-driving commands target the selected device. To switch devices, run `ios-use stop`, then `ios-use start \u003cother-udid\u003e`.\n\n## Why ios-use\n\n- **Built for tight agent loops**: `dom` and `find` are cheap enough to call before actions instead of guessing UI state.\n- **No automation server to run**: no Appium server, no WDA checkout, no iproxy process, no separate WebDriver bridge.\n- **Label-first actions**: tap, input, waitFor, and swipe can target visible UI text before falling back to coordinates.\n- **Real device and Simulator support**: real devices connect through usbmuxd; Simulators connect over `localhost`.\n- **Flows, logs, and proxy capture included**: YAML flows, OSLog, NSLogger, and HTTP/HTTPS proxy capture are first-class CLI workflows.\n\n## What It Is\n\n`ios-use` is a command-line automation tool for macOS users who want direct iOS UI control.\n\nIt is **not** a WebDriver-compatible Appium server. If you need Selenium/Appium protocol compatibility, use Appium. If you want a small CLI that an AI agent or local script can call repeatedly, `ios-use` is optimized for that path.\n\nDriving devices still requires Apple's tooling:\n\n- Real devices require USB and a full Xcode install.\n- Simulators require a full Xcode install and the target Simulator runtime.\n- Real-device first setup requires Apple ID signing. A free Apple Developer account is enough.\n\n## Installation\n\n### Install The CLI\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/xhzq233/ios-use/main/scripts/install.sh | bash -s --\n```\n\nThe installer downloads the prebuilt Apple Silicon macOS CLI and driver IPAs from the latest GitHub Release, then installs `ios-use` into a user-writable bin directory. To install a specific version:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/xhzq233/ios-use/main/scripts/install.sh | bash -s -- --version v1.1.0\n```\n\nIntel Macs should compile locally instead:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/xhzq233/ios-use/main/scripts/install.sh | bash -s -- --build-from-source\n```\n\n### First-Time Setup\n\nChoose the environment you want to drive.\n\n**Real device:**\n\n```bash\nios-use devices\n\n# First run: provide Apple ID credentials if prompted.\nios-use config --udid \u003cdevice-udid\u003e --apple-id \u003cemail\u003e --password '\u003capp-password\u003e'\n\n# Later runs: cached signing state is reused.\nios-use config --udid \u003cdevice-udid\u003e\nios-use start \u003cdevice-udid\u003e\n```\n\n**Simulator:**\n\n```bash\nios-use devices --simulator\nios-use config --simulator --udid \u003csimulator-udid\u003e\nios-use start \u003csimulator-udid\u003e\n```\n\nWhen upgrading `ios-use`, run `ios-use devices` after installation. If a device line says `driver update required`, run `ios-use config --udid \u003cdevice-udid\u003e` again so the on-device driver matches the newly installed CLI.\n\n## Command Overview\n\n| Command | Use it for |\n| --- | --- |\n| `devices` | List real devices or Simulators and see configuration status. |\n| `config` | Install or update the on-device driver. |\n| `start` / `stop` | Select or release the current automation target. |\n| `activateApp` / `terminateApp` | Open or close an app by bundle ID. |\n| `dom` | Print the current UI tree for inspection and planning. |\n| `find` | Locate elements by label/value text and optional traits. |\n| `tap` / `longpress` | Act on a label or coordinate. |\n| `swipe` | Scroll by direction/distance or toward a target label. |\n| `input` | Focus a text field by label and type content. |\n| `screenshot` | Capture a visual fallback when DOM is not enough. |\n| `flow` | Run a YAML automation flow. |\n| `oslog` / `nslog` | Capture system logs or app-side NSLogger output. |\n| `proxy` | Capture HTTP/HTTPS traffic through mitmproxy. |\n| `open` | Open a URL or custom scheme on a device. |\n\nTypical manual loop:\n\n```bash\nios-use activateApp com.apple.Preferences\nios-use dom\nios-use find \"蓝牙\"\nios-use tap \"通用\"\nios-use swipe --to \"开发者\" --from \"蓝牙\"\nios-use input --label \"搜索\" --content \"蓝牙\"\nios-use screenshot --name settings-home\n```\n\nTypical flow:\n\n```bash\nios-use flow flows/test_flow.yaml\n```\n\n## Performance Snapshot\n\nThe benchmark below compares `ios-use` against the full `Appium Server -\u003e WebDriverAgent` stack on the same real-device Settings scenario.\n\n| Case | ios-use Avg | Appium+WDA Avg | Reduction |\n| --- | ---: | ---: | ---: |\n| `dom` | `13.5 ms` | `984.2 ms` | `98.6%` |\n| `find` | `15.7 ms` | `279.8 ms` | `94.4%` |\n| `waitFor` | `13.7 ms` | `277.2 ms` | `95.1%` |\n| `screenshot` | `45.5 ms` | `215.0 ms` | `78.8%` |\n| `tap_label` | `542.8 ms` | `1089.5 ms` | `50.2%` |\n\nThese are the operations that matter most to AI agents: refresh UI state, locate targets, wait for changes, and act. Full benchmark setup and results are in [docs/benchmark.md](docs/benchmark.md).\n\n## Flow Example\n\n```yaml\nname: Settings Search\napp: com.apple.Preferences\nsteps:\n  - action: waitFor\n    label: 蓝牙\n    timeout: 8\n\n  - action: tap\n    label: 蓝牙\n\n  - action: dom\n    outputs: settingsDom\n```\n\nRun it with:\n\n```bash\nios-use flow settings.yaml\n```\n\n## Dependency Matrix\n\n| Dependency | Install CLI | Real Device | Simulator / Dev |\n| --- | --- | --- | --- |\n| `bash`, `curl`, `tar` | required | not needed after install | dev also uses them |\n| `swift` | only for `--build-from-source` | not needed after install | required for SwiftPM development |\n| `xcrun xctrace` | not needed | required for device discovery | not needed |\n| `xcrun devicectl` | not needed | required for install and launch | not needed |\n| `xcrun simctl` | not needed | not needed | required for Simulator config; dev build also uses it |\n| `unzip` | not needed | required during `config` | required during Simulator `config` |\n| `altsign-cli` | copied by installer if bundled | required for real-device signing | not needed |\n| `openssl` | not needed | required for real-device `oslog` TLS relay | not needed |\n| `dns-sd` | not needed | optional for NSLogger Bonjour publish | optional for NSLogger Bonjour publish |\n| `mitmproxy` | not needed | proxy capture only | proxy capture only |\n| `xcodebuild`, `zip`, `mktemp` | not needed | not needed at runtime | required for `scripts/build_driver.sh` |\n| `appium`, `lsof` | not needed | not needed at runtime | benchmark only |\n\n## Repository Layout\n\n```text\nswift-cli/             Swift CLI, command parsing, config, Flow, host tools\nshared/IOSUseProtocol/ Shared Swift RPC types and Fory frame models\ndriver/                Swift XCTest driver\nflows/                 Example flows\nscripts/               Install, build, test, and benchmark utilities\ndocs/                  Public documentation\nassets/                Prebuilt driver artifacts\n```\n\n## Development\n\n```bash\ngit clone https://github.com/xhzq233/ios-use.git\ncd ios-use\nbash scripts/build_swift_cli.sh --debug\n./ios-use --help\nbash scripts/build_driver.sh\nbash scripts/ci_test.sh\n```\n\n`bash scripts/build_swift_cli.sh` builds the local workspace CLI to repo-root `./ios-use`; use that binary for development instead of a global `ios-use`. `scripts/ci_test.sh` is the default CI/local Swift-only validation path. Full Simulator command matrix tests use `bash scripts/ci_full_simulator.sh --driver-ipa \u003cdriver-sim.ipa\u003e`. See `scripts/README.md` for the script index.\n\n## Acknowledgments\n\n- **[WebDriverAgent](https://github.com/appium/WebDriverAgent)**: This project borrows heavily from the ideas and implementation patterns established by WebDriverAgent. Gesture synthesis, snapshot handling, scrolling behavior, and parts of the driver architecture were shaped by studying WDA's source.\n- **[appium-xcuitest-driver](https://github.com/appium/appium-xcuitest-driver)**: The CLI and session behavior were informed by how the Appium XCUITest ecosystem exposes XCTest automation to users.\n- **[Appium](https://github.com/appium/appium)**: Appium helped establish the mental model for cross-device automation workflows, including action-oriented commands and reusable sessions.\n\n## License\n\n[GNU AGPL v3.0](https://www.gnu.org/licenses/agpl-3.0.html) - see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxhzq233%2Fios-use","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxhzq233%2Fios-use","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxhzq233%2Fios-use/lists"}