Skip to main content

​
Overview

Ensures a checkbox or switch is in the checked state. If already checked, does nothing. This is an idempotent operation, safe to call multiple times.

​
Syntax

agent-desktop check <ref>

​
Parameters

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

​
Response

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

​
Response Fields

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

​
AX-First Strategy

The check command:
  1. Reads current state via kAXValueAttribute
  2. If already checked (value = 1), returns success without action
  3. If unchecked (value = 0), performs kAXPressAction
  4. Verifies final state is checked

​
Usage Examples

​
Check Checkbox

agent-desktop snapshot --app "System Settings" -i
agent-desktop find --role checkbox --name "Enable Location Services"
agent-desktop check @e10

​
Idempotent Check

# Safe to run multiple times
agent-desktop check @e8
agent-desktop check @e8  # No-op if already checked
agent-desktop check @e8  # Still no-op

​
Enable Multiple Options

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

​
Conditional Check

# Check only if needed
if agent-desktop is @e8 checked | jq -r '.data' == "false"; then
  echo "Already checked, skipping"
else
  agent-desktop check @e8
fi

​
Check vs Toggle

CommandBehaviorIdempotentUse Case
checkEnsure checkedYesDesired end state
toggleFlip stateNoUnknown current state
uncheckEnsure uncheckedYesDesired end state
Use check when:
  • You need the checkbox checked
  • Idempotency is important
  • Running automation scripts repeatedly
  • Setting up known state
Use toggle when:
  • You want to flip whatever the current state is
  • Simulating user clicking

​
Supported Element Types

RoleCheck Behavior
checkboxSets to checked
switchSets to on
radiobuttonSelects option

​
State Verification

# Check the checkbox
agent-desktop check @e8

# Verify it's checked
agent-desktop is @e8 checked
# Returns: {"ok": true, "data": true}

# Check again (no-op)
agent-desktop check @e8
# Still checked, no state change

​
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_FAILEDCannot set checked stateElement may be disabled
ACTION_NOT_SUPPORTEDElement is not a checkbox/switchWrong element type

​
Common Use Cases

  • Configuration: Enable settings in preferences
  • Forms: Pre-fill form checkboxes
  • Permissions: Grant permissions
  • Feature Flags: Enable features
  • Setup Scripts: Configure applications

​
Idempotency Benefits

# This script can be run multiple times safely
agent-desktop snapshot --app "System Settings" -i
agent-desktop check @e3   # Enable FileVault
agent-desktop check @e5   # Enable Firewall
agent-desktop check @e7   # Enable Location Services
agent-desktop click @e10  # Save settings
Even if some options are already checked, the script succeeds.

​
Notes

  • Check is idempotent; safe to call when already checked
  • Returns success immediately if already in checked state
  • Pair with uncheck for state management
  • Use is @ref checked to verify state before or after
  • For radio buttons, check selects the option
  • Some apps may trigger onChange events even on no-op check
  • Always verify critical state changes with is command

Build docs developers (and LLMs) love

Get started for freeTalk to us