AXe

<img src="banner.png" alt="AXe" width="600"/>

AXe is a command-line tool that automates iOS simulators, including the dual-screen iPhone Duo, and connected iPhones and iPads. It reads the accessibility tree, sends taps, typing, gestures and hardware buttons, captures screenshots and video, and changes device settings. An agent mode gives AI agents checked, stateful control of the UI.

[![CI](https://github.com/cameroncooke/AXe/actions/workflows/release.yml/badge.svg)](https://github.com/cameroncooke/AXe/actions/workflows/release.yml)
[![Licence: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Install

```bash
brew install cameroncooke/axe/axe
axe --help
```

### AI skill

`axe init` installs the skill bundled with your AXe binary for the AI clients it detects (`--client claude|agents`, `--dest <dir>`, `--force`, `--uninstall`, `--print`). To keep the skill updated as releases ship, install it from this repository's marketplace instead, and keep the CLI on the latest release:

```bash
claude plugin marketplace add cameroncooke/AXe && claude plugin install axe@axe
codex plugin marketplace add cameroncooke/AXe && codex plugin add axe@axe
```

The marketplace reads the case-sensitive `Skills/CLI` path; clients that require a lowercase `skills/` directory are unsupported.

## Quick start

```bash
axe list-simulators                       # find a booted simulator's UDID
export UDID=<UDID>
axe describe-ui --udid "$UDID"            # accessibility tree as JSON
axe tap --label "Continue" --udid "$UDID"
axe type 'Hello world' --udid "$UDID"
axe screenshot --udid "$UDID" --output screen.png
```

Every command needs an explicit `--udid`; AXe never picks a device for you. Coordinates are logical points in the current orientation, the units `axe displays` reports, not screenshot pixels. Run `axe <command> --help` for every option.

## Output and errors

Without `--output`, commands print text:

- Commands that read or change state print that state in a few lines (`displays`, `settings`, `hinge`, `rotate`, `doctor`, `shutdown`, `clipboard copy`).
- Input commands print nothing on success, except `tap`, `slider` and `batch`, which print a `✓ … completed successfully` line.
- `screenshot` and `record-video` print the file path.
- A failure prints `Error: <message>` to stderr and exits nonzero.

Put `--output json` before the command for one `axe.output.command-result` object on stdout:

```
$ axe --output json screenshot --udid "$UDID" --output shot.png
{"command":"screenshot","data":{"result":{"path":"/…/shot.png","pixelHeight":2868,"pixelWidth":1320}},"didError":false,"nextSteps":[],"schema":"axe.output.command-result","schemaVersion":"1"}

$ axe --output json tap --id no-such-element --udid "$UDID"
{"command":"tap","data":{},"didError":true,"error":{"code":"elementNotFound","message":"No accessibility element matched --id 'no-such-element'. …"},"nextSteps":[],"schema":"axe.output.command-result","schemaVers