Skip to main content

​
Overview

Toggles the state of a checkbox or switch element, flipping it from checked to unchecked or vice versa. This is the action equivalent of clicking a toggle control.

​
Syntax

agent-desktop toggle <ref>

​
Parameters

​
ref
string
required
Element reference from snapshot (must be a checkbox or switch)

​
Response

{
  "version": "1.0",
  "ok": true,
  "command": "toggle",
  "data": {
    "action": "toggle",
    "ref_id": "@e12",
    "post_state": {
      "role": "checkbox",
      "value": "1",
      "states": ["enabled", "checked"]
    }
  }
}

​
Response Fields

​
action
string
The action performed (toggle)
​
ref_id
string
The element reference that was toggled
​
post_state
object
Element state after toggling
  • role (string): “checkbox” or “switch”
  • value (string): “0” (unchecked) or “1” (checked)
  • states (string[]): Includes “checked” if checked

​
AX-First Strategy

The toggle command:
  1. Reads current checked state via kAXValueAttribute
  2. Performs kAXPressAction to toggle
  3. Verifies state changed
  4. Falls back to click if AX toggle fails

​
Usage Examples

​
Toggle Checkbox

agent-desktop snapshot --app "System Settings" -i
agent-desktop find --role checkbox --name "Enable FileVault"
agent-desktop toggle @e8

​
Toggle Switch

agent-desktop snapshot --app Safari -i
agent-desktop find --role checkbox --name "Block pop-ups"
agent-desktop toggle @e15

​
Toggle Multiple Options

agent-desktop batch '[
  {"command": "toggle", "args": {"ref_id": "@e3"}},
  {"command": "toggle", "args": {"ref_id": "@e5"}},
  {"command": "toggle", "args": {"ref_id": "@e7"}}
]'

​
Conditional Toggle

# Check current state
STATE=$(agent-desktop is @e8 checked)

# Toggle if not checked
if [ "$STATE" = "false" ]; then
  agent-desktop toggle @e8
fi

​
Toggle vs Check/Uncheck

CommandBehaviorIdempotent
toggleFlips current stateNo
checkEnsures checkedYes
uncheckEnsures uncheckedYes
Use toggle when:
  • You want to flip the current state
  • Current state is unknown
  • Simulating user clicking the checkbox
Use check/uncheck when:
  • You need a specific end state
  • Idempotency is required
  • Running the same script multiple times

​
Supported Element Types

RoleToggle Behavior
checkboxChecked ↔ Unchecked
switchOn ↔ Off
radiobuttonSelect (not recommended, use click)

​
State Values

StateValueStates Array
Unchecked”0”["enabled"]
Checked”1”["enabled", "checked"]
Indeterminate”2”["enabled", "mixed"]

​
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_FAILEDToggle action not supportedTry click instead
ACTION_NOT_SUPPORTEDElement is not a checkbox/switchWrong element type

​
Verifying Toggle

# Check initial state
agent-desktop is @e12 checked
# Returns: false

# Toggle
agent-desktop toggle @e12

# Verify new state
agent-desktop is @e12 checked
# Returns: true

​
Common Use Cases

  • Settings: Toggle preferences on/off
  • Feature Flags: Enable/disable features
  • Filters: Toggle filter options
  • Permissions: Grant/revoke permissions
  • Form Controls: Toggle form options

​
Notes

  • Toggle is NOT idempotent; calling twice returns to original state
  • Use check/uncheck for idempotent operations
  • Some apps may use “switch” role for toggle switches
  • Radio buttons should use click instead of toggle
  • State is included in post_state for verification
  • For tristate checkboxes, toggle cycles through all three states
  • Always verify state after toggle if critical

Build docs developers (and LLMs) love

Get started for freeTalk to us