GitHub - riwsky/iosef: a CLI and MCP server for iOS Simulator automation, designed for agents

iosef start --local --device "X"   →  creates/boots simulator, saves state to .iosef/state.json
iosef tap / type / view            →  reads state.json, performs action, exits
iosef mcp                          →  long-running MCP server (stdio), same capabilities
iosef stop                         →  shuts down simulator, deletes device, cleans up state

uv tool install iosef
# or
pip install iosef

swift build -c release
# or
./scripts/build.sh   # builds + installs to ~/.local/bin/iosef

iosef start --local --device "my-sim"     # Create + boot simulator, local session
iosef start --device "iPhone 16 Pro" --device-type "iPhone 16 Pro" --runtime "iOS 18.4"
iosef connect "iPhone 16" --local         # Associate with an existing simulator
iosef status                              # Show simulator name, UDID, state, session info
iosef status --json                       # Machine-readable output
iosef stop                                # Shut down, delete device, remove session

iosef describe                            # Dump the full accessibility tree
iosef describe --depth 2                  # Limit tree depth
iosef describe --json | jq '.. | objects | select(.role == "button")'

iosef describe --x 200 --y 400           # What's at this coordinate?
iosef describe --x 200 --y 400 --json | jq '.content[0].text'

iosef view                                # Screenshot to temp file (prints path)
iosef view --output /tmp/screen.png       # Screenshot to specific file
iosef view --output /tmp/screen.jpg --type jpeg

iosef tap --name "Sign In"                    # Find element + tap (preferred)
iosef tap --role AXButton --name "Submit"
iosef tap --name "Menu" --duration 0.5        # Long-press by selector

iosef tap --x 200 --y 400                    # Tap at coordinates
iosef tap --x 100 --y 300 --duration 0.5     # Long-press at coordinates

iosef type --text "Hello World"               # Type into the focused field
iosef type --name "Search" --text "query"     # Find + tap + type in one step
iosef type --role AXTextField --text "hello"

iosef swipe --x-start 200 --y-start 600 --x-end 200 --y-end 200
iosef swipe --x-start 200 --y-start 600 --x-end 200 --y-end 200 --duration 0.3

iosef find --role AXButton                    # All buttons
iosef find --name "Sign In"                   # Elements matching label (substring, case-insensitive)
iosef find --role AXStaticText --name "count"  # Combine selectors

iosef exists --name "Sign In"                 # Prints "true"/"false", exit 0/1
iosef count --role AXButton                   # How many buttons?
iosef text --name "Tap count"                 # Extract text content from first match

iosef wait --name "Welcome"                   # Poll until element appears (default 10s)
iosef wait --role AXButton --name "Continue" --timeout 5

iosef install_app --app-path /path/to/MyApp.app   # Install .app or .ipa bundle
iosef launch_app --bundle-id com.apple.mobilesafari
iosef launch_app --bundle-id com.example.myapp --terminate-running

iosef log_show --process SpringBoard --last 5s
iosef log_show --predicate 'subsystem == "com.apple.UIKit"' --last 3s
iosef log_show --level debug --last 1m

iosef log_stream --process SpringBoard --duration 3
iosef log_stream --predicate 'process == "MyApp"' --duration 10

iosef mcp    # Start MCP server on stdio

{
  "mcpServers": {
    "iosef": {
      "command": "iosef",
      "args": ["mcp"]
    }
  }
}

iosef start --local --device "my-sim"   # State stored in ./.iosef/state.json
iosef tap --name "Sign In"              # Auto-detects local session
iosef stop                              # Cleans up local session

# Force global even when a local session exists
iosef --global tap --x 200 --y 400

# Force local
iosef --local status

#!/bin/bash
set -euo pipefail

FAIL=0

check() {
    if ! "$@"; then
        echo "FAIL: $*"
        FAIL=1
    fi
}

# Boot and launch
iosef start --local --device "test-sim"
iosef install_app --app-path ./build/MyApp.app
iosef launch_app --bundle-id com.example.myapp

# Wait for the app to load
iosef wait --name "Welcome" --timeout 15

# Log in
iosef type --name "Email" --text "user@example.com"
iosef type --name "Password" --text "hunter2"
iosef tap --name "Sign In"

# Verify we landed on the dashboard
iosef wait --name "Dashboard" --timeout 10
check iosef exists --name "Dashboard"
check iosef exists --role AXButton --name "Settings"

# Take a screenshot for the record
iosef view --output /tmp/dashboard.png

iosef stop

if [ "$FAIL" -ne 0 ]; then
    echo "Some checks failed"
    exit 1
fi
echo "All checks passed"