AXorcist

https://github.com/openclaw/axorcist
Admin
AXorcist is a Swift framework and CLI tool providing a type-safe, chainable interface for macOS...
Tokens:11,000
Snippets:106
Trust Score:8.8
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install AXorcist CLI with Homebrew

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Installs the signed, notarized universal command-line tool via Homebrew.

```bash
brew install openclaw/tap/axorcist
```

--------------------------------

### AXorcist usage example with QueryCommand

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Shows how to use the AXorcist singleton to run a query command that locates an accessibility button in the Safari app. Creates a QueryCommand with an app identifier and a locator criterion, wraps it in an AXCommandEnvelope, and passes it to runCommand.

```swift
import AXorcist

let axorcist = AXorcist.shared
let query = QueryCommand(
    appIdentifier: "Safari",
    locator: Locator(criteria: [Criterion(attribute: "AXRole", value: "AXButton")]))
let command = AXCommandEnvelope(
    commandID: "find-button",
    command: .query(query)
)
let response = axorcist.runCommand(command)
```

--------------------------------

### Get Element at Point

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Finds an element at specific screen coordinates.

```json
{
  "command_id": "element-at-point",
  "command": "getElementAtPoint",
  "point": [500, 300],
  "attributes": ["AXRole", "AXTitle"]
}
```

--------------------------------

### Verify Homebrew installation with cmp and codesign

Source: https://github.com/openclaw/axorcist/blob/main/docs/releasing.md

Confirm Homebrew preserved the published executable byte-for-byte and retained its Developer ID requirement. The designated requirement must contain 'anchor apple generic'; an ad-hoc requirement is a release blocker.

```bash
cmp axorc "$(brew --prefix axorc)/bin/axorc"
codesign --verify --strict "$(brew --prefix axorc)/bin/axorc"
codesign -d -r- "$(brew --prefix axorc)/bin/axorc"
```

--------------------------------

### batch

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Executes multiple commands in sequence. Raw input accepts one command object or a single-element array. Empty arrays and arrays containing multiple commands fail before dispatch; use `batch` with `sub_commands` for multiple operations. Every child must convert to a supported library command before execution starts, including children of nested batches. Invalid children reject the entire batch and no children execute. After validation, runtime failures retain the existing behavior: remaining children still execute, and the response reports an aggregate error without per-command data. Encoding failures return escaped JSON even when command IDs contain quotes or newlines.

```APIDOC
## Batch Commands

### Description
Executes multiple commands in sequence. Raw input accepts one command object or a single-element array. Empty arrays and arrays containing multiple commands fail before dispatch; use `batch` with `sub_commands` for multiple operations. Every child must convert to a supported library command before execution starts, including children of nested batches. Invalid children reject the entire batch and no children execute. After validation, runtime failures retain the existing behavior: remaining children still execute, and the response reports an aggregate error without per-command data. Encoding failures return escaped JSON even when command IDs contain quotes or newlines.

### Command
batch

### Request Example
{
  "command_id": "inspect-and-fill",
  "command": "batch",
  "sub_commands": [
    {
      "command_id": "find-text-area",
      "command": "query",
      "application": "TextEdit",
      "locator": {"criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]}
    },
    {
      "command_id": "fill-text-area",
      "command": "setFocusedValue",
      "application": "TextEdit",
      "locator": {"criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]},
      "action_value": "Hello, World!"
    }
  ]
}
```

--------------------------------

### Get Focused Element

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Retrieves the currently focused element.

```json
{
  "command_id": "focused-element",
  "command": "getFocusedElement",
  "attributes": ["AXRole", "AXTitle", "AXValue"]
}
```

--------------------------------

### setFocusedValue command JSON

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Sets the AXValue attribute on an element, optionally focusing it first. Use this command when the target may need focus before the value is applied. The example targets a TextEdit AXTextArea with the given action_value.

```json
{
  "command_id": "replace-text",
  "command": "setFocusedValue",
  "application": "TextEdit",
  "locator": {"criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]},
  "action_value": "New text content"
}
```

--------------------------------

