State commands

Read element properties, values, and attributes from macOS applications

State commands extract information from UI elements without modifying them.

get text

Extract text content from an element.

agent-native get text <target> [options]

Arguments

target · string · required

Target element: @ref (from snapshot) or app name

Options

--role · string

Filter by accessibility role

--title · string

Filter by title

--label · string

Filter by label

--index · integer · default: "0"

Which matching element to read (0-indexed)

--json · boolean

Output as JSON

Examples

Get by reference

agent-native get text @n15

Output

Operation completed successfully

The command reads from AXValue, AXTitle, or AXDescription attributes in that order, returning the first available value.

---

get value

Get the current value of an input element.

agent-native get value <target> [options]

Arguments and options

Identical to get text.

Examples

Get text field value

agent-native get value @n10

Output

[e-mail]

For checkboxes and numeric controls:

1

Checkboxes return 0 (unchecked) or 1 (checked). Sliders and steppers return their numeric value.

---

get attr

Retrieve a specific accessibility attribute.

agent-native get attr <target> <attribute> [options]

Arguments

target · string · required

Target element: @ref or app name

attribute · string · required

Attribute name (e.g., AXRole, AXEnabled, AXFrame, AXPosition)

Options

Standard filter options: --role, --title, --label, --index, --json

Examples

Get role

agent-native get attr @n20 AXRole

Output

AXButton

For position/size:

{100, 200}

For arrays:

[5 items]

Common attributes

Identity

• AXRole - Element type
• AXRoleDescription - Human-readable role
• AXTitle - Element title
• AXDescription - Accessibility description
• AXIdentifier - Unique identifier

State

• AXEnabled - Whether element is enabled
• AXFocused - Whether element has focus
• AXValue - Current value
• AXSelected - Whether element is selected
• AXExpanded - Whether element is expanded

Layout

• AXPosition - Screen coordinates
• AXSize - Width and height
• AXFrame - Position and size combined
• AXParent - Parent element
• AXChildren - Child elements

Content

• AXLabel - Accessibility label
• AXHelp - Help text
• AXPlaceholderValue - Placeholder text
• AXMaxValue - Maximum value
• AXMinValue - Minimum value

Use inspect to see all available attributes for an element.

---

get title

Get the title of the frontmost window of an application.

agent-native get title <app> [options]

Arguments

app · string · required

Application name or bundle identifier

Options

--json · boolean

Output as JSON

Examples

Get Safari window

agent-native get title Safari

Output

Welcome to Safari

---

is enabled

Check if an element is enabled (interactive).

agent-native is enabled <target> [options]

Arguments

target · string · required

Target element: @ref or app name

Options

Standard filter options: --role, --title, --label, --index, --json

Examples

Check by reference

agent-native is enabled @n12

Output

true

or

false

Use this in scripts to conditionally perform actions based on element availability.

---

is focused

Check if an element currently has keyboard focus.

agent-native is focused <target> [options]

Arguments and options

Identical to is enabled.

Examples

Check by reference

agent-native is focused @n8

Output

true

or

false

Workflow examples

Verify form submission

#!/bin/bash

# Fill form
agent-native fill @n5 "[e-mail]"
agent-native fill @n6 "password123"

# Check if submit button is enabled
if [ "$(agent-native is enabled @n7)" = "true" ]; then
  agent-native click @n7
  echo "Form submitted"
else
  echo "Submit button is disabled"
  exit 1
fi

# Wait and verify
agent-native wait MyApp --role StaticText --label "Success" --timeout 5
MESSAGE=$(agent-native get text MyApp --role StaticText --label "Success")
echo "Result: $MESSAGE"

Monitor dynamic content

#!/bin/bash

# Check current value
OLD_VALUE=$(agent-native get value @n10)
echo "Current value: $OLD_VALUE"

# Trigger update
agent-native click @n5

# Wait for change
while true; do
  NEW_VALUE=$(agent-native get value @n10)
  if [ "$NEW_VALUE" != "$OLD_VALUE" ]; then
    echo "Value changed to: $NEW_VALUE"
    break
  fi
  sleep 0.5
done

Extract structured data

#!/bin/bash

# Get window title
TITLE=$(agent-native get title MyApp)

# Get multiple field values
NAME=$(agent-native get value @n5)
EMAIL=$(agent-native get value @n6)
STATUS=$(agent-native get text @n10)

# Check states
ENABLED=$(agent-native is enabled @n15)
FOCUSED=$(agent-native is focused @n6)

# Output as JSON-like structure
cat <<EOF
{
  "window": "$TITLE",
  "name": "$NAME",
  "email": "$EMAIL",
  "status": "$STATUS",
  "saveEnabled": $ENABLED,
  "emailFocused": $FOCUSED
}
EOF

Validation checks

#!/bin/bash

# Take snapshot
agent-native snapshot MyApp --interactive > snapshot.txt

# Verify required elements exist
if ! grep -q "Button \"Submit\"" snapshot.txt; then
  echo "Error: Submit button not found"
  exit 1
fi

# Check element states
if [ "$(agent-native is enabled @n10)" = "false" ]; then
  echo "Warning: Next button is disabled"
fi

# Verify values
EMAIL=$(agent-native get value @n5)
if [[ ! "$EMAIL" =~ @.+\. ]]; then
  echo "Error: Invalid email format: $EMAIL"
  exit 1
fi

echo "All validation checks passed"

Compare states

#!/bin/bash

# Capture before state
agent-native get value @n5 > before.txt
agent-native get text @n10 >> before.txt
agent-native is enabled @n15 >> before.txt

# Perform action
agent-native click @n8
sleep 1

# Capture after state
agent-native get value @n5 > after.txt
agent-native get text @n10 >> after.txt
agent-native is enabled @n15 >> after.txt

# Compare
if diff before.txt after.txt > /dev/null; then
  echo "No state changes detected"
else
  echo "State changes:"
  diff before.txt after.txt
fi