### AXorcist CLI Quick Start

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

Examples of using the AXorcist command-line tool for searching and performing actions.

```APIDOC
## Command Line Quick Start

### Description
Utilize the AXorcist CLI for common tasks like finding elements and performing actions via stdin.

### Method
Command Line Interface (CLI)

### Endpoint
N/A (Local execution)

### Parameters
- **stdin**: Accepts JSON payload for commands.

### Request Example
```bash
# Find all buttons in Safari
echo '{"command": "query", "application": "com.apple.Safari", "locator": {"criteria": [{"attribute": "AXRole", "value": "AXButton"}]}}' | axorc --stdin

# Click the Back button
echo '{"command": "performAction", "application": "Safari", "locator": {"criteria": [{"attribute": "AXTitle", "value": "Back"}]}, "action": "AXPress"}' | axorc --stdin
```

### Response
#### Success Response (200)
- **stdout**: JSON output detailing the command results.

#### Response Example
(Depends on the command executed)
```

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

### Automated Form Filling Example

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

This example demonstrates how to use the 'batch' command to perform a series of actions, such as filling in email and password fields and clicking a sign-in button in Safari.

```APIDOC
## POST /api/commands (Example)

### Description
Automates form filling by executing a batch of commands.

### Method
POST

### Endpoint
/api/commands

### Request Body
- **command** (string) - Required - The command type, should be "batch".
- **commands** (array) - Required - A list of commands to execute sequentially.
  - **command** (string) - Required - The specific action to perform (e.g., "performAction").
  - **application** (string) - Required - The application to target (e.g., "Safari").
  - **locator** (object) - Required - Defines how to find the UI element.
    - **criteria** (array) - Required - A list of attributes to match.
      - **attribute** (string) - Required - The accessibility attribute to check (e.g., "AXRole", "AXPlaceholderValue").
      - **value** (string) - Required - The value to match the attribute against.
      - **match_type** (string) - Optional - How to match the value (e.g., "contains").
  - **action** (string) - Required - The accessibility action to perform (e.g., "AXSetValue", "AXPress").
  - **actionValue** (string) - Optional - The value to set for the action (e.g., for "AXSetValue").

### Request Example
```json
{
  "command": "batch",
  "commands": [
    {
      "command": "performAction",
      "application": "Safari",
      "locator": {
        "criteria": [
          {"attribute": "AXRole", "value": "AXTextField"},
          {"attribute": "AXPlaceholderValue", "value": "Email", "match_type": "contains"}
        ]
      },
      "action": "AXSetValue",
      "actionValue": "user@example.com"
    },
    {
      "command": "performAction",
      "application": "Safari",
      "locator": {
        "criteria": [
          {"attribute": "AXRole", "value": "AXTextField"},
          {"attribute": "AXPlaceholderValue", "value": "Password", "match_type": "contains"}
        ]
      },
      "action": "AXSetValue",
      "actionValue": "secretpassword"
    },
    {
      "command": "performAction",
      "application": "Safari",
      "locator": {
        "criteria": [
          {"attribute": "AXRole", "value": "AXButton"},
          {"attribute": "AXTitle", "value": "Sign In", "match_type": "contains"}
        ]
      },
      "action": "AXPress"
    }
  ]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "status": "success",
  "message": "Batch commands executed successfully."
}
```
```

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

### Monitoring Text Changes Example

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

This example shows how to set up an observer to monitor text changes within a specific application, like TextEdit.

```APIDOC
## POST /api/observe (Example)

### Description
Sets up an observer to monitor specific UI element changes within an application.

### Method
POST

### Endpoint
/api/observe

### Parameters
#### Request Body
- **command** (string) - Required - The command type, should be "observe".
- **application** (string) - Required - The bundle identifier of the application to observe (e.g., "com.apple.TextEdit").
- **notifications** (array of strings) - Required - A list of accessibility notifications to listen for (e.g., "AXValueChanged", "AXSelectedTextChanged").
- **locator** (object) - Required - Defines the UI element to observe.
  - **criteria** (array) - Required - A list of attributes to match.
    - **attribute** (string) - Required - The accessibility attribute to check (e.g., "AXRole").
    - **value** (string) - Required - The value to match the attribute against.
- **includeDetails** (boolean) - Optional - Whether to include details in the notification payload.
- **watchChildren** (boolean) - Optional - Whether to also observe changes in child elements.

### Request Example
```json
{
  "command": "observe",
  "application": "com.apple.TextEdit",
  "notifications": ["AXValueChanged", "AXSelectedTextChanged"],
  "locator": {
    "criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]
  },
  "includeDetails": true,
  "watchChildren": true
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of setting up the observer.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "status": "success",
  "message": "Observer set up successfully."
}
```
```

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

### Enabling Debug Logging

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

This example shows how to enable debug logging for a specific command to get more detailed output.

