Skip to main content
Check a boolean state property of an element identified by its ref ID. Returns true or false based on the element’s current state from the last snapshot.

​
Usage

agent-desktop is <REF> --property <PROPERTY>

​
Parameters

​
REF
string
required
Element reference ID from a previous snapshot (e.g., @e1, @e2, @e14).
​
--property
enum
default:"visible"
State property to check.Options:
  • visible - Element is visible (not hidden)
  • enabled - Element is enabled (not disabled)
  • checked - Element is checked (checkboxes, radio buttons, toggles)
  • focused - Element has keyboard focus
  • expanded - Element is expanded (disclosure triangles, tree items, comboboxes)

​
Response

​
property
string
Name of the state property that was checked.
​
ref
string
Reference ID that was queried.
​
result
boolean
Whether the state is true or false.
​
applicable
boolean
Whether this state property is applicable to the element’s role. For example, checked is only applicable to checkboxes, radio buttons, and toggles.

​
Examples

​
Check if button is enabled

agent-desktop is @e3 --property enabled

{
  "version": "1.0",
  "ok": true,
  "command": "is",
  "data": {
    "property": "enabled",
    "ref": "@e3",
    "result": true,
    "applicable": true
  }
}

​
Check if checkbox is checked

agent-desktop is @e7 --property checked

{
  "version": "1.0",
  "ok": true,
  "command": "is",
  "data": {
    "property": "checked",
    "ref": "@e7",
    "result": true,
    "applicable": true
  }
}

​
Check if element is visible (default)

agent-desktop is @e12

{
  "version": "1.0",
  "ok": true,
  "command": "is",
  "data": {
    "property": "visible",
    "ref": "@e12",
    "result": true,
    "applicable": true
  }
}

​
Check if element is focused

agent-desktop is @e5 --property focused

{
  "version": "1.0",
  "ok": true,
  "command": "is",
  "data": {
    "property": "focused",
    "ref": "@e5",
    "result": false,
    "applicable": true
  }
}

​
Check if disclosure is expanded

agent-desktop is @e9 --property expanded

{
  "version": "1.0",
  "ok": true,
  "command": "is",
  "data": {
    "property": "expanded",
    "ref": "@e9",
    "result": true,
    "applicable": true
  }
}

​
Check inapplicable state

agent-desktop is @e3 --property checked

{
  "version": "1.0",
  "ok": true,
  "command": "is",
  "data": {
    "property": "checked",
    "ref": "@e3",
    "result": false,
    "applicable": false
  }
}

​
Error Cases

​
Stale ref

{
  "version": "1.0",
  "ok": false,
  "command": "is",
  "error": {
    "code": "STALE_REF",
    "message": "@e7 not found in current RefMap",
    "suggestion": "Run 'snapshot' to refresh, then retry with updated ref"
  }
}

​
Element not found

{
  "version": "1.0",
  "ok": false,
  "command": "is",
  "error": {
    "code": "ELEMENT_NOT_FOUND",
    "message": "Element @e99 could not be resolved",
    "suggestion": "Run 'snapshot' to get fresh refs"
  }
}

​
State Logic

​
visible

Returns false if the element has the hidden state, otherwise true.
  • Applicable to: All elements

​
enabled

Returns false if the element has the disabled state, otherwise true.
  • Applicable to: All elements

​
checked

Returns true if the element has the checked state, otherwise false.
  • Applicable to: checkbox, switch, radiobutton, togglebutton, menuitemcheckbox, menuitemradio

​
focused

Returns true if the element has the focused state, otherwise false.
  • Applicable to: All elements

​
expanded

Returns true if the element has the expanded state, otherwise false.
  • Applicable to: disclosuretriangle, treeitem, combobox, popupbutton, outline, row

​
Notes

  • States are read from the last snapshot’s RefMap, not re-queried from the accessibility API.
  • The command uses optimistic re-identification to verify the element still exists, but the state values themselves are from the cached snapshot.
  • To ensure fresh state information, run snapshot before calling is.
  • The applicable field indicates whether the property makes sense for the element’s role. For example, checked is not applicable to buttons.
  • If a state is not applicable, result will be false but applicable will also be false.

​
See Also

  • get - Read other element properties
  • snapshot - Capture fresh state information
  • find - Search for elements

Build docs developers (and LLMs) love

Get started for freeTalk to us