How to Use xcrun simctl in macOS Terminal to Control iOS Simulators and Automated Workflows

Testing iOS, watchOS, and tvOS applications typically involves launching Xcode and interacting with graphical simulator windows. However, for continuous integration (CI) runners, automated testing pipelines, and command-line development workflows, GUI navigation introduces unnecessary delays. Built directly into the macOS Xcode command-line developer tools, xcrun simctl exposes granular terminal commands to boot devices, install applications, capture screenshots and video, inject push notifications, and override device sensor parameters without ever touching the Xcode interface.

Prerequisites and Verifying Installation

The simctl sub-utility is bundled with Xcode Command Line Tools. Verify that your system path resolves Xcode’s developer directory:

# Check active developer directory
xcode-select -p

# If unconfigured, set the developer directory to Xcode.app
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

# Verify simctl availability
xcrun simctl help

Listing Available Runtimes, Device Types, and Devices

Before launching a simulated environment, query available hardware and OS configurations:

# List all devices and their current state (Booted / Shutdown)
xcrun simctl list devices

# Filter list to only show available (installed) devices
xcrun simctl list devices available

# Output simulator metadata in structured JSON for automation scripts
xcrun simctl list --json

Booting, Shutting Down, and Opening Simulators

Simulators operate headlessly by default, executing applications in the background without drawing a desktop window:

Task	Terminal Command	Description
Boot a Device	xcrun simctl boot <device-UUID-or-Name>	Boots the target simulator headlessly in the background.
Open Simulator GUI	open -a Simulator	Connects the macOS Simulator desktop window to the active booted instance.
Shut Down a Device	xcrun simctl shutdown <device-UUID>	Gracefully terminates simulator processes and clears runtime memory.
Shut Down All	xcrun simctl shutdown all	Terminates all running simulator instances concurrently.
Erase a Device	xcrun simctl erase <device-UUID>	Factory resets the simulator, wiping all caches, app data, and settings.

Installing, Launching, and Terminating Applications

Deploy compiled .app bundles directly to a running simulator using the following commands:

# Install an application bundle
xcrun simctl install booted /path/to/YourApp.app

# Launch the installed app using its bundle identifier
xcrun simctl launch booted com.example.YourApp

# Launch with environment variables and launch arguments
xcrun simctl launch --console-pty booted com.example.YourApp -FIRAnalyticsDebugEnabled YES

# Terminate a running app process
xcrun simctl terminate booted com.example.YourApp

# Uninstall an app bundle completely
xcrun simctl uninstall booted com.example.YourApp

Capturing Screenshots and Video Recordings

Generate high-resolution device assets directly from Terminal:

# Capture an uncompressed PNG screenshot
xcrun simctl io booted screenshot ~/Desktop/simulator_screen.png

# Record device video (press Ctrl+C to conclude capture)
xcrun simctl io booted recordVideo --codec=h264 ~/Desktop/demo_walkthrough.mp4

Injecting Simulated Push Notifications and Overriding Status Bars

Testing remote notifications and preparing App Store marketing screenshots is straightforward with simctl:

1. Testing Push Notifications via APNS JSON Payload

# Send an APNS payload file directly to the app
xcrun simctl push booted com.example.YourApp notification_payload.json

2. Overriding the Status Bar for Clean Marketing Captures

To standardize clock time, battery level, and signal bars across all marketing captures:

xcrun simctl status_bar booted override \
  --time "9:41" \
  --batteryState charged \
  --batteryLevel 100 \
  --cellularBars 4 \
  --wifiBars 3

# Clear status bar overrides when finished
xcrun simctl status_bar booted clear