pctr

Element-based Windows UI Automation CLI for AI agents.

Instead of screenshotting and guessing pixel coordinates, pctr finds controls by their name / control type / automation id and acts on them. Window moves, DPI changes, and layout shifts don't break your script.

Built on pywinauto (UI Automation) with pyautogui / pydirectinput for raw mouse and keyboard input.

Install

pip install pctr

Windows only.

Commands

Command	What it does
`pctr windows [--filter RE]`	List top-level windows (`pid=… \| title`).
`pctr tree --title RE [--limit N]`	Dump the UIA control tree of a window.
`pctr find --title RE --name RE [--control-type T] [--auto-id ID]`	List matching elements.
`pctr click --title RE --name RE [--method auto\|invoke\|mouse] [--dbl]`	Click an element.
`pctr set --title RE --name RE --text S`	Set a field via the UIA ValuePattern.
`pctr type [--title RE --name RE] --text S [--delay 0.03] [--chunk 1]`	Type literal text.
`pctr keys --keys "{ENTER}"`	Send a global key combo.
`pctr hotkey --keys win+shift+s`	Send a modifier combo.
`pctr focus --title RE`	Bring a window to the foreground.
`pctr wait --title RE --name RE [--timeout S]`	Wait until an element exists.
`pctr shot [--title RE] --out PATH`	Screenshot the screen or a window.
`pctr size`	Print primary screen size as `WxH`.
`pctr move --x N --y N`	Move the cursor.
`pctr down / up [--button left]`	Press / release a mouse button.
`pctr hold --ms 1000 [--x N --y N]`	Press, hold, release.
`pctr drag --start x,y --end x,y [--duration S]`	Drag between two points.
`pctr keydown / keyup --key a`	Hold / release a keyboard key.
`pctr keyhold --key w --ms 1500`	Hold a key for a duration.

Common filters: --title (regex), --name (regex), --control-type (Button, Edit, Pane, MenuItem, …), --auto-id, --nth, --process.

The loop

pctr tree  --title "Notepad" --limit 60      # see what's clickable
pctr click --title "Notepad" --name "^File$"
pctr set   --title "Notepad" --name "Text Editor" --text "hello"

Notes

Prefer set (ValuePattern) over type for text fields - it can't drop or reorder characters.
type is sent in small chunks (--chunk 1 --delay 0.03); raise the delay for Qt/Electron apps that garble fast input.
Global type / keys go to the OS-focused window - pctr focus first.
Qt apps expose a rich tree including embedded webviews. Electron apps expose only the window frame unless accessibility is enabled (use focus + keys).

License

MIT

Metadata

Release files for pctr 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pctr 0.2.2
File	Size	Uploaded
pctr-0.2.2.tar.gz	16.5 kB	Sep 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pctr 0.2.2
File	Interpreter	ABI	Platform	Reset
pctr-0.2.2-py3-none-any.whl 16.2 kB Sep 28, 2026	Python 3	none	any	Details

Total release size: 32.7 kB

Release files / pctr-0.2.2.tar.gz

Download URL	pctr-0.2.2.tar.gz
Size	16.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`c6f3d26884860dab8380f571bac543891c8e31fde8294e09e8fdef6081f54c68`
BLAKE2b-256 checksum How to use checksums	`7f7de2968846c20d9264cfed4313c460567193b8343b53f3446aca6e62565992`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / pctr-0.2.2-py3-none-any.whl

Download URL	pctr-0.2.2-py3-none-any.whl
Size	16.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`eb61ed4e3144c11acc30da4a73b070521bc0c436c312c17621c6b8d6174dcf11`
BLAKE2b-256 checksum How to use checksums	`ff10a9cada9974f1a2da6474af301de99abf12dfb728383c1974e09780a694c2`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`