Linux

Overview

On Linux, CUP uses the AT-SPI2 (Assistive Technology Service Provider Interface) framework via PyGObject (Python) or gdbus + xdotool (TypeScript).

Requirements

AT-SPI2 enabled (default on most GNOME/KDE desktops)
Python: python3-gi and gir1.2-atspi-2.0
TypeScript: gdbus and xdotool (system packages)

AT-SPI2 must be enabled. On most desktop environments it's on by default. If not, set the environment variable ATSPI_ENABLED=1.

Setup

Install system dependencies, then CUP. See Installation for full details.

# Ubuntu/Debian — system packages
sudo apt install python3-gi gir1.2-atspi-2.0  # Python
sudo apt install dbus xdotool                  # TypeScript

How it works

The Linux adapter connects to AT-SPI2 via D-Bus, traversing the accessibility tree exposed by applications. GTK and Qt apps generally have good AT-SPI2 support.

Role mapping

AT-SPI2 Role	CUP Role
`ROLE_PUSH_BUTTON`	`button`
`ROLE_CHECK_BOX`	`checkbox`
`ROLE_COMBO_BOX`	`combobox`
`ROLE_ENTRY`	`textbox`
`ROLE_LINK`	`link`
`ROLE_IMAGE`	`img`
`ROLE_LIST`	`list`
`ROLE_LIST_ITEM`	`listitem`
`ROLE_MENU`	`menu`
`ROLE_MENU_ITEM`	`menuitem`
`ROLE_PROGRESS_BAR`	`progressbar`
`ROLE_RADIO_BUTTON`	`radio`
`ROLE_SLIDER`	`slider`
`ROLE_TABLE`	`table`
`ROLE_LABEL`	`text`
`ROLE_FRAME`	`window`

Action mapping

CUP Action	Linux (AT-SPI2) Implementation
`click`	`DoAction("click"/"press"/"activate")`
`type`	`EditableText.SetTextContents`, fallback to `xdotool type`
`setvalue`	`Value.SetCurrentValue`
`toggle`	`DoAction("toggle"/"click")`
`expand`	`DoAction("expand or activate")`
`collapse`	`DoAction("collapse")`
`select`	`Selection.SelectChild` / `DoAction("click")`
`scroll`	`xdotool` mouse wheel at element center

Platform-specific properties

For the full platform-specific property schema, see Node Structure.

Troubleshooting

Empty tree

Ensure AT-SPI2 is running:

dbus-send --session --print-reply --dest=org.a11y.Bus /org/a11y/bus org.a11y.Bus.GetAddress

Electron apps

Electron apps need --force-renderer-accessibility flag for full AT-SPI2 support.

On this page