### Swift API: Initialize AXorcist and run a query command

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Initializes AXorcist, builds a QueryCommand with an app identifier and locator criteria, then executes it via runCommand with an AXCommandEnvelope. Use this to query accessibility elements such as a text area in a target application.

```swift
import AXorcist

// Initialize AXorcist
let axorcist = AXorcist()

// Create a query command
let query = QueryCommand(
    appIdentifier: "com.apple.TextEdit",
    locator: Locator(criteria: [
        Criterion(attribute: 
```

--------------------------------

### Render Homebrew formula with render-homebrew-formula.sh

Source: https://github.com/openclaw/axorcist/blob/main/docs/releasing.md

Render the formula from the directory containing the public archives and checksum files. The renderer checks each checksum against its archive and selects thin downloads only when both architecture pairs are present.

```bash
scripts/render-homebrew-formula.sh 0.2.1 --artifacts <verified-directory> > axorc.rb
```

--------------------------------

### observe

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Monitors UI changes in real-time.

```APIDOC
## Observe Notifications

### Description
Monitors UI changes in real-time.

### Command
observe

### Request Example
{
  "command_id": "watch-text-edit",
  "command": "observe",
  "application": "com.apple.TextEdit",
  "notifications": ["AXValueChanged", "AXFocusedUIElementChanged"],
  "include_element_details": ["AXRole", "AXTitle", "AXValue"],
  "watch_children": false
}
```

--------------------------------

### Check Accessibility permission and print recovery instructions

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Run the axorc permissions command to check the Accessibility permission and print recovery instructions.

```bash
axorc permissions
```

--------------------------------

### axorc permissions

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Inspect application permissions and recovery instructions.

```APIDOC
## [CLI] axorc permissions

### Description
Check permission and recovery instructions for the axorc command-line tool.

### Method
CLI

### Endpoint
`axorc permissions`

### Parameters
None

### Response
Human-readable output to stdout, diagnostics to stderr, nonzero exit code on failure.

```

--------------------------------

### Verify notarization ticket with codesign

Source: https://github.com/openclaw/axorcist/blob/main/docs/releasing.md

Run this command to verify the standalone executable's notarization ticket. Note that spctl --assess --type execute is an app assessment and can reject valid standalone executables.

```bash
codesign -vvvv -R="notarized" --check-notarization axorc
```

--------------------------------

### query

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Find elements in the accessibility tree using criteria and/or path navigation.

```APIDOC
## [JSON] query

### Description
Find elements in the accessibility tree using criteria and/or path navigation.

### Method
JSON

### Endpoint
`axorc raw --json '{"command_id":"<id>","command":"query","application":"<app>","locator":{...}}'`

### Parameters
#### Request Body
- **command_id** (string) - Required - Unique identifier for the command.
- **command** (string) - Required - Must be `"query"`.
- **application** (string) - Required - Bundle identifier or application name.
- **locator** (object) - Required - Contains `criteria` and/or `path_from_root`.
  - **criteria** (array) - Optional - List of attribute-value pairs.
  - **path_from_root** (array) - Optional - Path from root element.

### Request Example
```json
{
  "command_id": "enabled-button",
  "command": "query",
  "application": "Safari",
  "locator": {
    "criteria": [
      {"attribute": "AXRole", "value": "AXButton"},
      {"attribute": "AXEnabled", "value": "true"}
    ]
  }
}
```

### Response
JSON output to stdout, diagnostics to stderr, nonzero exit code on failure.

```

--------------------------------

### Batch Commands

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Executes multiple commands in sequence.

```json
{
  "command_id": "batch-commands",
  "command": "batch",
  "commands": [
    {
      "command_id": "find-text-area",
      "command": "query",
      "application": "com.apple.TextEdit",
      "locator": {
        
```

--------------------------------

### Perform Action - press-back

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Executes an action on a located element. Use this to trigger actions like AXPress on a matching element.

```json
{
  "command_id": "press-back",
  "command": "performAction",
  "application": "Safari",
  "locator": {
    "criteria": [{"attribute": "AXTitle", "value": "Back"}]
  },
  "action_name": "AXPress"
}
```

--------------------------------

### performAction

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Executes actions on elements.

