> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ericclemmons/agent-native/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
agent-native get text <target> [options]
```

### Arguments

<ParamField path="target" type="string" required>
  Target element: `@ref` (from snapshot) or app name
</ParamField>

### Options

<ParamField query="--role" type="string">
  Filter by accessibility role
</ParamField>

<ParamField query="--title" type="string">
  Filter by title
</ParamField>

<ParamField query="--label" type="string">
  Filter by label
</ParamField>

<ParamField query="--index" type="integer" default="0">
  Which matching element to read (0-indexed)
</ParamField>

<ParamField query="--json" type="boolean">
  Output as JSON
</ParamField>

### Examples

<CodeGroup>
  ```bash Get by reference theme={null}
  agent-native get text @n15
  ```

  ```bash Get by filter theme={null}
  agent-native get text Safari --role StaticText --label "Status"
  ```

  ```bash JSON output theme={null}
  agent-native get text @n8 --json
  ```
</CodeGroup>

### Output

```bash theme={null}
Operation completed successfully
```

<Info>
  The command reads from `AXValue`, `AXTitle`, or `AXDescription` attributes in that order, returning the first available value.
</Info>

***

## get value

Get the current value of an input element.

```bash theme={null}
agent-native get value <target> [options]
```

### Arguments and options

Identical to `get text`.

### Examples

<CodeGroup>
  ```bash Get text field value theme={null}
  agent-native get value @n10
  ```

  ```bash Get slider value theme={null}
  agent-native get value Settings --role Slider --label "Volume"
  ```

  ```bash Get checkbox value theme={null}
  agent-native get value @n25
  ```
</CodeGroup>

### Output

```bash theme={null}
user@example.com
```

For checkboxes and numeric controls:

```bash theme={null}
1
```

<Note>
  Checkboxes return `0` (unchecked) or `1` (checked). Sliders and steppers return their numeric value.
</Note>

***

## get attr

Retrieve a specific accessibility attribute.

```bash theme={null}
agent-native get attr <target> <attribute> [options]
```

### Arguments

<ParamField path="target" type="string" required>
  Target element: `@ref` or app name
</ParamField>

<ParamField path="attribute" type="string" required>
  Attribute name (e.g., `AXRole`, `AXEnabled`, `AXFrame`, `AXPosition`)
</ParamField>

### Options

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

### Examples

<CodeGroup>
  ```bash Get role theme={null}
  agent-native get attr @n20 AXRole
  ```

  ```bash Get enabled state theme={null}
  agent-native get attr @n15 AXEnabled
  ```

  ```bash Get position theme={null}
  agent-native get attr Safari --role Button --title "Back" AXPosition
  ```

  ```bash Get description theme={null}
  agent-native get attr @n5 AXDescription
  ```
</CodeGroup>

### Output

```bash theme={null}
AXButton
```

For position/size:

```bash theme={null}
{100, 200}
```

For arrays:

```bash theme={null}
[5 items]
```

### Common attributes

<Tabs>
  <Tab title="Identity">
    * `AXRole` - Element type
    * `AXRoleDescription` - Human-readable role
    * `AXTitle` - Element title
    * `AXDescription` - Accessibility description
    * `AXIdentifier` - Unique identifier
  </Tab>

  <Tab title="State">
    * `AXEnabled` - Whether element is enabled
    * `AXFocused` - Whether element has focus
    * `AXValue` - Current value
    * `AXSelected` - Whether element is selected
    * `AXExpanded` - Whether element is expanded
  </Tab>

  <Tab title="Layout">
    * `AXPosition` - Screen coordinates
    * `AXSize` - Width and height
    * `AXFrame` - Position and size combined
    * `AXParent` - Parent element
    * `AXChildren` - Child elements
  </Tab>

  <Tab title="Content">
    * `AXLabel` - Accessibility label
    * `AXHelp` - Help text
    * `AXPlaceholderValue` - Placeholder text
    * `AXMaxValue` - Maximum value
    * `AXMinValue` - Minimum value
  </Tab>
</Tabs>

<Tip>
  Use `inspect` to see all available attributes for an element.
</Tip>

***

## get title

Get the title of the frontmost window of an application.

```bash theme={null}
agent-native get title <app> [options]
```

### Arguments

<ParamField path="app" type="string" required>
  Application name or bundle identifier
</ParamField>

### Options

<ParamField query="--json" type="boolean">
  Output as JSON
</ParamField>

### Examples

<CodeGroup>
  ```bash Get Safari window title theme={null}
  agent-native get title Safari
  ```

  ```bash Get Terminal title theme={null}
  agent-native get title Terminal
  ```

  ```bash JSON output theme={null}
  agent-native get title "Google Chrome" --json
  ```
</CodeGroup>

### Output

```bash theme={null}
Welcome to Safari
```

***

## is enabled

Check if an element is enabled (interactive).

```bash theme={null}
agent-native is enabled <target> [options]
```

### Arguments

<ParamField path="target" type="string" required>
  Target element: `@ref` or app name
</ParamField>

### Options

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

### Examples

<CodeGroup>
  ```bash Check by reference theme={null}
  agent-native is enabled @n12
  ```

  ```bash Check button theme={null}
  agent-native is enabled Safari --role Button --title "Submit"
  ```

  ```bash JSON output theme={null}
  agent-native is enabled @n20 --json
  ```
</CodeGroup>

### Output

```bash theme={null}
true
```

or

```bash theme={null}
false
```

<Info>
  Use this in scripts to conditionally perform actions based on element availability.
</Info>

***

## is focused

Check if an element currently has keyboard focus.

```bash theme={null}
agent-native is focused <target> [options]
```

### Arguments and options

Identical to `is enabled`.

### Examples

<CodeGroup>
  ```bash Check by reference theme={null}
  agent-native is focused @n8
  ```

  ```bash Check text field theme={null}
  agent-native is focused Safari --role TextField --label "Search"
  ```
</CodeGroup>

### Output

```bash theme={null}
true
```

or

```bash theme={null}
false
```

## Workflow examples

### Verify form submission

```bash theme={null}
#!/bin/bash

# Fill form
agent-native fill @n5 "user@example.com"
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

```bash theme={null}
#!/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

```bash theme={null}
#!/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

```bash theme={null}
#!/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

```bash theme={null}
#!/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
```