AXedocs
Install

Reading & Tapping

Read the accessibility tree, choose selectors that survive layout changes, wait for elements, and tap, long press, double tap or two-finger tap.

Selectors are more reliable than coordinates. Prefer --id (the accessibility identifier), then --label, and use coordinates only when no accessibility element exists.

Read the UI#

shell
axe describe-ui --udid "$UDID"                 # the whole tree as JSON
axe describe-ui --point 200,400 --udid "$UDID" # the element at one point

Useful fields are AXUniqueId, AXLabel, AXValue, type, frame, enabled and customActions. Frames are in points, the same units as tap coordinates.

On a physical device the read is a new request each time and takes about 1 second plus 44 ms per element. For AI agents, describe-ui --agent returns compact rows with refs instead of the full tree; see Agent Mode.

Selectors#

SelectorCommandsWhen to use it
--idtap, sliderPreferred. Matches the accessibility identifier.
--labeltap, sliderWhen labels are stable and you know how localisation affects them.
--valuetapWhen the current value is the only stable thing about the target.
--element-typetap, sliderNarrows duplicates, for example Button, TextField or Switch.

tap takes either -x and -y, or exactly one of --id, --label or --value. A selector must match one element: no match fails with elementNotFound, several with ambiguousElement.

shell
axe tap --id SaveButton --element-type Button --udid "$UDID"
axe tap --label "Done" --udid "$UDID"
axe tap --value "Enabled" --udid "$UDID"
axe tap -x 200 -y 400 --udid "$UDID"

Agent mode adds --label-contains, --label-regex and --frame to narrow a selector; see Agent Mode.

Wait for dynamic UI#

shell
axe tap --label "Done" --wait-timeout 10 --poll-interval 0.25 --udid "$UDID"

--wait-timeout polls until a selector match appears. 0 (the default) does not wait, and coordinate taps never wait. In a batch, set --wait-timeout once on the batch and every selector tap step uses it.

Long press, double tap and two-finger tap#

On a point or an element:

shell
axe tap --label "Photo" --hold 1 --udid "$UDID"          # long press
axe tap --id Map --count 2 --udid "$UDID"                # double tap
axe tap --id Canvas --touches 2 --udid "$UDID"           # two-finger tap

--hold <seconds> keeps the finger down (above 0 to 10 seconds). --count 2 taps twice. --touches 2 uses two contacts 40 points apart around the point. These three send real touches and need plain input, without --agent or --input-mode selected.

For a press at a point with an exact duration, touch is the low-level form:

shell
axe touch -x 100 -y 200 --down --up --delay 1.0 --udid "$UDID"

Tap style and switches#

--tap-style chooses how a tap is sent:

ValueBehaviour
automaticThe default for plain taps. Sends a touch for switch-like controls such as UISwitch and SwiftUI Toggle, and a simulator tap otherwise.
simulatorAlways sends a simulator tap at the resolved point.
physicalAlways sends a touch down and up. The default with --agent and selected input.

When a selector matches a row that holds one switch, the default automatic style taps the switch itself.

shell
axe tap --label "Weather Alerts" --udid "$UDID"
axe tap --label "Weather Alerts" --tap-style simulator --udid "$UDID"

Sliders#

slider sets a slider to a percentage and checks the new value:

shell
axe slider --id volume --value 75 --udid "$UDID"
axe slider --label Volume --endpoint maximum --input-mode selected --udid "$UDID"

slider takes exactly one of --id or --label. --value is 0 to 100. It drags once, reads the slider's value back and fails if the value is outside tolerance; iOS sliders can be quantised, so AXe reports the value it observed rather than chasing an unreachable one. --endpoint minimum|maximum works with --agent or selected input. Physical devices do not support slider.

Native checkboxes#

tap --semantic-press --id <ID> presses a native CheckBox through accessibility and confirms that its value changed. On a physical device it prints Switch <id>: off -> on. Simulators need --input-mode selected for it.

Orientation#

tap, swipe, drag, draw, touch and gestures take the logical points that describe-ui and displays report, in the current orientation. AXe maps them for rotated screens and letterboxed landscape-only apps.