```APIDOC
## Perform Action

### Description
Executes actions on elements.

### Command
performAction

### Request Example
{
  "command_id": "press-back",
  "command": "performAction",
  "application": "Safari",
  "locator": {
    "criteria": [{"attribute": "AXTitle", "value": "Back"}]
  },
  "action_name": "AXPress"
}
```

--------------------------------

### query

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Finds elements and retrieves their attributes.

```APIDOC
## Query

### Description
Finds elements and retrieves their attributes.

### Command
query

### Request Example
{
  "command_id": "find-text-area",
  "command": "query",
  "application": "com.apple.TextEdit",
  "locator": {
    "criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]
  },
  "attributes": ["AXValue", "AXRole", "AXTitle"],
  "max_depth": 10
}
```

--------------------------------

### Enable debug logging in commands

Source: https://github.com/openclaw/axorcist/blob/main/README.md

JSON configuration enabling debug logging in commands. Sets debug_logging to true for a query command.

```json
{
  "command_id": "debug-query",
  "command": "query",
  "debug_logging": true,
  ...
}
```

--------------------------------

### collectAll

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Collect the entire accessibility tree for an application, with optional depth and attributes.

```APIDOC
## [JSON] collectAll

### Description
Collect the entire accessibility tree for an application, with optional depth and attributes.

### Method
JSON

### Endpoint
`axorc raw --json '{"command_id":"<id>","command":"collectAll","application":"<app>","max_depth":<depth>,"attributes":[...]}'`

### Parameters
#### Request Body
- **command_id** (string) - Required - Unique identifier for the command.
- **command** (string) - Required - Must be `"collectAll"`.
- **application** (string) - Required - Bundle identifier or application name.
- **max_depth** (integer) - Optional - Maximum depth of the tree.
- **attributes** (array) - Optional - List of attribute names to include.

### Request Example
```json
{
  "command_id": "mail-tree",
  "command": "collectAll",
  "application": "com.apple.mail",
  "max_depth": 3,
  "attributes": ["AXRole","AXTitle","AXDescription","AXIdentifier","AXValue"]
}
```

### Response
JSON output to stdout, diagnostics to stderr, nonzero exit code on failure.

```

--------------------------------

### axorc CLI inspection commands

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Shows the human-readable inspection commands for axorc: checking permissions, printing an application hierarchy, limiting a tree to one role with JSON output, and finding elements by exact or case-insensitive substring matching. Human-readable output goes to stdout, diagnostics to stderr, and failures return nonzero exit codes. Run `axorc --help` or `axorc help find` for the complete terminal reference.

```bash
# Check permission and recovery instructions
axorc permissions

# Print a hierarchy; use a bundle identifier when names are ambiguous
axorc tree --app com.apple.dock --depth 3

# Limit a tree to one role and emit JSON for scripts
axorc tree --app com.apple.dock --role AXDockItem --json

# Find one element with exact matching
axorc find --app Safari --role AXButton --title Back

# Use case-insensitive substring matching
axorc find --app Safari --title address --contains
```

--------------------------------

### Request Accessibility Permissions

Source: https://github.com/openclaw/axorcist/blob/main/Sources/AXorcist/Documentation.docc/AXorcist.md

Requests accessibility permissions and initializes the shared AXorcist instance if granted. Use this before performing any accessibility operations.

```swift
import AXorcist

let hasPermissions = await AXPermissionHelpers.requestPermissions()
if hasPermissions {
    let axorcist = AXorcist.shared
    // Begin accessibility operations
}
```

--------------------------------

### Query command: find-text-area

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Finds elements by attribute criteria and retrieves their attributes. The locator uses AXRole with value AXTextArea, and the response includes AXValue, AXRole, and AXTitle attributes with a max_depth of 10.

```json
{
  "command_id": "find-text-area",
  "command": "query",
  "application": "com.apple.TextEdit",
  "locator": {
    "criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]
  },
  "attributes": ["AXValue", "AXRole", "AXTitle"],
  "max_depth": 10
}
```

--------------------------------

### performAction

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Perform an accessibility action on an element identified by a locator.

