Axe – CLI tool for interacting with iOS Simulators

10 hours ago 1

AXe is a comprehensive CLI tool for interacting with iOS Simulators using Apple's Accessibility APIs and HID (Human Interface Device) functionality.

Features
Quick Start
- Installation
  - Install via Homebrew
  - Build from source
- Basic Usage
Commands Overview
Architecture
- Why AXe?
Gesture Presets Reference
Contributing
Licence

AXe provides complete iOS Simulator automation capabilities:

Tap: Precise touch events at specific coordinates with timing controls
Swipe: Multi-touch gestures with configurable duration and delta
Touch Control: Low-level touch down/up events for advanced gesture control
Gesture Presets: Common gesture patterns (scroll-up, scroll-down, scroll-left, scroll-right, edge swipes)

Text Input: Comprehensive text typing with automatic shift key handling
Key Presses: Individual key presses by HID keycode
Key Sequences: Multi-key sequences with timing control
Multiple Input Methods: Direct text, stdin, or file input

Home Button: iOS home button simulation
Lock/Power Button: Power button with duration control
Side Button: iPhone X+ side button
Siri Button: Siri activation button
Apple Pay Button: Apple Pay button simulation

Pre/Post Delays: Configurable delays before and after actions
Duration Control: Precise timing for gestures and button presses
Sequence Timing: Custom delays between key sequences
Complex Automation: Multi-step workflows with precise timing

Screenshot-based Streaming: Capture simulator video at 1-30 FPS
Multiple Output Formats: MJPEG, raw JPEG, ffmpeg-compatible, BGRA
H.264 Recording: Use the record-video command to write MP4 files with hardware-friendly encoding
Configurable Quality: Adjust JPEG quality and scale factor
Real-time Performance: Efficient frame timing for smooth playback

UI Description: Extract accessibility information from any point or full screen
Simulator Management: List available simulators

# Install via Homebrew brew tap cameroncooke/axe brew install axe # Or single liner brew install cameroncooke/axe/axe # Use directly axe --help

Note

You may see errors when using brew install, like Failed to fix install linkage; these can be safely ignored. This is because the binaries are already codesigned and Homebrew is attempting to resign them, which is not necessary.

For development work:

# Clone the repository git clone https://github.com/cameroncooke/AXe.git cd AXe # Run directly with Swift (frameworks handled automatically) swift run axe --help swift run axe list-simulators # Build for development swift build .build/debug/axe --help

# List available simulators axe list-simulators # Get simulator UDID UDID="B34FF305-5EA8-412B-943F-1D0371CA17FF" # Basic interactions axe tap -x 100 -y 200 --udid $UDID axe type 'Hello World!' --udid $UDID axe swipe --start-x 100 --start-y 300 --end-x 300 --end-y 100 --udid $UDID axe button home --udid $UDID # Gesture presets axe gesture scroll-up --udid $UDID axe gesture swipe-from-left-edge --udid $UDID # With timing controls (NEW!) axe tap -x 100 -y 200 --pre-delay 1.0 --post-delay 0.5 --udid $UDID axe gesture scroll-down --pre-delay 0.5 --post-delay 1.0 --udid $UDID

# Tap at coordinates axe tap -x 100 -y 200 --udid SIMULATOR_UDID axe tap -x 100 -y 200 --pre-delay 1.0 --post-delay 0.5 --udid SIMULATOR_UDID # Swipe gestures axe swipe --start-x 100 --start-y 300 --end-x 300 --end-y 100 --udid SIMULATOR_UDID axe swipe --start-x 50 --start-y 500 --end-x 350 --end-y 500 --duration 2.0 --delta 25 --udid SIMULATOR_UDID # Advanced touch control axe touch -x 150 -y 250 --down --udid SIMULATOR_UDID axe touch -x 150 -y 250 --up --udid SIMULATOR_UDID axe touch -x 150 -y 250 --down --up --delay 1.0 --udid SIMULATOR_UDID

