Native App Automation

Overview

Browse automates native apps on Android, iOS, and macOS using the same @ref workflow as web browsing. All platforms support: snapshot, text, tap, fill, type, press, swipe, screenshot.

Enable Platforms

browse enable android    # Installs adb, JDK, SDK, emulator, driver APK
browse enable ios        # Builds iOS runner (requires Xcode)
browse enable macos      # Builds macOS AX bridge (requires Xcode CLI tools)
browse enable all        # All platforms

Pre-built binaries ship with npm install. enable verifies they're ready. If building from source, it installs dependencies automatically.

Android

Start

browse sim start --platform android --app com.android.settings --visible

On first run, this automatically installs the full toolchain via Homebrew:

adb (Android platform-tools)
JDK 21 (OpenJDK)
Android SDK command-line tools
System image (API 35, arm64)
Android emulator
Default AVD (browse_default)

Interact

browse --platform android --app com.android.settings snapshot -i
browse --platform android --app com.android.settings tap @e3
browse --platform android --app com.android.settings swipe up
browse --platform android --app com.android.settings press back
browse --platform android --app com.android.settings text
browse --platform android --app com.android.settings screenshot app.png

Switch Apps

browse sim start --platform android --app com.google.android.dialer --visible

Switching --app restarts the driver with the new target. The emulator stays running.

Stop

browse sim stop --platform android    # Kills driver + emulator

Diagnostics

browse doctor --platform android

iOS

Start

browse sim start --platform ios --app com.apple.Preferences --visible

Requires Xcode. The simulator boots automatically.

Interact

browse --platform ios --app com.apple.Preferences snapshot -i
browse --platform ios --app com.apple.Preferences tap @e2
browse --platform ios --app com.apple.Preferences swipe up
browse --platform ios --app com.apple.Preferences press home
browse --platform ios --app com.apple.Preferences type "hello"

Switch Apps

browse --platform ios --app com.apple.mobilesafari snapshot -i

iOS reconfigures the runner in-place — no restart needed when switching apps.

Stop

browse sim stop --platform ios

macOS

macOS doesn't need a simulator — it automates apps directly via the Accessibility API.

Interact

browse --app "System Settings" snapshot -i
browse --app "System Settings" tap @e5
browse --app "System Settings" swipe up
browse --app TextEdit type "Hello world"
browse --app TextEdit press "cmd+n"       # Modifier combos supported
browse --app TextEdit press "cmd+shift+s"

Requires: macOS, Accessibility permission granted to the terminal.

Platform Flags

Flag	Description
`--platform android\|ios`	Target platform
`--app <name>`	Package name (Android), bundle ID (iOS), or process name (macOS)
`--device <serial>`	Device serial (Android) or simulator UDID (iOS)
`--visible`	Show simulator/emulator window (default: headless)

Supported Commands

All platforms share the same command surface:

Command	Description
`snapshot -i`	Interactive elements with @refs
`text`	Extract visible text
`tap @ref`	Tap/click element
`fill @ref "value"`	Fill text field
`type "text"`	Type text (focused element)
`press <key>`	Press key (back, home, enter, cmd+n)
`swipe up\|down`	Scroll content
`screenshot [path]`	Capture screenshot

Commands requiring browser capabilities (goto, js, tabs, cookies) are blocked with clear errors on app targets.

On this page