```APIDOC
## POST /api/command (Example with Debug)

### Description
Executes a command with debug logging enabled for detailed troubleshooting.

### Method
POST

### Endpoint
/api/command

### Parameters
#### Request Body
- **command** (string) - Required - The command to execute (e.g., "query").
- **debugLogging** (boolean) - Required - Set to true to enable debug logging.
- Other command-specific parameters...

### Request Example
```json
{
  "command": "query",
  "debugLogging": true,
  "application": "com.apple.finder",
  "locator": {
    "criteria": [
      {"attribute": "AXRole", "value": "AXWindow"}
    ]
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **message** (string) - A confirmation message or command output.
- **debugInfo** (object) - Optional - Detailed debug information if logging was enabled.

#### Response Example
```json
{
  "status": "success",
  "message": "Query executed.",
  "debugInfo": {
    "searchPath": "...",
    "matchedElements": "..."
  }
}
```
```

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

### Command-Line Interface (CLI)

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

Provides examples for using the Axorcist tool from the command line.

```APIDOC
## Command-Line Usage

### Basic Usage

Run commands using JSON payloads via files or standard input.

```bash
# Run command from file
axorc --file command.json

# Run command from stdin
echo '{"command": "ping"}' | axorc --stdin

# Pretty print output
axorc --file command.json --pretty

# Include debug logging
axorc --file command.json --debug
```

### Advanced CLI Examples

Examples demonstrating more complex command-line operations.

```bash
# Find all enabled buttons
echo '{
  "command": "query",
  "application": "Safari",
  "locator": {
    "criteria": [
      {"attribute": "AXRole", "value": "AXButton"},
      {"attribute": "AXEnabled", "value": "true"}
    ]
  }
}' | axorc --stdin --pretty

# Click button using path navigation
echo '{
  "command": "performAction",
  "application": "com.apple.Safari",
  "locator": {
    "path_from_root": [
      {"attribute": "AXRole", "value": "AXWindow"},
      {"attribute": "AXIdentifier", "value": "toolbar"}
    ],
    "criteria": [{"attribute": "AXTitle", "value": "Back"}]
  },
  "action": "AXPress"
}' | axorc --stdin
```
```

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

### AXorcist Swift API Quick Start

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

Demonstrates how to initialize AXorcist and run a query command using the Swift API.

```APIDOC
## Swift API Quick Start

### Description
Initialize AXorcist and execute a query command to find UI elements.

### Method
Swift API Call

### Endpoint
N/A (In-memory execution)

### Parameters
N/A

### Request Example
```swift
import AXorcist

let axorcist = AXorcist()
let query = QueryCommand(
    appIdentifier: "com.apple.TextEdit",
    locator: AXLocator(criteria: [
        AXCriterion(attribute: "AXRole", value: "AXTextArea")
    ]),
    attributesToReturn: ["AXValue", "AXRole"]
)
let response = axorcist.runCommand(AXCommandEnvelope(
    commandID: "query-1",
    command: .query(query)
))
```

### Response
#### Success Response (200)
- **response** (AXCommandResponse) - The result of the command execution.

#### Response Example
(Depends on the query result)
```

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

### CLI Basic Usage

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

Examples of running Axorcist commands via the command line, including reading from files, stdin, and formatting output.

```bash
# Run command from file
axorc --file command.json

# Run command from stdin
echo '{"command": "ping"}' | axorc --stdin

# Pretty print output
axorc --file command.json --pretty

# Include debug logging
axorc --file command.json --debug
```

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

### CLI Advanced Examples

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

Advanced CLI usage for complex queries and path-based element interaction.

```bash
# Find all enabled buttons
echo '{
  "command": "query",
  "application": "Safari",
  "locator": {
    "criteria": [
      {"attribute": "AXRole", "value": "AXButton"},
      {"attribute": "AXEnabled", "value": "true"}
    ]
  }
}' | axorc --stdin --pretty

# Click button using path navigation
echo '{
  "command": "performAction",
  "application": "com.apple.Safari",
  "locator": {
    "path_from_root": [
      {"attribute": "AXRole", "value": "AXWindow"},
      {"attribute": "AXIdentifier", "value": "toolbar"}
    ],
    "criteria": [{"attribute": "AXTitle", "value": "Back"}]
  },
  "action": "AXPress"
}' | axorc --stdin
```

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

### Build and Install AXorcist CLI

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

Compile the AXorcist command-line tool from source and move the binary to the system path for global access.

```bash
swift build -c release
cp .build/release/axorc /usr/local/bin/
```

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

### Define Element Search Criteria

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

Examples of JSON configurations for locating UI elements using exact matches, substring matching, class lists, and logical OR operations.

```json
{
  "criteria": [
    {"attribute": "role", "value": "AXButton"},
    {"attribute": "title", "value": "Submit"}
  ]
}

{
  "criteria": [
    {"attribute": "role", "value": "AXTextField"},
    {"attribute": "title", "value": "email", "match_type": "contains"}
  ]
}

{
  "criteria": [
    {"attribute": "domclasslist", "value": "btn-primary", "match_type": "contains"}
  ]
}