# Scrolling gestures axe gesture scroll-up --udid SIMULATOR_UDID axe gesture scroll-down --udid SIMULATOR_UDID axe gesture scroll-left --udid SIMULATOR_UDID axe gesture scroll-right --udid SIMULATOR_UDID # Navigation gestures axe gesture swipe-from-left-edge --udid SIMULATOR_UDID axe gesture swipe-from-right-edge --udid SIMULATOR_UDID axe gesture swipe-from-top-edge --udid SIMULATOR_UDID axe gesture swipe-from-bottom-edge --udid SIMULATOR_UDID # With custom screen dimensions axe gesture scroll-up --screen-width 430 --screen-height 932 --udid SIMULATOR_UDID # With timing controls axe gesture scroll-down --pre-delay 1.0 --post-delay 0.5 --udid SIMULATOR_UDID

# Simple text input (use single quotes for special characters) axe type 'Hello World!' --udid SIMULATOR_UDID # From stdin (best for automation) echo "Complex text" | axe type --stdin --udid SIMULATOR_UDID # From file axe type --file input.txt --udid SIMULATOR_UDID

# Available buttons: home, lock, side-button, siri, apple-pay axe button home --udid SIMULATOR_UDID axe button lock --duration 2.0 --udid SIMULATOR_UDID axe button siri --udid SIMULATOR_UDID

# Individual key presses (by HID keycode) axe key 40 --udid SIMULATOR_UDID # Enter key axe key 42 --duration 1.0 --udid SIMULATOR_UDID # Hold Backspace # Key sequences axe key-sequence --keycodes 11,8,15,15,18 --udid SIMULATOR_UDID # Type "hello"

# Stream MJPEG frames over stdout (default format) axe stream-video --udid SIMULATOR_UDID --fps 10 --format mjpeg > stream.mjpeg # Pipe JPEG frames directly into ffmpeg axe stream-video --udid SIMULATOR_UDID --fps 30 --format ffmpeg | \ ffmpeg -f image2pipe -framerate 30 -i - -c:v libx264 -preset ultrafast output.mp4 # Stream raw JPEG frames with length prefixes for custom servers axe stream-video --udid SIMULATOR_UDID --fps 12 --format raw | custom-stream-consumer # Legacy BGRA stream for backward compatibility axe stream-video --udid SIMULATOR_UDID --format bgra | \ ffmpeg -f rawvideo -pixel_format bgra -video_size 393x852 -i - output.mp4 # Record directly to MP4 using the dedicated recorder axe record-video --udid SIMULATOR_UDID --fps 15 --output recording.mp4

# Record the simulator to an MP4 file (QuickTime compatible) axe record-video --udid SIMULATOR_UDID --fps 15 --output recording.mp4 # Let AXe pick a timestamped filename in the current directory axe record-video --udid SIMULATOR_UDID --fps 20 # Tweak quality/scale to reduce file size axe record-video --udid SIMULATOR_UDID --fps 10 --quality 60 --scale 0.5 --output low-bandwidth.mp4

Tip

Press Ctrl+C to stop recording. AXe finalises the MP4 before exiting and prints the file path to stdout.

# Get accessibility information axe describe-ui --udid SIMULATOR_UDID # Full screen axe describe-ui --point 100,200 --udid SIMULATOR_UDID # Specific point # List simulators axe list-simulators

AXe directly utilises the lower-level frameworks provided by idb, Facebook's open-source suite for automating iOS Simulators and Devices.

While idb offers a powerful client/server architecture and a broad set of device automation features via an RPC protocol, AXe takes a different approach:

Single Binary: AXe is distributed as a single, standalone CLI tool—no server or client setup required.
Focused Scope: AXe is purpose-built for UI automation, streamlining accessibility testing and automation tasks.
Simple Integration: With no external dependencies or daemons, AXe can be easily scripted and embedded into other tools or systems running on the same host.
Complete HID Coverage: Full feature parity with idb's HID functionality plus gesture presets and timing controls.
Intelligent Automation: Built-in gesture presets and coordinate helpers for common use cases.

This makes AXe a lightweight and easily adoptable alternative for projects that need direct, scriptable access to Simulator automation.

Gesture Presets Reference

Preset Description Use Case

scroll-up	Scroll up in center of screen	Content navigation
scroll-down	Scroll down in center of screen	Content navigation
scroll-left	Scroll left in center of screen	Horizontal scrolling
scroll-right	Scroll right in center of screen	Horizontal scrolling
swipe-from-left-edge	Left edge to right edge	Back navigation
swipe-from-right-edge	Right edge to left edge	Forward navigation
swipe-from-top-edge	Top to bottom	Dismiss/close
swipe-from-bottom-edge	Bottom to top	Open/reveal