```APIDOC
## [JSON] performAction

### Description
Perform an accessibility action on an element identified by a locator.

### Method
JSON

### Endpoint
`axorc raw --json '{"command_id":"<id>","command":"performAction","application":"<app>","locator":{...},"action_name":"<action>"}'`

### Parameters
#### Request Body
- **command_id** (string) - Required - Unique identifier for the command.
- **command** (string) - Required - Must be `"performAction"`.
- **application** (string) - Required - Bundle identifier or application name.
- **locator** (object) - Required - Contains `criteria` and/or `path_from_root`.
- **action_name** (string) - Required - Name of the action to perform (e.g., `"AXPress"`).

### Request Example
```json
{
  "command_id": "press-back",
  "command": "performAction",
  "application": "com.apple.Safari",
  "locator": {
    "path_from_root": [
      {"attribute": "AXRole", "value": "AXWindow"},
      {"attribute": "AXIdentifier", "value": "toolbar"}
    ],
    "criteria": [{"attribute": "AXTitle", "value": "Back"}]
  },
  "action_name": "AXPress"
}
```

### Response
JSON output to stdout, diagnostics to stderr, nonzero exit code on failure.

```

--------------------------------

### Complex Search with Path Navigation

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Queries Safari for a button using a path from the root and criteria. The locator combines a path_from_root array with criteria filters and requests specific attributes in the response.

```json
{
  "command_id": "find-submit",
  "command": "query",
  "application": "com.apple.Safari",
  "locator": {
    "path_from_root": [
      {"attribute": "AXRole", "value": "AXWindow", "depth": 1},
      {"attribute": "AXRole", "value": "AXWebArea", "depth": 5}
    ],
    "criteria": [
      {"attribute": "AXRole", "value": "AXButton"},
      {"attribute": "AXDOMClassList", "value": "submit-button primary", "match_type": "contains"}
    ]
  },
  "attributes": ["AXTitle", "AXValue", "AXEnabled", "AXPosition", "AXSize"],
  "command_id": "find-submit",
  "command": "query",
  "application": "com.apple.Safari"
}
```

--------------------------------

### axorc tree

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Print a hierarchy of the accessibility tree for an application, with optional depth and role filtering.

```APIDOC
## [CLI] axorc tree

### Description
Print a hierarchy of the accessibility tree for a given application, with optional depth and role filtering. JSON output is available for scripts.

### Method
CLI

### Endpoint
`axorc tree --app <app> --depth <depth> [--role <role>] [--json]`

### Parameters
#### Options
- **--app** (string) - Required - Bundle identifier or application name.
- **--depth** (integer) - Optional - Maximum depth of the tree.
- **--role** (string) - Optional - Limit the tree to a specific role.
- **--json** (flag) - Optional - Emit JSON output.

### Response
Human-readable output to stdout, diagnostics to stderr, nonzero exit code on failure.

```

--------------------------------

### Global notification watching with NotificationWatcher

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Creates a NotificationWatcher for the global focusedUIElementChanged notification. The closure receives the PID and the changed AXUIElement when the focused element changes. Use this to monitor focus changes across all running user applications, including menu-bar agents and background applications.

```swift
let watcher = NotificationWatcher(globalNotification: .focusedUIElementChanged) {
    pid, element in
    // handle focus change
}
```

--------------------------------

### Build release artifact with codesign identity

Source: https://github.com/openclaw/axorcist/blob/main/docs/releasing.md

Builds the release artifact using the specified Developer ID Application identity. The identity must be set via the AXORC_CODESIGN_IDENTITY environment variable.

```bash
AXORC_CODESIGN_IDENTITY='Developer ID Application: ...' scripts/build-release-artifact.sh 0.2.1
```

--------------------------------

### axorc raw

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Send raw JSON commands to the axorc protocol, supporting multiple input methods.

```APIDOC
## [CLI] axorc raw

### Description
Send a raw JSON command to the axorc protocol. Supports input from standard input, a file, or an argument.

### Method
CLI

### Endpoint
`axorc raw --stdin | --file <file> | --json <json>`

### Parameters
#### Options
- **--stdin** (flag) - Optional - Read JSON from standard input.
- **--file** (string) - Optional - Read JSON from a file.
- **--json** (string) - Optional - Provide JSON as an argument.

### Request Example
```json
{"command_id":"health","command":"ping"}
```

### Response
JSON output to stdout, diagnostics to stderr, nonzero exit code on failure.

```