{
  "criteria": [
    {"attribute": "title", "value": "Save"},
    {"attribute": "title", "value": "Submit"},
    {"attribute": "title", "value": "OK"}
  ],
  "matchAll": false
}
```

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

### Debug AXorcist Commands

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

Examples for running the AXorcist CLI with debug flags or enabling debug logging within a command configuration.

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

```json
{
  "command": "query",
  "debugLogging": true
}
```

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

### Install AXorcist via Swift Package Manager

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

Add the AXorcist dependency to your Swift project's Package.swift file.

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

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

### AXPermissionHelpers: Managing Accessibility Permissions

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

Provides examples of using AXPermissionHelpers for asynchronous accessibility permission management. It covers checking current permissions, requesting them, and monitoring changes using AsyncStream.

```swift
// Check current status
let hasPermissions = AXPermissionHelpers.hasAccessibilityPermissions()

// Request permissions asynchronously
let granted = await AXPermissionHelpers.requestPermissions()

// Monitor permission changes
for await hasPermissions in AXPermissionHelpers.permissionChanges() {
    if hasPermissions {
        print("Permissions granted!")
        // Enable accessibility features
    } else {
        print("Permissions revoked!")
        // Disable accessibility features
    }
}
```

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

### Get Element at Point

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

Finds an accessibility element at specific screen coordinates and retrieves its attributes.

```APIDOC
## Get Element at Point

### Description
Find an element at specific screen coordinates and retrieve its attributes.

### Method
POST

### Endpoint
/api/getElementAtPoint

### Parameters
#### Request Body
- **command** (string) - Required - Must be "getElementAtPoint"
- **xCoordinate** (integer) - Required - The X-coordinate on the screen.
- **yCoordinate** (integer) - Required - The Y-coordinate on the screen.
- **attributes** (array of strings) - Optional - List of accessibility attributes to retrieve (e.g., ["AXRole", "AXTitle"])

### Request Example
```json
{
  "command": "getElementAtPoint",
  "xCoordinate": 500,
  "yCoordinate": 300,
  "attributes": ["AXRole", "AXTitle"]
}
```

### Response
#### Success Response (200)
- **element** (object) - The element found at the specified point with requested attributes.
```

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

### Get Focused Element

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

Retrieves the currently focused accessibility element along with specified attributes.

```APIDOC
## Get Focused Element

### Description
Retrieve the currently focused element and its attributes.

### Method
POST

### Endpoint
/api/getFocusedElement

### Parameters
#### Request Body
- **command** (string) - Required - Must be "getFocusedElement"
- **application** (string) - Required - The application to query (e.g., "focused")
- **attributes** (array of strings) - Optional - List of accessibility attributes to retrieve (e.g., ["AXRole", "AXTitle", "AXValue"])

### Request Example
```json
{
  "command": "getFocusedElement",
  "application": "focused",
  "attributes": ["AXRole", "AXTitle", "AXValue"]
}
```

### Response
#### Success Response (200)
- **element** (object) - The focused element with requested attributes.
```

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

### Create Accessibility Element Instances using Swift

Source: https://context7.com/steipete/axorcist/llms.txt

Demonstrates how to instantiate Element objects from system-wide contexts, specific process IDs, running applications, and screen coordinates. These methods provide the foundation for interacting with UI elements in macOS accessibility.

```swift
import AXorcist
import AppKit

@MainActor
func elementCreationExamples() {
    let systemWide = Element.systemWide()

    if let finderElement = Element.application(for: pid_t(12345)) {
        print("Created element for PID 12345")
    }

    if let safariApp = NSRunningApplication
        .runningApplications(withBundleIdentifier: "com.apple.Safari").first,
       let safariElement = Element.application(for: safariApp) {
        print("Safari element: \(safariElement.title() ?? "Unknown")")
    }

    if let focused = Element.focusedApplication() {
        print("Focused: \(focused.title() ?? "Unknown")")
    }

    if let elementAtPoint = Element.elementAtPoint(CGPoint(x: 500, y: 300)) {
        print("Element at (500, 300): \(elementAtPoint.role() ?? "Unknown")")
    }

    if let focused = Element.focusedApplication(),
       let pid = focused.pid(),
       let element = Element.elementAtPoint(CGPoint(x: 500, y: 300), pid: pid) {
        print("Element in app at (500, 300): \(element.role() ?? "Unknown")")
    }
}
```

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

### GET /elements/focused

Source: https://context7.com/steipete/axorcist/llms.txt

Retrieves the currently focused application element and provides methods for hierarchy navigation and property access.

```APIDOC
## GET /elements/focused

### Description
Retrieves the root element for the currently focused application, allowing for property inspection and child traversal.

### Method
GET

### Endpoint
/elements/focused

### Parameters
None

### Response
#### Success Response (200)
- **title** (String) - The title of the app.
- **role** (String) - The accessibility role.
- **children** (Array) - List of child elements.

