Skip to main content

​
Overview

Selects an option from a dropdown, combobox, or list by matching the option’s text value. This command searches for the specified value among the element’s children and selects it.

​
Syntax

agent-desktop select <ref> <value>

​
Parameters

​
ref
string
required
Element reference from snapshot (must be a combobox, popupbutton, or list)
​
value
string
required
Text of the option to select (exact match or partial)

​
Response

{
  "version": "1.0",
  "ok": true,
  "command": "select",
  "data": {
    "action": "select",
    "ref_id": "@e9",
    "post_state": {
      "role": "combobox",
      "value": "Option B",
      "states": ["enabled"]
    }
  }
}

​
Response Fields

​
action
string
The action performed (select)
​
ref_id
string
The element reference where selection was made
​
post_state
object
Element state after selection
  • role (string): Element role
  • value (string): Selected option text
  • states (string[]): Current states

​
AX-First Strategy

The select command uses this approach:
  1. Get element’s children/options via accessibility
  2. Find child matching the value text
  3. Click the matching option
  4. Verify selection via kAXValueAttribute

​
Usage Examples

​
Select from Dropdown

agent-desktop snapshot --app "System Settings" -i
agent-desktop find --role combobox --name "Country"
agent-desktop select @e7 "United States"

​
Select from Popup Button

agent-desktop snapshot --app Safari -i
agent-desktop find --role popupbutton --name "Zoom"
agent-desktop click @e5  # Open dropdown
agent-desktop wait 200
agent-desktop select @e5 "150%"

​
Select from List

agent-desktop snapshot --app Finder -i
agent-desktop find --role list
agent-desktop select @e8 "Documents"

​
Partial Match Selection

# Finds "Option A (recommended)" when searching for "Option A"
agent-desktop select @e9 "Option A"

​
Supported Element Types

RoleBehavior
comboboxOpens dropdown and selects option
popupbuttonOpens menu and clicks menu item
listSelects list item by value
tableSelects row by cell content

​
Selection Strategies

  1. Direct AX Selection: Sets kAXSelectedChildrenAttribute
  2. Click Option: Finds and clicks the matching option
  3. Keyboard Navigation: Uses arrow keys to navigate to option

​
Error Cases

Error CodeCauseRecovery
ELEMENT_NOT_FOUNDRef doesn’t exist or value not foundVerify option exists via snapshot
STALE_REFElement no longer matches saved refRun snapshot and use new ref
ACTION_FAILEDSelection failed or option not clickableManually click dropdown then option
INVALID_ARGSEmpty value or wrong element typeProvide valid option text

​
Select Patterns

​
Two-Step Pattern (Open + Select)

# Some dropdowns require opening first
agent-desktop click @e7      # Open dropdown
agent-desktop wait 200        # Wait for options to appear
agent-desktop snapshot -i     # Get options with refs
agent-desktop click @e12      # Click desired option

​
One-Step Pattern (Direct Select)

# Direct selection without opening
agent-desktop select @e7 "Option B"

​
Verifying Selection

# Select option
agent-desktop select @e9 "Dark Mode"

# Verify selection
agent-desktop get @e9 value

# Should return: "Dark Mode"

​
Common Use Cases

  • Form Fields: Select country, state, category
  • Settings: Choose preferences from dropdowns
  • Filters: Select filter values in search interfaces
  • Lists: Select items from file/folder lists

​
Notes

  • Value matching is typically case-sensitive
  • Partial matches are supported in most implementations
  • Some dropdowns must be opened with click first
  • Selection may trigger onChange events
  • For multi-select lists, use multiple select calls
  • Verify selection after command if critical
  • Use snapshot to see available options before selecting

Build docs developers (and LLMs) love

Get started for freeTalk to us