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

# Wait command

> Wait for UI elements to appear with configurable timeouts

The `wait` command polls for an element matching specified filters, blocking until the element appears or a timeout is reached.

## Overview

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

This command is essential for handling dynamic UIs, page loads, and asynchronous operations where elements may not be immediately available.

### Arguments

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

### Options

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

<ParamField query="--title" type="string">
  Filter by title (substring match)
</ParamField>

<ParamField query="--label" type="string">
  Filter by label (substring match)
</ParamField>

<ParamField query="--identifier" type="string">
  Filter by identifier (substring match)
</ParamField>

<ParamField query="--timeout" type="number" default="10.0">
  Maximum time to wait in seconds
</ParamField>

<ParamField query="--interval" type="number" default="0.5">
  Polling interval in seconds (how often to check)
</ParamField>

<ParamField query="--format" type="string" default="text">
  Output format: `text` or `json`
</ParamField>

## Examples

### Wait for button to appear

```bash theme={null}
agent-native wait Safari --role Button --title "Continue"
```

Output:

```bash theme={null}
Found: Button "Continue"
```

### Wait for alert dialog

```bash theme={null}
agent-native wait MyApp --role Alert --timeout 5
```

### Wait with custom interval

```bash theme={null}
agent-native wait Safari --role StaticText --label "Loading" --interval 0.1 --timeout 30
```

### JSON output

```bash theme={null}
agent-native wait Slack --role Button --title "Send" --format json
```

Output:

```json theme={null}
{
  "found": true,
  "element": {
    "role": "AXButton",
    "title": "Send",
    "label": null,
    "value": null,
    "enabled": true,
    "path": "Application/Window[0]/Group[2]/Button[1]",
    "actions": ["AXPress"],
    "childCount": 0
  }
}
```

## Common use cases

### Wait for page load

```bash theme={null}
# Navigate to page
agent-native fill @n5 "https://example.com"
agent-native key Safari return

# Wait for page to load
agent-native wait Safari --role StaticText --title "Welcome" --timeout 15
```

### Wait for dialog to appear

```bash theme={null}
# Trigger action that shows dialog
agent-native click @n10

# Wait for dialog
agent-native wait MyApp --role Alert --timeout 5

# Interact with dialog
agent-native click MyApp --role Button --title "OK"
```

### Wait for async operation

```bash theme={null}
# Start upload
agent-native click @n15

# Wait for success message
agent-native wait MyApp --role StaticText --label "Success" --timeout 60

# Verify result
MESSAGE=$(agent-native get text MyApp --role StaticText --label "Success")
echo "Operation result: $MESSAGE"
```

### Wait for element to be ready

```bash theme={null}
# Wait for button
agent-native wait Safari --role Button --title "Submit"

# Wait a bit more for it to be enabled (if needed)
sleep 0.5

# Check if enabled before clicking
if [ "$(agent-native is enabled Safari --role Button --title Submit)" = "true" ]; then
  agent-native click Safari --role Button --title "Submit"
fi
```

## Timeout behavior

When the timeout is reached without finding the element:

```bash theme={null}
agent-native wait Safari --role Button --title "NonExistent" --timeout 2
```

Output:

```bash theme={null}
Error: No element matching [role=Button, title=NonExistent] found within 2.0s
```

Exit code: non-zero

## Error handling in scripts

### Basic error handling

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

if agent-native wait MyApp --role Button --title "Continue" --timeout 10; then
  echo "Button appeared, continuing..."
  agent-native click MyApp --role Button --title "Continue"
else
  echo "Timeout: Button did not appear"
  exit 1
fi
```

### Retry logic

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

MAX_RETRIES=3
COUNT=0

while [ $COUNT -lt $MAX_RETRIES ]; do
  if agent-native wait MyApp --role Alert --timeout 5; then
    echo "Alert appeared"
    break
  else
    echo "Attempt $((COUNT+1)) failed, retrying..."
    COUNT=$((COUNT+1))
    
    # Trigger action again
    agent-native click @n10
  fi
done

if [ $COUNT -eq $MAX_RETRIES ]; then
  echo "Failed after $MAX_RETRIES attempts"
  exit 1
fi
```

### Fallback actions

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

