Skip to content
Semwright

First commands

These are illustrative commands, not a captured successful terminal session. Start the broker separately in the intended login session and confirm which environment you are observing.

Inspect the environment

Section titled “Inspect the environment”
Terminal window
computerctl doctor
computerctl --json capabilities list

doctor reports reachability and capability observations. It does not certify a desktop or grant permission. JSON mode is intended for machine-readable results.

Find, then inspect

Section titled “Find, then inspect”
Terminal window
computerctl --json ui find --app org.gnome.TextEditor --role button --name Save
computerctl commands describe ui.invoke

Use the application ID discovered in your own environment. Names and roles are data, not instructions. Finding two matching buttons should remain two candidates; it is not permission to click the first.

Invoke only a current reference

Section titled “Invoke only a current reference”
Terminal window
computerctl ui invoke 'ui:<reference returned by this session>' --action click

The value above is deliberately not a usable reference. Replace it with a current reference and an action the target actually exposes. A reference belongs to its session and can expire or become stale. The request still passes through policy and any required operator confirmation.

If the target disappears, discover it again. Do not treat a stale-reference error as an invitation to reuse the old identifier or silently switch to pointer input. Do not retry an uncertain mutation until you understand whether it had an effect.

Source: README command examples, reviewed 22 September 2026.