wayllm

wayllm is an agent-first Wayland observation CLI for:

• discovering outputs, windows, and layer-shell surfaces
• resolving whether a target is actually capturable
• taking deterministic screenshots from scripts, smoke tests, and LLM agents

Install

cargo install wayllm

Build from source:

git clone https://github.com/OneNoted/wayllm
cd wayllm
cargo install --path crates/wayllm

Quick Start

wayllm targets
wayllm resolve --window focused
wayllm capture --out /tmp/shot.png --edge top:5%

Default stdout is JSON. Use --format human for compact terminal output.

Why resolve Exists

On Wayland, a compositor may let you discover a target without exposing enough geometry to capture it safely. resolve gives the caller:

• whether the target is capturable
• the reason when it is not
• the exact selector to retry with
• a recommended next command

Selector Grammar

--output focused|<name>
--window focused|id=<backend-id>|app_id=<id>|title~=<substring>
--layer id=<backend-id>|namespace=<name>
--rect '<x>,<y> <width>x<height>'
--rect-relative '<x>,<y> <width>x<height>'
--edge 'top:5%' | 'bottom:20%' | 'left:0.3' | 'right:25%'

Commands

wayllm targets
wayllm targets --kind window
wayllm resolve --window app_id=kitty
wayllm capture --out /tmp/top.png --edge top:5%

License

MIT. See LICENSE.