Skip to main content

​
Overview

Sets an element’s value directly using the accessibility API (kAXValueAttribute). This is faster than typing and bypasses keyboard events, making it ideal for bulk text entry or filling fields that don’t require keystroke validation.

​
Syntax

agent-desktop set-value <ref> <value>

​
Parameters

​
ref
string
required
Element reference from snapshot (@e1, @e2, etc.)
​
value
string
required
Value to set (no length limit)

​
Response

{
  "version": "1.0",
  "ok": true,
  "command": "set-value",
  "data": {
    "action": "set_value",
    "ref_id": "@e7",
    "post_state": {
      "role": "textfield",
      "value": "new value here",
      "states": ["enabled", "focused"]
    }
  }
}

​
Response Fields

​
action
string
The action performed (set_value)
​
ref_id
string
The element reference that was updated
​
post_state
object
Element state after setting value
  • role (string): Element role
  • value (string): New element value
  • states (string[]): Current states

​
AX-First Strategy

The set-value command:
  1. Sets kAXValueAttribute directly via accessibility API
  2. Falls back to clear + type if AX set fails
  3. Returns updated element state

​
Usage Examples

​
Set Text Field Value

agent-desktop snapshot --app Safari -i
agent-desktop find --role textfield --name "Email"
agent-desktop set-value @e4 "[email protected]"

​
Fill Large Text Area

# Read content from file
CONTENT=$(cat document.txt)

agent-desktop snapshot --app TextEdit -i
agent-desktop set-value @e2 "$CONTENT"

​
Update Slider Value

agent-desktop snapshot --app "System Settings" -i
agent-desktop find --role slider --name "Volume"
agent-desktop set-value @e8 "75"

​
Batch Form Fill

agent-desktop batch '[
  {"command": "set-value", "args": {"ref_id": "@e3", "value": "John"}},
  {"command": "set-value", "args": {"ref_id": "@e5", "value": "Doe"}},
  {"command": "set-value", "args": {"ref_id": "@e7", "value": "[email protected]"}},
  {"command": "click", "args": {"ref_id": "@e12"}}
]'

​
Supported Element Types

RoleValue TypeExample
textfieldStringEmail, password, search
textareaStringMulti-line text
sliderNumeric string”50”, “75”
comboboxStringSelected option
incrementorNumeric stringStepper value

​
Set-Value vs Type

Aspectset-valuetype
SpeedFast (instant)Slower (char-by-char)
Keyboard eventsNot triggeredTriggered
ValidationMay be skippedTriggers on keypress
AutocompleteWon’t triggerWill trigger
Max lengthUnlimited10,000 chars
Use caseBulk data entryUser simulation
Use set-value when:
  • Filling large text areas
  • No validation on keypress
  • Speed is priority
  • Keyboard events not required
Use type when:
  • Autocomplete must trigger
  • Validation happens on keypress
  • Simulating real user typing
  • Keyboard shortcuts should fire

​
Error Cases

Error CodeCauseRecovery
ELEMENT_NOT_FOUNDRef doesn’t exist in current refmapRun snapshot to refresh
STALE_REFElement no longer matches saved refRun snapshot and use new ref
ACTION_FAILEDElement doesn’t support value attributeTry type or clear + type
ACTION_NOT_SUPPORTEDElement type doesn’t accept valuesWrong element type

​
Notes

  • Replaces existing value completely (not append)
  • No length limit (unlike type with 10K limit)
  • Does not trigger keyboard events (keydown, keyup)
  • Does not move cursor or trigger autocomplete
  • May not work with custom input components
  • Always verify value was set by reading it back if critical
  • For password fields, some apps may block AX value reads

Build docs developers (and LLMs) love

Get started for freeTalk to us