# Windows CLI

> Guidance for driving Windows desktop automation from the wincli command-line tool - the token-efficient entry point that mirrors the Windows MCP server. Use when a coding agent has shell access and wants one compact command surface instead of many MCP tool schemas.

- Skill: `sbroenne/windows-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sbroenne/windows-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sbroenne/windows-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: sbroenne (https://skillmd.com/u/sbroenne)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sbroenne/windows-cli

---


## Context

`wincli` is the command-line twin of the Windows MCP server. Every command calls the exact same
underlying tool, so behavior and JSON output are identical to the MCP tools - only the entry point
differs. Prefer `wincli` when you already have a shell: one small command vocabulary costs far fewer
tokens than loading every MCP tool schema, and each call is stateless (window handles are OS-global,
so there is no server session to keep alive).

## Discovery (do this first)

- `wincli --help` - the command map and a common workflow.
- `wincli tools` - every command with its options.
- `wincli tools --json` - machine-readable tool manifest (names, descriptions, JSON input schemas);
  the same surface the MCP server exposes via `tools/list`. Parse this to construct calls precisely.
- `wincli guidance` - the full semantic-automation guide (same text the MCP host receives).

## Preferred workflow

1. `wincli window find --title <part>` (or `wincli app --path <exe>`) to get a **window handle**.
2. `wincli ui snapshot --window <handle>` to see the accessible element tree.
3. `wincli ui find|click|type|select|read --window <handle> ...` for normal controls.
4. `wincli ui read-table --window <handle> --automation-id <grid>` to pull a grid/table/details-list into structured rows + headers in one call.
   For a web page, add `--format article` to `wincli ui read` to get clean main-content text (nav/breadcrumb chrome and inline link URLs stripped, headings/lists as markdown).
5. `wincli file-save --window <handle> --path <file>` for Save / Save As - never raw Ctrl+S.
   Use `wincli file-open --window <handle> --path <file>` for Open flows.
6. `wincli clipboard get|set|clear` for fast bulk text IO; `wincli macro save|run|list|get|delete`
   to persist a `ui batch` sequence and replay it by name.
7. Fall back to `wincli screenshot`, `wincli mouse`, or `wincli keyboard` only for custom-drawn UI.

## Patterns

### Semantic-first automation
- Target elements by `--name`, `--name-contains`, `--control-type`, or `--automation-id`, not coordinates.
- Add `--with-snapshot` to `ui click`/`ui type`/`ui select` to get the updated tree back in the same
  call (perceive + act fused - avoids a second round trip).
- Use `ui batch --window <h> --steps '<json>'` to run an ordered sequence
  (e.g. `[{"action":"type","automationId":"UsernameInput","text":"me"},{"action":"click","name":"Submit"}]`)
  in a single invocation.

### Waiting
- Use `ui wait --window <h> --name <x>` (or `--mode disappear`) instead of sleeping, so automation
  stays fast and deterministic after dialogs, navigation, or tab switches.

### Macros (record & replay)
- Save a proven `ui batch` sequence once: `wincli macro save --name login --steps '<json>'`.
- Replay it against any window: `wincli macro run --name login --window <h>`.
- Manage saved macros with `wincli macro list|get --name <x>|delete --name <x>`.

### Clipboard
- `wincli clipboard set --text "<value>"` then paste with `wincli keyboard press --key v --modifiers ctrl`.
- Copy in the app (`wincli keyboard press --key c --modifiers ctrl`) then `wincli clipboard get` to read it.

### Exit codes (script on these)
- `0` success, `1` tool error (inspect the JSON `error` field), `2` usage error (bad arguments).

### Output
- stdout is the tool's JSON payload - parse it directly. Diagnostic detail is available on any
  command via `--include-diagnostics`.

## Anti-patterns

- Do not start with `mouse`/`screenshot` clicks when the app exposes accessible controls.
- Do not save files with raw `keyboard press --key s --modifiers ctrl` when a Save As dialog may appear;
  use `file-save`.
- Do not assume coordinates are stable across machines, themes, or display scaling.
- Do not keep re-launching an app to "retry" - reuse the existing window handle.