#### Response Example
{
  "title": "Safari",
  "role": "AXApplication",
  "isEnabled": true
}
```

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

### AXorcist Class - Running Accessibility Commands

Source: https://context7.com/steipete/axorcist/llms.txt

Demonstrates how to use the AXorcist shared instance to create and execute accessibility commands, such as querying UI elements. It shows the command envelope pattern and response handling for success and error cases. Requires the AXorcist framework.

```swift
import AXorcist

// Get the shared instance
let axorcist = AXorcist.shared

// Create a query command to find buttons in Safari
let queryCommand = QueryCommand(
    appIdentifier: "com.apple.Safari",
    locator: Locator(criteria: [
        Criterion(attribute: "AXRole", value: "AXButton"),
        Criterion(attribute: "AXEnabled", value: "true")
    ]),
    attributesToReturn: ["AXTitle", "AXRole", "AXEnabled"],
    maxDepthForSearch: 10
)

// Execute the command through the envelope pattern
let envelope = AXCommandEnvelope(
    commandID: "find-safari-buttons",
    command: .query(queryCommand)
)

let response = axorcist.runCommand(envelope)

// Handle the response
switch response {
case .success(let payload, let logs):
    if let data = payload?.value as? [String: Any],
       let elements = data["elements"] as? [Any] {
        print("Found \(elements.count) buttons")
    }
case .error(let message, let code, _):
    print("Error (\(code)): \(message)")
}
```

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

### AXorcist Main Class: Running Commands

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

Demonstrates how to use the singleton AXorcist instance to run accessibility commands. It shows the creation of a command envelope for querying UI elements, such as finding a button in a specific application.

```swift
import AXorcist

let axorcist = AXorcist.shared
let command = AXCommandEnvelope(
    commandID: "find-button",
    command: .query(QueryCommand(appName: "Safari", searchCriteria: [.role(.button)]))
)
let response = axorcist.runCommand(command)
```

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

### Perform UI Accessibility Actions with PerformActionCommand

Source: https://context7.com/steipete/axorcist/llms.txt

Demonstrates how to target UI elements using locators and perform accessibility actions such as clicking, setting values, or interacting with menus. It requires an app identifier and specific criteria to locate the target element.

```swift
import AXorcist

let clickCommand = PerformActionCommand(
    appIdentifier: "com.apple.Safari",
    locator: Locator(criteria: [
        Criterion(attribute: "AXTitle", value: "Back")
    ]),
    action: "AXPress"
)

let setValueCommand = PerformActionCommand(
    appIdentifier: "com.apple.TextEdit",
    locator: Locator(criteria: [
        Criterion(attribute: "AXRole", value: "AXTextArea")
    ]),
    action: "AXSetValue",
    value: AnyCodable("Hello, World!")
)

let axorcist = AXorcist.shared
let response = axorcist.runCommand(AXCommandEnvelope(commandID: "click", command: .performAction(clickCommand)))

switch response {
case .success:
    print("Action performed successfully")
case .error(let message, let code, _):
    print("Action failed (\(code)): \(message)")
}
```

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

### Automate Form Filling with Batch Commands

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

This JSON configuration demonstrates how to perform a sequence of actions, such as setting text fields and clicking a button, within a target application like Safari.

```json
{
  "command": "batch",
  "commands": [
    {
      "command": "performAction",
      "application": "Safari",
      "locator": {
        "criteria": [
          {"attribute": "AXRole", "value": "AXTextField"},
          {"attribute": "AXPlaceholderValue", "value": "Email", "match_type": "contains"}
        ]
      },
      "action": "AXSetValue",
      "actionValue": "user@example.com"
    },
    {
      "command": "performAction",
      "application": "Safari",
      "locator": {
        "criteria": [
          {"attribute": "AXRole", "value": "AXTextField"},
          {"attribute": "AXPlaceholderValue", "value": "Password", "match_type": "contains"}
        ]
      },
      "action": "AXSetValue",
      "actionValue": "secretpassword"
    },
    {
      "command": "performAction",
      "application": "Safari",
      "locator": {
        "criteria": [
          {"attribute": "AXRole", "value": "AXButton"},
          {"attribute": "AXTitle", "value": "Sign In", "match_type": "contains"}
        ]
      },
      "action": "AXPress"
    }
  ]
}
```

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

### Navigate UI Hierarchies

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

Use path-based locators to traverse the UI tree by specifying attributes and search depth for each step.

```json
{
  "path_from_root": [
    {"attribute": "role", "value": "AXWindow", "depth": 1},
    {"attribute": "identifier", "value": "main-content", "depth": 3},
    {"attribute": "role", "value": "AXButton"}
  ]
}
```

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

### Monitor UI Changes with AXObserverCenter

Source: https://context7.com/steipete/axorcist/llms.txt

Demonstrates how to subscribe to various accessibility notifications such as focus changes, value updates, and window creation. It also shows how to handle subscription results and manage observer cleanup.

```swift
import AXorcist
import ApplicationServices

