winauto-cli

winauto-cli is a Python CLI wrapper around pywinauto for Windows desktop automation, with an Agent-oriented command surface for inspection, interaction, validation, and screenshot capture.

Install

Install from PyPI:

pip install winauto-cli

Or, if you prefer explicit Python invocation:

python -m pip install winauto-cli

For local development:

pip install -e .

Agent commands

These commands default to JSON output and are intended to be composed by an AI Agent.

list-windows

List top-level windows:

winauto-cli list-windows

find

Return candidate matches instead of forcing a single element:

winauto-cli find --window-title "MyApp" --control-type Button --max-results 10
winauto-cli find --window-title "MyApp" --path "//Button[@name='Submit']"
winauto-cli find --window-title "MyApp" --path "Pane/Edit[0]"

inspect

Inspect one resolved element and return its children, parent chain, supported patterns, recommended selectors, and recommended paths:

winauto-cli inspect --window-title "MyApp" --name "Submit"
winauto-cli inspect --window-title "MyApp" --path "//Button[@name='Submit']"

inspect now returns path-oriented hints such as:

• recommended_paths
• relative_path

These are intended for Agent follow-up calls using --path.

act

Run a single action against a resolved element:

winauto-cli act --window-title "MyApp" --name "Submit" --action click
winauto-cli act --window-title "MyApp" --control-type Edit --action type --text "hello"
winauto-cli act --window-title "MyApp" --path "//Button[@name='Submit']" --action click

assert

Validate existence, count, text, visibility, or enabled state:

winauto-cli assert --window-title "MyApp" --name "Submit" --assertion exists
winauto-cli assert --window-title "MyApp" --name "Submit" --assertion enabled --expected-bool true
winauto-cli assert --window-title "MyApp" --control-type Button --assertion count --expected 3
winauto-cli assert --window-title "MyApp" --path "//Button[@name='Submit']" --assertion exists

screenshot

Capture a screenshot for a resolved window or element:

winauto-cli screenshot --window-title "MyApp" --out app-window.png
winauto-cli screenshot --window-title "MyApp" --path "//Button[@name='Submit']" --out submit-button.png
winauto-cli screenshot --window-title "MyApp" --path "//Button[@name='Submit']" --highlight --out submit-button-marked.png

Useful highlight options:

• --highlight
• --highlight-duration-ms 800
• --highlight-colour red
• --highlight-thickness 3

Path DSL

The --path query is XPath-like, but intentionally smaller and desktop-focused.

Supported forms:

• //Button
• //Button[@name='Submit']
• //Edit[@auto_id='txtUsername']
• Pane/Edit[0]
• //Pane[@class_name='Toolbar']/Button[1]

Rules:

• / means direct child step.
• // means descendant step.
• Type matches control_type.
• [@name='x'], [@auto_id='x'], [@class_name='x'], [@control_type='x'], [@window_text='x'] are supported.
• [0], [1], ... select by zero-based index after a step is filtered.

Compatibility commands

These are retained as convenience wrappers over the newer primitives.

• dump
• click
• type

Examples:

winauto-cli dump --window-title "MyApp"
winauto-cli click --window-title "MyApp" --name "Submit"
winauto-cli type --window-title "MyApp" --control-type Edit --text "hello from cli"

Selector model

Parent window options:

• --window-title
• --window-title-re
• --window-class-name
• --window-auto-id

Target element options:

• --name
• --auto-id
• --control-type
• --class-name
• --index
• --path

Runtime options:

• --backend {uia,win32}
• --timeout <seconds>
• --top-level-only
• --verbose
• --json

Design intent

The project is optimized for AI-assisted test authoring and debugging:

• find returns candidate sets instead of hiding ambiguity.
• inspect exposes enough metadata to refine selectors.
• act separates action execution from selector debugging.
• assert closes the loop for script verification.
• screenshot provides visual verification and failure evidence.
• --path provides a bridge between raw tree exploration and stable scripted lookup.
• Compatibility commands remain available for quick manual use.

License

This project is licensed under the MIT License. See LICENSE.

Third-party dependencies keep their own licenses. See THIRD_PARTY_NOTICES.md.

Publishing

Build distributions:

python -m pip install build twine
python -m build
python -m twine check dist/*

Test on TestPyPI first:

python -m twine upload --repository testpypi dist/*

Then publish to PyPI:

python -m twine upload dist/*