Skip to content
Semwright
GitHub

First commands

Inspect capabilities and targets before requesting an operation.

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
semwright doctor
semwright --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
semwright --json ui find --app org.gnome.TextEditor --role button --name Save
semwright 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
semwright 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: command reference, source references checked 7 October 2026.