@MainActor
func setupNotificationObservers() {
    guard let app = Element.focusedApplication(),
          let pid = app.pid() else { return }

    let focusResult = AXObserverCenter.shared.subscribe(
        pid: pid,
        notification: .focusedUIElementChanged
    ) { observedPid, notification, element, userInfo in
        let elem = Element(element)
        print("Focus changed to: \(elem.title() ?? "Unknown")")
        print("Role: \(elem.role() ?? "Unknown")")
    }

    let valueResult = AXObserverCenter.shared.subscribe(
        pid: pid,
        notification: .valueChanged
    ) { observedPid, notification, element, userInfo in
        let elem = Element(element)
        if let value = elem.attribute(Attribute<String>.value) {
            print("Value changed: \(value)")
        }
    }

    let windowResult = AXObserverCenter.shared.subscribe(
        pid: pid,
        notification: .windowCreated
    ) { observedPid, notification, element, userInfo in
        let elem = Element(element)
        print("Window created: \(elem.title() ?? "Unknown")")
    }

    switch focusResult {
    case .success(let token):
        print("Subscribed with token: \(token.id)")
    case .failure(let error):
        print("Subscription failed: \(error)")
    }

    let isRegistered = AXObserverCenter.shared.isKeyRegistered(
        pid: pid,
        notification: .focusedUIElementChanged
    )
    print("Focus observer registered: \(isRegistered)")
}
```

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

### POST /command

Source: https://context7.com/steipete/axorcist/llms.txt

Executes an accessibility command against a target application.

```APIDOC
## POST /command

### Description
Executes a specific accessibility command (query, performAction, getFocusedElement) on a target application.

### Method
POST

### Endpoint
/command (via stdin or file)

### Request Body
- **command** (string) - Required - The action to perform (e.g., "query", "performAction", "getFocusedElement", "isProcessTrusted")
- **application** (string) - Required - The target application bundle ID or name
- **locator** (object) - Optional - Criteria for finding UI elements
- **action** (string) - Optional - The accessibility action to perform (e.g., "AXPress", "AXSetValue")

### Request Example
{
  "command": "performAction",
  "application": "TextEdit",
  "locator": {
    "criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]
  },
  "action": "AXSetValue",
  "actionValue": "Hello from axorc!"
}

### Response
#### Success Response (200)
- **status** (string) - "success"
- **payload** (object) - The resulting data from the query or action

#### Response Example
{
  "status": "success",
  "payload": { "value": "Operation completed" }
}
```

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

### AXorcist Path Navigation

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

Explains how to navigate the UI hierarchy using path hints.

```APIDOC
## Path Navigation

### Description
Navigate through UI hierarchies by specifying a sequence of attribute-based steps.

### Method
Path Construction (Swift API or CLI JSON)

### Endpoint
N/A

### Parameters
- **`path_from_root`** (array): An array of path components.
  - **`attribute`** (string): The accessibility attribute to match.
  - **`value`** (string): The expected value for the attribute.
  - **`depth`** (integer, optional): Maximum search depth for this step (default: 3).
  - **`match_type`** (string, optional): How to match the value (default: `exact`).

### Request Example
```json
{
  "path_from_root": [
    {"attribute": "role", "value": "AXWindow", "depth": 1},
    {"attribute": "identifier", "value": "main-content", "depth": 3},
    {"attribute": "role", "value": "AXButton"}
  ]
}
```

### Response
#### Success Response (200)
- **Path**: A JSON object or Swift struct defining the navigation path.

#### Response Example
(N/A - This section describes request structure)
```

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

### Execute UI Queries with Swift API

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

Initialize the AXorcist client and perform a query to retrieve specific accessibility attributes from a target application.

```swift
import AXorcist

let axorcist = AXorcist()

let query = QueryCommand(
    appIdentifier: "com.apple.TextEdit",
    locator: AXLocator(criteria: [
        AXCriterion(attribute: "AXRole", value: "AXTextArea")
    ]),
    attributesToReturn: ["AXValue", "AXRole"]
)

let response = axorcist.runCommand(AXCommandEnvelope(
    commandID: "query-1",
    command: .query(query)
))
```

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

### Execute Query and Action Commands

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

JSON structures for performing complex queries with attribute retrieval or executing specific actions on UI elements.

```json
{
  "command": "query",
  "application": "com.apple.TextEdit",
  "locator": {
    "criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]
  },
  "attributes": ["AXValue", "AXRole", "AXTitle"],
  "maxDepthForSearch": 10
}

{
  "command": "performAction",
  "application": "Safari",
  "locator": {
    "criteria": [{"attribute": "AXTitle", "value": "Back"}]
  },
  "action": "AXPress"
}
```

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

### Execute AXorcist CLI Commands

Source: https://context7.com/steipete/axorcist/llms.txt

Demonstrates how to interact with the AXorcist CLI by piping JSON command envelopes via stdin. These commands allow for querying elements, performing actions, and checking system permissions.

```bash
echo '{"command": "query", "application": "com.apple.Safari", "locator": {"criteria": [{"attribute": "AXRole", "value": "AXButton"}, {"attribute": "AXEnabled", "value": "true"}]}, "attributes": ["AXTitle", "AXRole"]}' | axorc --stdin --pretty

