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
axe [--output text|json] <command> [options] --udid <UDID>Every command has help with a short description, examples and one line per option:
axe --help
axe tap --help
axe help settings status-barCommand groups
| Group | Commands |
|---|---|
| Discovery and readiness | list-simulators, list-devices, doctor, displays |
| Reading the UI | describe-ui |
| Touch input | tap, slider, swipe, drag, draw, touch, gesture |
| Keyboard | type, key, key-sequence, key-combo |
| Device | button, rotate, hinge, settings, shutdown, clipboard |
| Capture | screenshot, record-video, stream-video |
| Automation | batch, 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
| Route | Flag | What it does |
|---|---|---|
| Plain | none | Sends 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 selected | Binds 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 | --agent | Acts 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
| Stream | What goes there |
|---|---|
| stdout | Results: 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. |
| stderr | Error: <message> on failure, stream-video dimensions and summaries, --verbose logs from batch, and AXE_TIMING=1 tables. |
SHOT=$(axe screenshot --udid "$UDID")
axe stream-video --udid "$UDID" --format ffmpeg | ffmpeg -f image2pipe -framerate 10 -i - out.mp4See 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.