Metadata-Version: 2.4
Name: winauto-cli
Version: 0.1.1
Summary: A pragmatic Windows UI automation CLI built on top of pywinauto.
Author: wenqu
License-Expression: MIT
Project-URL: Homepage, https://github.com/zhaowenquan131/winauto-cli
Project-URL: Repository, https://github.com/zhaowenquan131/winauto-cli
Project-URL: Issues, https://github.com/zhaowenquan131/winauto-cli/issues
Keywords: windows,automation,uia,pywinauto,testing,cli
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: Operating System :: Microsoft :: Windows
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pywinauto>=0.6.8
Dynamic: license-file

# 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:

```powershell
pip install winauto-cli
```

Or, if you prefer explicit Python invocation:

```powershell
python -m pip install winauto-cli
```

For local development:

```powershell
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:

```powershell
winauto-cli list-windows
```

### `find`

Return candidate matches instead of forcing a single element:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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:

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

Test on TestPyPI first:

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

Then publish to PyPI:

```powershell
python -m twine upload dist/*
```