echo '{"command": "performAction", "application": "Safari", "locator": {"criteria": [{"attribute": "AXTitle", "value": "Back"}]}, "action": "AXPress"}' | axorc --stdin

echo '{"command": "getFocusedElement", "application": "focused", "attributes": ["AXRole", "AXTitle", "AXValue"]}' | axorc --stdin --pretty

echo '{"command": "performAction", "application": "TextEdit", "locator": {"criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]}, "action": "AXSetValue", "actionValue": "Hello from axorc!"}' | axorc --stdin

axorc --file command.json --debug --pretty

echo '{"command": "isProcessTrusted"}' | axorc --stdin
```

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

### Execute Commands via CLI

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

Interact with UI elements by piping JSON command configurations into the axorc CLI tool.

```bash
# Find all buttons in Safari
echo '{"command": "query", "application": "com.apple.Safari", "locator": {"criteria": [{"attribute": "AXRole", "value": "AXButton"}]}}' | axorc --stdin

# Click the Back button
echo '{"command": "performAction", "application": "Safari", "locator": {"criteria": [{"attribute": "AXTitle", "value": "Back"}]}, "action": "AXPress"}' | axorc --stdin
```

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

### Execute Multi-Step Workflows with AXBatchCommand

Source: https://context7.com/steipete/axorcist/llms.txt

Shows how to bundle multiple accessibility commands into a single batch operation. This is useful for complex workflows like automated form filling where multiple sequential actions are required.

```swift
import AXorcist

let batchCommand = AXBatchCommand(commands: [
    AXBatchCommand.SubCommandEnvelope(
        commandID: "focus-email",
        command: .performAction(PerformActionCommand(
            appIdentifier: "Safari",
            locator: Locator(criteria: [
                Criterion(attribute: "AXRole", value: "AXTextField"),
                Criterion(attribute: "AXPlaceholderValue", value: "Email", matchType: .contains)
            ]),
            action: "AXPress"
        ))
    ),
    AXBatchCommand.SubCommandEnvelope(
        commandID: "set-email",
        command: .performAction(PerformActionCommand(
            appIdentifier: "Safari",
            locator: Locator(criteria: [
                Criterion(attribute: "AXRole", value: "AXTextField"),
                Criterion(attribute: "AXPlaceholderValue", value: "Email", matchType: .contains)
            ]),
            action: "AXSetValue",
            value: AnyCodable("user@example.com")
        ))
    )
])

let axorcist = AXorcist.shared
let envelope = AXCommandEnvelope(commandID: "login-workflow", command: .batch(batchCommand))
let response = axorcist.runCommand(envelope)
```

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

### Query UI Elements with Complex Criteria in Swift

Source: https://context7.com/steipete/axorcist/llms.txt

Shows how to construct QueryCommand objects to find UI elements using various matching strategies like exact, contains, and logical OR operations. It also covers hierarchical path navigation for deep element searching.

```swift
import AXorcist

let exactQuery = QueryCommand(
    appIdentifier: "com.apple.TextEdit",
    locator: Locator(criteria: [
        Criterion(attribute: "AXRole", value: "AXTextArea")
    ]),
    attributesToReturn: ["AXValue", "AXRole", "AXTitle"]
)

let containsQuery = QueryCommand(
    appIdentifier: "Safari",
    locator: Locator(
        matchAll: true,
        criteria: [
            Criterion(attribute: "AXRole", value: "AXTextField"),
            Criterion(attribute: "AXTitle", value: "email", matchType: .contains)
        ]
    ),
    maxDepthForSearch: 15
)

let orQuery = QueryCommand(
    appIdentifier: "com.apple.Safari",
    locator: Locator(
        matchAll: false,
        criteria: [
            Criterion(attribute: "AXTitle", value: "Save"),
            Criterion(attribute: "AXTitle", value: "Submit"),
            Criterion(attribute: "AXTitle", value: "OK")
        ]
    )
)

let pathQuery = QueryCommand(
    appIdentifier: "com.apple.Safari",
    locator: Locator(
        criteria: [
            Criterion(attribute: "AXRole", value: "AXButton"),
            Criterion(attribute: "AXDOMClassList", value: "submit-button", matchType: .contains)
        ],
        rootElementPathHint: [
            JSONPathHintComponent(attribute: "AXRole", value: "AXWindow", maxDepthForStep: 1),
            JSONPathHintComponent(attribute: "AXRole", value: "AXWebArea", maxDepthForStep: 5)
        ]
    ),
    attributesToReturn: ["AXTitle", "AXValue", "AXEnabled", "AXPosition", "AXSize"]
)

