microsoft/winappCli v0.3.1

Release v0.3.1

Repository: microsoft/winappCli

Tag: v0.3.1

Published: 2026-05-01T19:10:33Z

Prerelease: no

Release notes: Version: 0.3.1 Commit: c8ada4a403c43b96780b87abc454cba51f649c60

Breaking Changes

• `winapp ui --json` envelope reshape (#511) — JSON output shapes are not backward compatible. Update any scripts/tools parsing these outputs:
• ui inspect --json — elements are now nested under { depth, interactive, hideDisabled, hideOffscreen, windows: [{ hwnd, title, className, elementCount, elements: [{ ..., children: [...] }] }] } (was a flat { elements: [...] } list). Per-element id, depth, parentSelector, and windowHandle fields have been removed — selector is the public handle.
• ui inspect --ancestors --json — ancestors are now nested via a Depth=i parent → child chain (previously emitted as sibling roots).
• ui get-focused --json — emits a { hasFocus: false } or { hasFocus: true, element: {...} } envelope (was a bare null when nothing was focused).
• ui search --json / ui wait-for --json — internal id, parentSelector, and windowHandle fields are scrubbed from results (top-level and nested invokableAncestor).

New Features

• `winapp run` support for `--` passthrough arguments (#506) — Pass application arguments directly using -- without escaping them in quotes. For example, instead of:

winapp run . --args "--my-flag value"

you can now write:

winapp run . -- --my-flag value

• Plain progress streaming in CI and AI-agent terminals (#507) — Auto-detects environments that can't honour cursor control (GitHub Actions, Azure DevOps, Copilot CLI, Claude Code, etc.) and falls back to append-only line-buffered progress output. Real interactive terminals continue to render the animated spinner tree; --quiet / --json remain silent. No new flags or env vars.
• `ui inspect --interactive` ancestor surfacing (#511) — Non-interactive ancestors are collapsed and surfaced as ancestorPath on surviving descendants; +more markers indicate truncated subtrees in both text and JSON modes.

Bug Fixes

• `winapp run` no longer picks `createdump.exe` (#496) — Fixed an issue where winapp run could incorrectly select createdump.exe over the intended application executable when multiple .exe files existed. Detection logic is now shared with winapp package.
• `winapp register`: accurate error for package-already-exists conflicts (#512) — HRESULT 0x80073CFB was being misreported as a Developer Mode error. The Developer Mode mapping is now correctly scoped to 0x800704EC, and conflicts emit an actionable hint with the real package identity (parsed from the manifest).
• `winapp unregister`: safer per-package unregistration (#512) — Fixed two data-loss bugs: a per-package safety check that could be bypassed when multiple packages were classified together, and sibling-directory misclassification caused by a prefix StartsWith containment check. Rewritten as a two-pass classify-then-remove loop with segment-aware path containment.
• Status output: real exception messages instead of `(null)` (#512) — Failed operations now surface ex.Message; falls back to "Operation failed without an error message." when no message is available. Stack traces are appended only at Debug log level.
• NuGet version range parsing on cache-warm runs (#512) — ParseMinimumVersion no longer silently breaks when brackets are pre-stripped (which only manifested after git clean of .winapp while the global NuGet cache still had the package).
• WinAppSDK 2.0.1 forward compatibility (#512) — Supports the new major-only framework package naming (Microsoft.WindowsAppRuntime.2 instead of Microsoft.WindowsAppRuntime.2.0).

Compliance

• NuGet package metadata (#489) — Microsoft.Windows.SDK.BuildTools.WinApp now includes a compliant `` element required by Microsoft NuGet policy.

---

Installation Options

MSIX Installer (Recommended)

1. Download winappcli_x64.msix for x64 or winappcli_arm64.msix for ARM64 2. Double-click to install 3. Automatically added to PATH

Standalone CLI Binaries

1. Download winappcli-x64.zip for x64 or winappcli-arm64.zip for ARM64 2. Extract to your desired location 3. Add to PATH or run directly: winapp.exe

NPM Package (for Electron or NodeJS)

npm install microsoft-winappcli.tgz

What's Included

• MSIX installer packages (x64 and ARM64)
• Standalone CLI binaries (x64 and ARM64)
• NPM package for NodeJS/Electron integration