iOS Simulator CLI

A command-line tool for interacting with iOS simulators. Control UI, capture screenshots and video, install apps, and inspect accessibility elements from your terminal or automation scripts.

Security Notice: Command injection vulnerabilities present in versions < 1.3.3 have been fixed. Please update to v1.3.3 or later. See SECURITY.md for details.

Installation

Homebrew (recommended)

The formula lives in this repo, so tap it explicitly (Homebrew otherwise looks for a separate homebrew-ios-simulator-cli repo that does not exist):

brew tap DebugSwift/ios-simulator-cli https://github.com/DebugSwift/ios-simulator-cli
brew install ios-simulator-cli

To install the latest from main:

brew install --HEAD ios-simulator-cli

npm

npm install -g ios-simulator-cli

From source

git clone https://github.com/DebugSwift/ios-simulator-cli
cd ios-simulator-cli
npm install
npm run build
npm link

Prerequisites

• macOS (iOS simulators are only available on macOS)
• Xcode and iOS simulators installed
• Facebook IDB tool (install guide)

Usage

ios-simulator-cli --help
ios-simulator-cli --version

Commands

| Command | Description | | --- | --- | | get-booted-sim-id | Get the booted simulator UUID | | open | Open Simulator.app | | ui describe-all | Describe all UI accessibility elements | | ui tap | Tap at coordinates | | ui type | Input text | | ui swipe | Swipe gesture | | ui describe-point | Get element at coordinates | | ui find-element | Search accessibility tree | | ui view | Capture compressed screenshot (JPEG base64 or file) | | screenshot | Save screenshot to file | | record-video | Start video recording | | stop-recording | Stop video recording | | install-app | Install an app bundle (.app or .ipa) | | launch-app | Launch an app by bundle identifier |

Examples

# Get the booted simulator
ios-simulator-cli get-booted-sim-id

# Open Simulator.app
ios-simulator-cli open

# Describe the current screen
ios-simulator-cli ui describe-all

# Tap at coordinates
ios-simulator-cli ui tap --x 200 --y 400

# Type text
ios-simulator-cli ui type "Hello World"

# Swipe down
ios-simulator-cli ui swipe --x-start 200 --y-start 600 --x-end 200 --y-end 200

# Find a button by label
ios-simulator-cli ui find-element --search "Search" --type Button

# Save a screenshot
ios-simulator-cli screenshot --output home.png

# Capture a compressed view to a file
ios-simulator-cli ui view --output screen.jpg

# Start and stop recording
ios-simulator-cli record-video --output demo.mp4
ios-simulator-cli stop-recording

# Install and launch an app
ios-simulator-cli install-app --app-path ./MyApp.app
ios-simulator-cli launch-app --bundle-id com.apple.mobilesafari --terminate-running
ios-simulator-cli launch-app --bundle-id com.example.app --env FOO=bar --env BAZ=qux

Configuration

Environment Variables

| Variable | Description | Example | | --- | --- | --- | | IOS_SIMULATOR_CLI_DEFAULT_OUTPUT_DIR | Default directory for relative output paths (screenshots, recordings). Defaults to ~/Downloads. | ~/Code/project/tmp | | IOS_SIMULATOR_CLI_IDB_PATH | Custom path to the IDB executable. Defaults to idb on PATH. | ~/bin/idb |

Legacy IOS_SIMULATOR_MCP_* environment variables are still supported for output directory and IDB path.

License

MIT