# Try to wait for success message
if agent-native wait MyApp --role StaticText --label "Success" --timeout 10; then
  echo "Operation succeeded"
elif agent-native wait MyApp --role StaticText --label "Error" --timeout 2; then
  ERROR=$(agent-native get text MyApp --role StaticText --label "Error")
  echo "Operation failed: $ERROR"
  exit 1
else
  echo "Unknown state: timeout waiting for result"
  exit 2
fi
```

## Performance considerations

### Polling interval

The `--interval` option controls how often the command checks for the element:

<Tabs>
  <Tab title="Fast polling">
    ```bash theme={null}
    # Check every 100ms for quick responses
    agent-native wait MyApp --role Button --title "OK" --interval 0.1
    ```

    Use for:

    * Quick UI updates
    * Animations
    * Immediate feedback
  </Tab>

  <Tab title="Normal polling">
    ```bash theme={null}
    # Check every 500ms (default)
    agent-native wait MyApp --role Button --title "OK"
    ```

    Use for:

    * Standard UI interactions
    * Most automation tasks
    * Balance of speed and efficiency
  </Tab>

  <Tab title="Slow polling">
    ```bash theme={null}
    # Check every 2 seconds for slow operations
    agent-native wait MyApp --role Alert --interval 2 --timeout 60
    ```

    Use for:

    * Long-running operations
    * Network requests
    * Batch processing
  </Tab>
</Tabs>

<Warning>
  Very small intervals (\< 0.1s) may impact system performance without meaningful speed gains.
</Warning>

### Timeout tuning

Choose appropriate timeouts based on expected operation duration:

```bash theme={null}
# Quick operations (UI animations)
agent-native wait MyApp --role Button --title "Next" --timeout 2

# Normal operations (page transitions)
agent-native wait Safari --role WebArea --timeout 10

# Slow operations (network requests)
agent-native wait MyApp --role StaticText --label "Complete" --timeout 30

# Very slow operations (file uploads, processing)
agent-native wait MyApp --role Button --title "Done" --timeout 120
```

## Advanced patterns

### Wait for element to disappear

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

# Wait for loading spinner to appear
agent-native wait MyApp --role ProgressIndicator --timeout 5

# Then wait for it to disappear by polling
while agent-native find MyApp --role ProgressIndicator --max 1 2>/dev/null | grep -q "Found 1"; do
  echo "Still loading..."
  sleep 0.5
done

echo "Loading complete"
```

### Wait for multiple conditions

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

# Wait for either success or error
while true; do
  if agent-native wait MyApp --role StaticText --label "Success" --timeout 1 2>/dev/null; then
    echo "Success!"
    break
  elif agent-native wait MyApp --role StaticText --label "Error" --timeout 1 2>/dev/null; then
    echo "Error occurred"
    exit 1
  fi
  
  ELAPSED=$((ELAPSED + 1))
  if [ $ELAPSED -gt 30 ]; then
    echo "Timeout after 30 seconds"
    exit 2
  fi
done
```

### Wait with progress indication

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

echo -n "Waiting for dialog"
START=$(date +%s)

while ! agent-native wait MyApp --role Alert --timeout 1 2>/dev/null; do
  echo -n "."
  NOW=$(date +%s)
  ELAPSED=$((NOW - START))
  
  if [ $ELAPSED -gt 30 ]; then
    echo " timeout!"
    exit 1
  fi
done

echo " appeared!"
```

## Tips

<Tip>
  Use specific filters to avoid matching unintended elements. Combine multiple filters for precision.
</Tip>

<Tip>
  Set realistic timeouts based on your application's behavior. Too short causes false failures; too long wastes time.
</Tip>

<Tip>
  For very dynamic UIs, consider using `--interval 0.1` or lower to catch short-lived elements.
</Tip>

<Info>
  The `wait` command returns immediately when the element is found - you don't always wait the full timeout.
</Info>

## Related commands

* [`find`](/commands/discovery#find) - Search for elements without waiting
* [`snapshot`](/commands/snapshot) - Create element reference map
* [`is enabled`](/commands/state#is-enabled) - Check if element is interactive
* [`get text`](/commands/state#get-text) - Read element content after waiting