--------------------------------

### Debug flag for detailed search logs

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Use the debug flag to see detailed search logs.

```bash
axorc raw --file command.json --debug
```

--------------------------------

### AXorcist main class definition

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Defines the central orchestrator for accessibility operations. Uses a singleton pattern with MainActor isolation for thread safety and a command-based architecture. The runCommand method accepts an AXCommandEnvelope and returns an AXResponse.

```swift
@MainActor
public class AXorcist {
    static let shared = AXorcist()
    public func runCommand(_ commandEnvelope: AXCommandEnvelope) -> AXResponse
}
```

--------------------------------

### getElementAtPoint

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Finds element at specific screen coordinates.

```APIDOC
## Get Element at Point

### Description
Finds element at specific screen coordinates.

### Command
getElementAtPoint

### Request Example
{
  "command_id": "element-at-point",
  "command": "getElementAtPoint",
  "point": [500, 300],
  "attributes": ["AXRole", "AXTitle"]
}
```

--------------------------------

### ping

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Check the health of the axorc service.

```APIDOC
## [JSON] ping

### Description
Check the health of the axorc service.

### Method
JSON

### Endpoint
`axorc raw --json '{"command_id":"<id>","command":"ping"}'`

### Parameters
#### Request Body
- **command_id** (string) - Required - Unique identifier for the command.
- **command** (string) - Required - Must be `"ping"`.

### Response
JSON output to stdout, diagnostics to stderr, nonzero exit code on failure.

```

--------------------------------

### axorc find

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Find one element with exact or case-insensitive substring matching.

```APIDOC
## [CLI] axorc find

### Description
Find one element in the accessibility tree with exact or case-insensitive substring matching.

### Method
CLI

### Endpoint
`axorc find --app <app> [--role <role>] [--title <title>] [--contains]`

### Parameters
#### Options
- **--app** (string) - Required - Bundle identifier or application name.
- **--role** (string) - Optional - Role to match.
- **--title** (string) - Optional - Title to match.
- **--contains** (flag) - Optional - Use case-insensitive substring matching.

### Response
Human-readable output to stdout, diagnostics to stderr, nonzero exit code on failure.

```

--------------------------------

### collectAll

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Recursively collects all elements. Collection honors the request's traversal timeout (`--timeout` in the CLI), checking the deadline between elements. When the deadline expires, it logs a warning and returns the elements collected so far as a successful partial result. The traversal deadline does not interrupt an accessibility call already in progress.

```APIDOC
## Collect All

### Description
Recursively collects all elements. Collection honors the request's traversal timeout (`--timeout` in the CLI), checking the deadline between elements. When the deadline expires, it logs a warning and returns the elements collected so far as a successful partial result. The traversal deadline does not interrupt an accessibility call already in progress.

### Command
collectAll

### Request Example
{
  "command_id": "collect-buttons",
  "command": "collectAll",
  "application": "Safari",
  "attributes": ["AXRole", "AXTitle"],
  "max_depth": 5,
  "filter_criteria": {"AXRole": "AXButton"}
}
```

--------------------------------

### Add AXorcist dependency to Package.swift

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Adds the AXorcist package dependency to a Swift package manifest. Use this in the dependencies array of Package.swift to integrate the library.

```swift
dependencies: [
    .package(url: "https://github.com/openclaw/AXorcist.git", from: "0.2.1")
]
```

--------------------------------

### getFocusedElement

Source: https://github.com/openclaw/axorcist/blob/main/README.md

Retrieves the currently focused element.

```APIDOC
## Get Focused Element

### Description
Retrieves the currently focused element.

### Command
getFocusedElement

### Request Example
{
  "command_id": "focused-element",
  "command": "getFocusedElement",
  "attributes": ["AXRole", "AXTitle", "AXValue"]
}
```
Tokens:
Raw