Free command line tool
Drive the iOS Simulator from the command line
cosmokit brings the simulator actions from the CosmoKit app to your Makefiles, git hooks and CI jobs. Free, open source, and it works whether or not you use the app.
brew install maththedev42/tap/cosmokitRequires macOS 13+ and Xcode's command line tools. Source on GitHub.
Or build from source
git clone https://github.com/maththedev42/cosmokit-cli.git
cd cosmokit-cli
swift build -c releaseRun directly from the checkout (swift run cosmokit or ./.build/release/cosmokit), or set COSMOKIT_DRIVER_DIR to the driver source directory if moving the binary (cp to /usr/local/bin alone no longer works for agent start).
Commands
| cosmokit list | List available simulators |
| cosmokit boot [name|udid] | Boot a simulator |
| cosmokit shutdown [name|udid] | Shut a simulator down |
| cosmokit capture [name|udid] | Screenshot to a file |
| cosmokit record [name|udid] | Record video until Ctrl-C |
| cosmokit location <lat> <lon> | Set the simulator's GPS position |
| cosmokit open <url> | Open a deep link |
| cosmokit erase [name|udid] | Erase a simulator to a fresh install |
Device arguments accept a UDID, an exact name or a partial name. Omit them to use the booted simulator. --output sets the directory for capture and record.
For AI agents
| cosmokit agent start [name|udid] | Start the XCUITest simulator driver |
| cosmokit agent stop [name|udid] | Stop the simulator driver |
| cosmokit agent status [name|udid] | Check driver reachability |
| cosmokit agent stream [name|udid] | Stream simulator to browser for feedback |
| cosmokit ui tree | Print the compact UI tree |
| cosmokit ui wait "<text>" | Wait for UI element to appear or disappear |
| cosmokit ui do <step> [<step>...] | Run a sequence of UI actions |
| cosmokit ui tap <ref|x,y> | Tap an element or coordinate |
| cosmokit ui press <ref> | Long-press an element |
| cosmokit ui swipe <direction> | Swipe up, down, left, or right |
| cosmokit ui type <text> | Type into the active field |
| cosmokit ui button <name> | Press a hardware button |
| cosmokit ui alert <action> | Accept, dismiss, or press an alert button |
| cosmokit ui screenshot | Capture the current UI as PNG |
| cosmokit ui find <text> | Find matching UI elements |
| cosmokit feedback next | Wait for the next human comment |
| cosmokit feedback list | List all feedback comments |
| cosmokit feedback ack <seq> | Mark feedback comment answered |
| cosmokit feedback clear | Clear all feedback comments |
| cosmokit mcp | Run as an MCP server over stdio |
| cosmokit doctor | Check simulator and driver setup |
Agent Skill and MCP
The agent commands above are documented in the full agentic development guide.
Install the Claude Code skill with cp -r skills/cosmokit-simulator ~/.claude/skills/ to give your agent native simulator steering. For Claude Code, Cursor, or any MCP client, add the cosmokit mcp server configuration with claude mcp add cosmokit -- cosmokit mcp or from examples/mcp.json to expose all 56 simulator tools over stdio. Drop examples/cursor-rule.mdc into .cursor/rules/ so Cursor automatically prefers fast UI tree inspection and batched actions when driving tests.
What people use it for
Screenshots in CI
Capture every booted simulator into your repo as part of a build, so a broken layout shows up in the pull request rather than in review.
cosmokit capture --output ./screenshotsDeterministic location tests
Put the simulator somewhere specific before the suite runs, instead of relying on whatever the last manual test left behind.
cosmokit location -22.9068 -43.1729Deep links in a git hook
Exercise a deep link on every commit so a malformed route is caught before it reaches anyone else.
cosmokit open "myapp://item/42"A clean device every run
Erase and boot from a known state so a passing run means the same thing today as it did last week.
cosmokit erase "iPhone 16" && cosmokit boot "iPhone 16"Good to know
- Free and open source under the MIT license
- Universal binary, Apple silicon and Intel
- No account, no telemetry, no CosmoKit Pro required
- Shells out to xcrun simctl, so it works with the Xcode you already have
- Exits non-zero on failure, so it is safe under set -e
- Does not require the CosmoKit app to be installed
The app picks up where the CLI stops
The CLI covers what plain simctl can do. The CosmoKit app adds the network proxy, App Store screenshot generator, device frames, saved push payloads and Dev Presets, with a free tier to start.