let axorcist = AXorcist.shared
let response = axorcist.runCommand(AXCommandEnvelope(commandID: "search", command: .query(pathQuery)))
```

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

### Element Actions - Performing UI Interactions and Setting Values

Source: https://context7.com/steipete/axorcist/llms.txt

Shows how to perform standard accessibility actions (like press, raise) and set attribute values on UI elements using the Element struct. It demonstrates modern enum-based syntax and error handling, along with convenience methods. Requires the AXorcist framework and MainActor isolation.

```swift
import AXorcist

@MainActor
func performButtonClick() {
    guard let app = Element.focusedApplication() else { return }

    do {
        // Modern enum-based action syntax
        try app.performAction(.press)
        print("Pressed element successfully")

        try app.performAction(.raise)
        print("Raised element to front")

        // Available actions: .press, .increment, .decrement, .confirm, 
        // .cancel, .showMenu, .pick, .raise, .setValue

    } catch let error as AccessibilitySystemError {
        let accessibilityError = error.axError.toAccessibilityError(context: "Pressing button")
        print("Accessibility error: \(accessibilityError)")
    } catch {
        print("Unexpected error: \(error)")
    }

    // Convenience methods that return Bool
    let didPress = app.press()      // Returns true if successful
    let didShowMenu = app.showMenu() // Returns true if successful
    let didPick = app.pick()        // Returns true if successful

    // Set attribute values
    let success = app.setValue("New text", forAttribute: "AXValue")
    if success {
        print("Value set successfully")
    }
}
```

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

### PerformActionCommand - Executing UI Actions

Source: https://context7.com/steipete/axorcist/llms.txt

This section explains how to use PerformActionCommand to execute individual UI accessibility actions like clicks, setting values, and menu interactions on target elements.

```APIDOC
## PerformActionCommand - Executing UI Actions

### Description
Perform accessibility actions on target elements including clicks, value setting, and menu interactions.

### Method
POST (Conceptual - executed via `AXorcist.shared.runCommand`)

### Endpoint
`/runCommand` (Conceptual endpoint for executing commands)

### Parameters
#### Request Body (AXCommandEnvelope)
- **commandID** (string) - Required - A unique identifier for the command.
- **command** (PerformActionCommand) - Required - The action to perform.
  - **appIdentifier** (string) - Required - The bundle identifier of the target application.
  - **locator** (Locator) - Required - Defines the target element.
    - **criteria** (array of Criterion) - Required - A list of criteria to find the element.
      - **attribute** (string) - Required - The accessibility attribute to check (e.g., "AXTitle", "AXRole").
      - **value** (string) - Required - The value to match for the attribute.
      - **matchType** (string, optional) - The type of match (e.g., "exact", "contains"). Defaults to "exact".
  - **action** (string) - Required - The accessibility action to perform (e.g., "AXPress", "AXSetValue", "AXIncrement", "AXShowMenu").
  - **value** (AnyCodable, optional) - Required if action is "AXSetValue" - The value to set for the element.

### Request Example
```json
{
  "commandID": "click-back-button",
  "command": {
    "performAction": {
      "appIdentifier": "com.apple.Safari",
      "locator": {
        "criteria": [
          {
            "attribute": "AXTitle",
            "value": "Back"
          }
        ]
      },
      "action": "AXPress"
    }
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - "success"

#### Error Response
- **status** (string) - "error"
- **message** (string) - Description of the error.
- **code** (integer) - Error code.

#### Response Example
```json
{
  "status": "success"
}
```
```

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

### Handle AXorcist Responses in Swift

Source: https://context7.com/steipete/axorcist/llms.txt

Shows how to execute commands using the Swift API and handle results using pattern matching. It covers processing success payloads and managing specific error codes like permission issues or element lookup failures.

```swift
import AXorcist

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

let response = axorcist.runCommand(command)

switch response {
case .success(let payload, let logs):
    print("Status: \(response.status)")
    if let data = payload?.value { print("Payload: \(data)") }
    if let debugLogs = logs { print("Logs: \(debugLogs.joined(separator: "\n"))") }
case .error(let message, let code, let logs):
    print("Status: \(response.status)")
    switch code {
    case .elementNotFound: print("Element not found: \(message)")
    case .applicationNotFound: print("Application not running: \(message)")
    case .permissionDenied: print("Need accessibility permissions: \(message)")
    case .actionFailed: print("Action could not be performed: \(message)")
    case .actionNotSupported: print("Element doesn't support this action: \(message)")
    case .timeout: print("Operation timed out: \(message)")
    case .invalidCommand, .invalidParameter: print("Invalid input: \(message)")
    default: print("Error (\(code.rawValue)): \(message)")
    }
}
```

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

### QueryCommand - Finding UI Elements

Source: https://context7.com/steipete/axorcist/llms.txt

Search for UI elements using multiple criteria with flexible matching strategies including exact, contains, regex, prefix, and suffix matching.

