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
axe describe-ui --udid "$UDID" # the whole tree as JSON
axe describe-ui --point 200,400 --udid "$UDID" # the element at one pointUseful 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
| Selector | Commands | When to use it |
|---|---|---|
--id | tap, slider | Preferred. Matches the accessibility identifier. |
--label | tap, slider | When labels are stable and you know how localisation affects them. |
--value | tap | When the current value is the only stable thing about the target. |
--element-type | tap, slider | Narrows 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.
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
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:
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:
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:
| Value | Behaviour |
|---|---|
automatic | The default for plain taps. Sends a touch for switch-like controls such as UISwitch and SwiftUI Toggle, and a simulator tap otherwise. |
simulator | Always sends a simulator tap at the resolved point. |
physical | Always 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.
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:
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.