Read a specific property from an element identified by its ref ID. Properties include text content, value, title, bounds, role, and state information.
Usage
agent-desktop get <REF> --property <PROPERTY>
Parameters
Element reference ID from a previous snapshot (e.g., @e1, @e2, @e14).
Property to read from the element.Options:
text - Text content or valuevalue - Current value (for inputs, sliders, etc.)title - Accessible name or labelbounds - Pixel bounds (x, y, width, height)role - Accessibility rolestates - Array of state strings
Response
Name of the property that was requested.
Reference ID that was queried.
Value of the requested property. Type varies by property:
text, value, title, role: string or nullbounds: object with x, y, width, height or nullstates: array of strings
Examples
Get text from a button
agent-desktop get @e3 --property title
{
"version": "1.0",
"ok": true,
"command": "get",
"data": {
"property": "title",
"ref": "@e3",
"value": "Save"
}
}
Get value from a text field
agent-desktop get @e7 --property value
{
"version": "1.0",
"ok": true,
"command": "get",
"data": {
"property": "value",
"ref": "@e7",
"value": "quarterly report.pdf"
}
}
Get role
agent-desktop get @e12 --property role
{
"version": "1.0",
"ok": true,
"command": "get",
"data": {
"property": "role",
"ref": "@e12",
"value": "checkbox"
}
}
Get bounds
agent-desktop get @e5 --property bounds
{
"version": "1.0",
"ok": true,
"command": "get",
"data": {
"property": "bounds",
"ref": "@e5",
"value": {
"x": 150.0,
"y": 300.0,
"width": 200.0,
"height": 24.0
}
}
}
Get states
agent-desktop get @e9 --property states
{
"version": "1.0",
"ok": true,
"command": "get",
"data": {
"property": "states",
"ref": "@e9",
"value": ["enabled", "checked"]
}
}
Get text (default property)
{
"version": "1.0",
"ok": true,
"command": "get",
"data": {
"property": "text",
"ref": "@e2",
"value": "Search"
}
}
Empty value
agent-desktop get @e4 --property value
{
"version": "1.0",
"ok": true,
"command": "get",
"data": {
"property": "value",
"ref": "@e4",
"value": null
}
}
Error Cases
Stale ref
{
"version": "1.0",
"ok": false,
"command": "get",
"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": "get",
"error": {
"code": "ELEMENT_NOT_FOUND",
"message": "Element @e99 could not be resolved",
"suggestion": "Run 'snapshot' to get fresh refs"
}
}
{
"version": "1.0",
"ok": false,
"command": "get",
"error": {
"code": "INVALID_ARGS",
"message": "Invalid ref format: 'e3' (expected '@e3')"
}
}
Notes
- The ref must be from the last snapshot. Refs become stale after a new snapshot is taken.
- The command uses optimistic re-identification to verify the element still exists with matching (pid, role, name, bounds_hash).
- For
text and value properties, the command attempts to fetch the live value from the accessibility API. If unavailable, it falls back to the cached value from the snapshot.
- For other properties (
title, bounds, role, states), values are read from the cached RefMap (not re-queried from the OS).
- To ensure fresh state information, run
snapshot before calling get.
- The
bounds property returns null if bounds were not included in the original snapshot (requires --include-bounds flag).
See Also
- is - Check boolean element states
- snapshot - Capture the accessibility tree
- find - Search for elements
