Metadata-Version: 2.4
Name: pctr
Version: 0.1.0
Summary: Element-based Windows UI Automation CLI for AI agents. Find controls by name/type/id and click, type, hold, drag, and screenshot - no pixel coordinates.
Author: Space-lab515
License-Expression: MIT
Keywords: automation,windows,uia,pywinauto,desktop,agent,computer-use,rpa
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pywinauto>=0.6.8; platform_system == "Windows"
Requires-Dist: uiautomation>=2.0; platform_system == "Windows"
Requires-Dist: pyautogui>=0.9.54; platform_system == "Windows"
Requires-Dist: pydirectinput>=1.0.4; platform_system == "Windows"
Dynamic: license-file

# 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

```bash
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

```bash
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