```APIDOC
## QueryCommand - Finding UI Elements

### Description
Search for UI elements using multiple criteria with flexible matching strategies including exact, contains, regex, prefix, and suffix matching.

### Method
`AXorcist.shared.runCommand(AXCommandEnvelope)`

### Endpoint
N/A (This is a command execution, not a REST endpoint)

### Parameters
- `appIdentifier` (String) - Required - The identifier of the application to search within.
- `locator` (Locator) - Required - Defines the search criteria and matching strategy.
  - `matchAll` (Bool) - Optional - If true, all criteria must match. If false, at least one criterion must match (OR logic).
  - `criteria` ([Criterion]) - Required - An array of search criteria.
    - `attribute` (String) - Required - The UI element attribute to match (e.g., "AXRole", "AXTitle").
    - `value` (String) - Required - The value to match against the attribute.
    - `matchType` (MatchType) - Optional - The type of matching to perform (e.g., `.exact`, `.contains`, `.regex`). Defaults to `.exact`.
  - `rootElementPathHint` ([JSONPathHintComponent]) - Optional - Path hints for hierarchical search.
- `attributesToReturn` ([String]) - Optional - A list of attributes to retrieve for matching elements.
- `maxDepthForSearch` (Int) - Optional - Maximum depth to search in the UI hierarchy.

### Request Example
```swift
import AXorcist

// Basic query with exact matching
let exactQuery = QueryCommand(
    appIdentifier: "com.apple.TextEdit",
    locator: Locator(criteria: [
        Criterion(attribute: "AXRole", value: "AXTextArea")
    ]),
    attributesToReturn: ["AXValue", "AXRole", "AXTitle"]
)

// Query with contains matching
let containsQuery = QueryCommand(
    appIdentifier: "Safari",
    locator: Locator(
        matchAll: true,
        criteria: [
            Criterion(attribute: "AXRole", value: "AXTextField"),
            Criterion(attribute: "AXTitle", value: "email", matchType: .contains)
        ]
    ),
    maxDepthForSearch: 15
)

// Query with OR logic (matchAll: false)
let orQuery = QueryCommand(
    appIdentifier: "com.apple.Safari",
    locator: Locator(
        matchAll: false,
        criteria: [
            Criterion(attribute: "AXTitle", value: "Save"),
            Criterion(attribute: "AXTitle", value: "Submit"),
            Criterion(attribute: "AXTitle", value: "OK")
        ]
    )
)

// Query with path navigation for hierarchical search
let pathQuery = QueryCommand(
    appIdentifier: "com.apple.Safari",
    locator: Locator(
        criteria: [
            Criterion(attribute: "AXRole", value: "AXButton"),
            Criterion(attribute: "AXDOMClassList", value: "submit-button", matchType: .contains)
        ],
        rootElementPathHint: [
            JSONPathHintComponent(attribute: "AXRole", value: "AXWindow", maxDepthForStep: 1),
            JSONPathHintComponent(attribute: "AXRole", value: "AXWebArea", maxDepthForStep: 5)
        ]
    ),
    attributesToReturn: ["AXTitle", "AXValue", "AXEnabled", "AXPosition", "AXSize"]
)

// Execute queries
let axorcist = AXorcist.shared
let response = axorcist.runCommand(AXCommandEnvelope(commandID: "search", command: .query(pathQuery)))
```

### Response
- Returns an `AXResponse` object containing the results of the query.

### Response Example
```json
{
  "commandID": "search",
  "status": "success",
  "elements": [
    // Array of found elements with requested attributes
  ]
}
```
```

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

### POST /commands/query

Source: https://context7.com/steipete/axorcist/llms.txt

Executes a query command to locate specific UI elements within an application using criteria and attribute filtering.

```APIDOC
## POST /commands/query

### Description
Executes a structured query command to find UI elements (e.g., buttons) within a target application based on defined criteria.

### Method
POST

### Endpoint
/commands/query

### Parameters
#### Request Body
- **appIdentifier** (String) - Required - The bundle identifier of the target application.
- **locator** (Object) - Required - Criteria for matching elements.
- **attributesToReturn** (Array) - Optional - List of accessibility attributes to retrieve.
- **maxDepthForSearch** (Int) - Optional - Maximum hierarchy depth for the search.

### Request Example
{
  "commandID": "find-safari-buttons",
  "command": {
    "appIdentifier": "com.apple.Safari",
    "locator": { "criteria": [{"attribute": "AXRole", "value": "AXButton"}] }
  }
}

### Response
#### Success Response (200)
- **payload** (Object) - The returned element data.
- **logs** (Array) - Execution logs.

#### Response Example
{
  "status": "success",
  "payload": {"elements": [...]}
}
```

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

### Element Wrapper: Accessing Properties and Performing Actions

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

Illustrates the usage of the Element struct, a Swift wrapper for AXUIElement. It shows how to create an Element instance, access its properties like title and role, and perform actions such as pressing a button or setting a value.

```swift
// Create element wrapper
let element = Element(axUIElement)

// Access properties safely
let title = element.title
let role = element.role
let isEnabled = element.isEnabled

// Perform actions
try element.performAction(.press)
try element.setValue("Hello World")

// Navigate hierarchy
let children = element.children()
let parent = element.parent()
```