AXedocs
Install

CLI Basics

The shape of an AXe command, how it picks a target, which units coordinates use, the three input routes and how long-running commands stop.

Synopsis#

shell
axe [--output text|json] <command> [options] --udid <UDID>

Every command has help with a short description, examples and one line per option:

shell
axe --help
axe tap --help
axe help settings status-bar

Command groups#

GroupCommands
Discovery and readinesslist-simulators, list-devices, doctor, displays
Reading the UIdescribe-ui
Touch inputtap, slider, swipe, drag, draw, touch, gesture
Keyboardtype, key, key-sequence, key-combo
Devicebutton, rotate, hinge, settings, shutdown, clipboard
Capturescreenshot, record-video, stream-video
Automationbatch, agent, init

See Command Reference for every option.

The --udid rule#

Every command that acts on a simulator or device needs --udid <UDID>; AXe never picks one for you, and an empty value never selects a device. list-simulators, list-devices and init take no UDID.

AXe looks the UDID up among simulators first, then among the physical devices Xcode's CoreDevice knows. A targetNotFound error names both. A shut-down simulator fails with notBooted.

batch takes --udid once; a step that names its own --udid is rejected.

Coordinates#

Coordinates are logical points in the current orientation, the units axe displays reports and describe-ui frames use. They are not screenshot pixels: a 3x screenshot of a 440-point-wide screen is 1320 pixels wide.

AXe maps points for rotated screens, letterboxed landscape-only apps, iPads and each iPhone Duo screen. Do not rotate or scale coordinates yourself.

Input routes#

RouteFlagWhat it does
PlainnoneSends input by point or selector. On the iPhone Duo and simulators with the DTUHID touch service, AXe measures the active screen and reuses one input connection.
Selected--input-mode selectedBinds one screen and one app before input. With --screen-id and --screen-uuid it refuses unless that screen is active; with --expected-pid it refuses if another app is frontmost. Simulators only. See iPhone Duo.
Agent--agentActs on a ref from a snapshot, checks the control is unchanged, sends the input and returns the settled screen. Simulators only. See Agent Mode.

Plain input confirms the events were sent, not that the app handled them. Read the screen afterwards, or use agent mode, which returns the new screen with every action.

stdout and stderr#

StreamWhat goes there
stdoutResults: describe-ui JSON, state summaries, the saved screenshot or video path, the ✓ line from tap, slider and batch, stream bytes, and the JSON envelope with --output json.
stderrError: <message> on failure, stream-video dimensions and summaries, --verbose logs from batch, and AXE_TIMING=1 tables.
shell
SHOT=$(axe screenshot --udid "$UDID")
axe stream-video --udid "$UDID" --format ffmpeg | ffmpeg -f image2pipe -framerate 10 -i - out.mp4

See Output & Errors for JSON output and error codes.

Exit status#

A successful command exits 0. A failure prints one error and exits nonzero. SIGINT or SIGTERM exits with 128 plus the signal number. An uncaught Objective-C exception exits with 70 and prints the exception.

Stopping long-running commands#

record-video and stream-video run until you press Ctrl+C or send SIGTERM. AXe stops capture, finishes the file and prints its path. SIGKILL skips that, and can leave a recording unfinished.

Timing flags#

Most input commands take --pre-delay and --post-delay (0 to 10 seconds) for scripts that need a fixed wait. Prefer tap --wait-timeout to wait for an element, and do not add delays in agent mode: agent actions return once the screen has settled.