Skip to main content

​
Overview

Expands a collapsible element such as a disclosure triangle, tree item, or accordion section. This reveals child elements that were previously hidden.

​
Syntax

agent-desktop expand <ref>

​
Parameters

​
ref
string
required
Element reference from snapshot (must support expand/collapse)

​
Response

{
  "version": "1.0",
  "ok": true,
  "command": "expand",
  "data": {
    "action": "expand",
    "ref_id": "@e15",
    "post_state": {
      "role": "group",
      "states": ["enabled", "expanded"]
    }
  }
}

​
Response Fields

​
action
string
The action performed (expand)
​
ref_id
string
The element reference that was expanded
​
post_state
object
Element state after expansion
  • role (string): Element role
  • states (string[]): Includes “expanded”

​
AX-First Strategy

The expand command:
  1. Checks if already expanded via kAXValueAttribute or states
  2. If collapsed, performs kAXPressAction
  3. Tries clicking disclosure triangle if present
  4. Verifies state changed to expanded

​
Usage Examples

​
Expand Folder in Finder

agent-desktop snapshot --app Finder -i
agent-desktop find --role "disclosure triangle" --name "Documents"
agent-desktop expand @e8
agent-desktop wait 200
agent-desktop snapshot -i  # See expanded children

​
Expand Tree Item

agent-desktop snapshot --app Xcode -i
agent-desktop find --role row --name "MyProject"
agent-desktop expand @e5

​
Expand Disclosure Section

agent-desktop snapshot --app "System Settings" -i
agent-desktop find --role group --name "Advanced"
agent-desktop expand @e12

​
Expand Nested Hierarchy

# Expand parent
agent-desktop expand @e5
agent-desktop wait 200
agent-desktop snapshot -i

# Expand child
agent-desktop expand @e8
agent-desktop wait 200
agent-desktop snapshot -i

# Expand grandchild
agent-desktop expand @e12

​
Supported Element Types

RoleExpand Behavior
disclosure triangleReveals child elements
row (with disclosure)Expands tree row
groupExpands collapsible group
outlineExpands outline row
button (disclosure)Opens section

​
State Changes

After expansion:
  • Element state includes "expanded"
  • Child elements become visible in accessibility tree
  • Disclosure triangle icon changes (▶ → ▼)
  • Subsequent snapshot shows newly visible children

​
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 cannot be expandedAlready expanded or not expandable
ACTION_NOT_SUPPORTEDElement type doesn’t support expandWrong element type

​
Verifying Expansion

# Expand element
agent-desktop expand @e15

# Verify expanded state
agent-desktop is @e15 expanded
# Returns: {"ok": true, "data": true}

# Or check in snapshot
agent-desktop snapshot -i | jq '.data.tree' | grep -A5 '@e15'

​
Common Use Cases

  • File Navigation: Expand folders in Finder
  • Tree Views: Expand hierarchy in IDEs and file browsers
  • Settings: Reveal advanced options
  • Outlines: Expand outline sections
  • Sidebars: Open sidebar categories

​
Expand + Snapshot Pattern

# Common pattern: expand and capture new children
agent-desktop expand @e8
agent-desktop wait 200  # Allow animation to complete
agent-desktop snapshot -i

# Now children are visible with refs
agent-desktop click @e12  # Interact with child

​
Idempotency

Expand is typically idempotent: 
# Expanding an already-expanded element succeeds without error
agent-desktop expand @e5
agent-desktop expand @e5  # No-op if already expanded
Some implementations may return success immediately if already expanded.

​
Expand vs Collapse

CommandBehaviorIcon Change
expandReveals children▶ → ▼
collapseHides children▼ → ▶

​
Notes

  • Always snapshot after expand to capture newly visible children
  • Some apps animate expansion; add wait after expand
  • Expanded state persists until collapsed or app restart
  • Use is @ref expanded to check state before expanding
  • Some disclosure triangles are separate clickable elements
  • Expanding large trees may be slow; consider timeout
  • Pair with collapse to manage tree visibility

Build docs developers (and LLMs) love

Get started for freeTalk to us