wl-tools

Recipe card from the charly-selkies plugin (Images — the deployable catalog).

wl-tools - Compositor-Agnostic Desktop Automation Tools

Overview

Provides CLI tools for desktop automation — Wayland-native, X11, and clipboard. Used by the wl: check verb (served out-of-process by candy/plugin-wl). Works on all wlroots compositors (sway, labwc). No daemon or special device access needed.

These are wlroots-only tools (sway/labwc). On a headless rootless KWin (KDE Plasma) pod they do NOT work and each HANGS: KWin implements none of the wlroots protocols they require — wtype needs zwp_virtual_keyboard_manager_v1, wl-clipboard needs wlr-data-control, wlr-randr needs wlr-output-management. So on KWin plugin-wl is compositor-aware (detectCompositor) and drives window management through kdotool (KWin scripting, shipped by /charly-selkies:kde-shell) instead — proven live: check-selkies-kde-pod’s wl-verb-dispatches probe passes (wl: status → compositor: kwin), and plugin-wl fail-fasts the wlroots paths (a clear “unsupported on KWin” error, never a hang). The bed authors no wl: clipboard/input/resolution probes (labwc doesn’t lean on them either), but wl: status + kdotool window automation are live and asserted. See the “What works where” table below and /charly-check:wl “Compositor Compatibility”.

Note: Screenshots are NOT included in this candy. Use wl-screenshot-grim (sway) or wl-screenshot-pixelflux (selkies) depending on your compositor.

Candy Definition

rpm:
  packages:
    - wtype
    - wlrctl
    - xdotool
    - xprop
    - xwininfo
    - wl-clipboard
    - wlr-randr
    - ydotool

No dependencies — compositor-agnostic. Works with sway, labwc, or any wlroots compositor.

Key Properties

Property	Value
Depends	None (compositor-agnostic)
Packages	`wtype`, `wlrctl`, `xdotool`, `xprop`, `xwininfo`, `wl-clipboard`, `wlr-randr`, `ydotool`
Service	None (all tools are one-shot CLI commands)
Ports	None

Tools

Wayland Tools

Tool	Protocol	Purpose
`wtype`	`zwp_virtual_keyboard_v1`	Keyboard input (type text, send keys, key combos with `-M`)
`wlrctl`	`wlr-virtual-pointer`, `wlr-foreign-toplevel-management`	Pointer control (move, click) + window management (list, focus, close, fullscreen, minimize)
`wl-copy` / `wl-paste`	`wlr-data-control`	Clipboard read/write
`wlr-randr`	`wlr-output-management`	Output resolution query and set
`ydotool`	`/dev/uinput`	Wayland-native mouse drag, scroll (press/release separation)

X11 Tools (via XWayland)

Tool	Purpose
`xdotool`	X11 window interaction (click, type, key, move, search, activate, scroll)
`xprop`	X11 window property inspection (WM_CLASS, _NET_WM_NAME, _NET_WM_PID)
`xwininfo`	X11 window geometry information

All packages are in Fedora official repos.

Included In

sway-desktop metalayer (+ wl-screenshot-grim for screenshots)
selkies-desktop metalayer (+ wl-screenshot-pixelflux for screenshots)

What works where

Tool	sway	labwc (selkies)	KWin (KDE Plasma)
wtype	YES	YES	NO — HANGS (needs `zwp_virtual_keyboard_manager_v1`, absent on KWin)
wlrctl pointer	YES	YES	NO (no host-safe pointer backend; click/mouse/scroll/drag unsupported on KWin)
wlrctl toplevel	YES	YES	via `kdotool` (plugin-wl routes window mgmt through KWin scripting)
wlr-randr	YES	YES	NO — HANGS (needs `wlr-output-management`, absent on KWin)
wl-clipboard	YES	YES	NO — HANGS (needs `wlr-data-control`, NOT implemented by KWin)
xdotool	YES (XWayland)	YES (XWayland on-demand)	YES (XWayland on-demand)
ydotool	YES	YES (needs /dev/uinput)	n/a (KWin pointer is unsupported)

On a headless rootless KWin pod the wlroots-backed wl: tools do NOT work — KWin implements none of the wlroots protocols they require, so wtype, wl-clipboard, and wlr-randr each HANG until the caller’s deadline. plugin-wl is therefore compositor-aware (detectCompositor): on KWin it routes window management through kdotool (KWin scripting) and fail-fasts the wlroots paths with a clear “unsupported on KWin” error instead of hanging. Proven live on check-selkies-kde-pod: wl: status → compositor: kwin (the wl-verb-dispatches probe passes) alongside the desktop-ready + frame-not-black stream coverage the labwc flavor also asserts.

Used In Boxes

/charly-selkies:sway-browser-vnc (via sway-desktop metalayer)
/charly-selkies:selkies-labwc (via selkies-desktop metalayer)
/charly-selkies:selkies-labwc-nvidia (via selkies-desktop metalayer)

Cross-References

/charly-check:wl — the wl: check verb that uses these tools (routes per compositor: wlroots via these tools, KWin via kdotool)
/charly-selkies:kde-shell — KDE Plasma session candy that ships kdotool (KWin window-management automation, KWin-only)
/charly-selkies:kde-selkies — KDE Plasma selkies flavor; hosts the KWin-specific deploy-scope wl check checks
/charly-selkies:wl-screenshot-grim — Screenshot candy for sway (grim)
/charly-selkies:wl-screenshot-pixelflux — Screenshot candy for selkies (pixelflux pipeline; also the KWin screenshot path)
/charly-selkies:sway-desktop — Desktop metalayer that includes this candy
/charly-selkies:selkies-desktop-layer — Desktop metalayer that includes this candy

/charly-image:layer — candy authoring reference (charly.yml schema, task verbs, service declarations)
/charly-check:check — declarative testing (check: block, charly check box, charly check live)