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.1

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.1
File	Size	Uploaded
pctr-0.2.1.tar.gz	14.1 kB	Sep 24, 2026	Details

Built distribution (wheel)

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

Total release size: 27.8 kB

Release files / pctr-0.2.1.tar.gz

Download URL	pctr-0.2.1.tar.gz
Size	14.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`f947b088c36aa9f936f5e239bfadbd914baacc2d751813c8dacf86fa164a4b08`
BLAKE2b-256 checksum How to use checksums	`0c691891a706465517aac5351781b292955c1e457e3d272008de1090ac941249`
Upload date	Sep 24, 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.1-py3-none-any.whl

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