-
Notifications
You must be signed in to change notification settings - Fork 4k
Update winapp CLI skill for latest winapp CLI capabilities in v0.3.1 #1599
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
aaronpowell
merged 7 commits into
github:staged
from
alvinashcraft:alvinashcraft/staged-update-winapp-cli-skill
May 4, 2026
+165
−179
Merged
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
3ccfab4
Update winapp CLI skill
alvinashcraft 31447ff
Updated skill for winapp cli based on review
alvinashcraft caf06ab
Updates to tighten up skill for winappcli
alvinashcraft 7fd4f96
Tighten skill to reduce token use
alvinashcraft 02f9caf
Update to use steps
alvinashcraft 31bc133
Updates from review comments
alvinashcraft 94fd4a3
Fix spellcheck in build
alvinashcraft File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,217 +1,115 @@ | ||
| --- | ||
| name: winapp-cli | ||
| description: 'Windows App Development CLI (winapp) for building, packaging, and deploying Windows applications. Use when asked to initialize Windows app projects, create MSIX packages, generate AppxManifest.xml, manage development certificates, add package identity for debugging, sign packages, publish to the Microsoft Store, create external catalogs, or access Windows SDK build tools. Supports .NET (csproj), C++, Electron, Rust, Tauri, and cross-platform frameworks targeting Windows.' | ||
| description: 'Windows App Development CLI (winapp) for building, packaging, signing, debugging, and UI-automating Windows applications. Use when asked to initialize Windows app projects, create MSIX packages, manage AppxManifest.xml or development certificates, run an app as packaged for debugging, automate Windows UI via Microsoft UI Automation, publish to the Microsoft Store, or access Windows SDK build tools. Covers commands like init, pack, run, unregister, manifest, cert, sign, store, ui, and tool. Supports .NET (csproj), C++, Electron, Rust, Tauri, Flutter, and other Windows frameworks.' | ||
| --- | ||
|
|
||
| # Windows App Development CLI | ||
|
|
||
| The Windows App Development CLI (`winapp`) is a command-line interface for managing Windows SDKs, MSIX packaging, generating app identity, manifests, certificates, and using build tools with any app framework. It bridges the gap between cross-platform development and Windows-native capabilities. | ||
|
|
||
| ## When to Use This Skill | ||
|
|
||
| Use this skill when you need to: | ||
|
|
||
| - Initialize a Windows app project with SDK setup, manifests, and certificates | ||
| - Create MSIX packages from application directories | ||
| - Generate or manage AppxManifest.xml files | ||
| - Create and install development certificates for signing | ||
| - Add package identity for debugging Windows APIs | ||
| - Sign MSIX packages or executables | ||
| - Access Windows SDK build tools from any framework | ||
| - Build Windows apps using cross-platform frameworks (Electron, Rust, Tauri, Qt) | ||
| - Set up CI/CD pipelines for Windows app deployment | ||
| - Access Windows APIs that require package identity (notifications, Windows AI, shell integration) | ||
| - Publish apps to the Microsoft Store via `winapp store` | ||
| - Create external catalogs for asset management | ||
| - Set up .NET (csproj) projects with Windows App SDK via NuGet | ||
| `winapp` manages Windows SDKs, MSIX packaging, app identity, manifests, certificates, signing, store publishing, and UI automation for any framework targeting Windows (.NET/csproj, C++, Electron, Rust, Tauri, Flutter, etc.). Public preview — subject to change. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - Windows 10 or later | ||
| - winapp CLI installed via one of these methods: | ||
| - **WinGet**: `winget install Microsoft.WinAppCli --source winget` | ||
| - **NPM** (for Electron): `npm install @microsoft/winappcli --save-dev` | ||
| - **GitHub Actions/Azure DevOps**: Use [setup-WinAppCli](https://github.com/microsoft/setup-WinAppCli) action | ||
| - **Manual**: Download from [GitHub Releases](https://github.com/microsoft/WinAppCli/releases/latest) | ||
|
|
||
| ## Core Capabilities | ||
|
|
||
| ### 1. Project Initialization (`winapp init`) | ||
|
|
||
| Initialize a directory with required assets (manifest, certificates, libraries) for building a modern Windows app. Supports SDK installation modes: `stable`, `preview`, `experimental`, or `none`. | ||
|
|
||
| ### 2. MSIX Packaging (`winapp pack`) | ||
|
|
||
| Create MSIX packages from prepared directories with optional signing, certificate generation, and self-contained deployment bundling. | ||
|
|
||
| ### 3. Package Identity for Debugging (`winapp create-debug-identity`) | ||
|
|
||
| Add temporary package identity to executables for debugging Windows APIs that require identity (notifications, Windows AI, shell integration) without full packaging. | ||
|
|
||
| ### 4. Manifest Management (`winapp manifest`) | ||
|
|
||
| Generate AppxManifest.xml files and update image assets from source images, automatically creating all required sizes and aspect ratios. Supports manifest placeholders for dynamic content and qualified names in AppxManifest for flexible app identity definitions. | ||
|
|
||
| ### 5. Certificate Management (`winapp cert`) | ||
|
|
||
| Generate development certificates and install them to the local machine store for signing packages. | ||
|
|
||
| ### 6. Package Signing (`winapp sign`) | ||
|
|
||
| Sign MSIX packages and executables with PFX certificates, with optional timestamp server support. | ||
|
|
||
| ### 7. SDK Build Tools Access (`winapp tool`) | ||
|
|
||
| Run Windows SDK build tools with properly configured paths from any framework or build system. | ||
|
|
||
| ### 8. Microsoft Store Integration (`winapp store`) | ||
|
|
||
| Run Microsoft Store Developer CLI commands directly from winapp, enabling store submission, package validation, and publishing workflows without leaving the CLI. | ||
|
|
||
| ### 9. External Catalog Creation (`winapp create-external-catalog`) | ||
|
|
||
| Create external catalogs to streamline asset management for developers, separating catalog data from the main package. | ||
|
|
||
| ## Usage Examples | ||
|
|
||
| ### Example 1: Initialize and Package a Windows App | ||
|
|
||
| ```bash | ||
| # Initialize workspace with defaults | ||
| winapp init | ||
| # Note: init no longer auto-generates a certificate (v0.2.0+). Generate one explicitly: | ||
| winapp cert generate | ||
|
|
||
| # Build your application (framework-specific) | ||
| # ... | ||
|
|
||
| # Create signed MSIX package | ||
| winapp pack ./build-output --generate-cert --output MyApp.msix | ||
| ``` | ||
|
|
||
| ### Example 2: Debug with Package Identity | ||
|
|
||
| ```bash | ||
| # Add debug identity to executable for testing Windows APIs | ||
| winapp create-debug-identity ./bin/MyApp.exe | ||
|
|
||
| # Run your app - it now has package identity | ||
| ./bin/MyApp.exe | ||
| ``` | ||
|
|
||
| ### Example 3: CI/CD Pipeline Setup | ||
|
|
||
| ```yaml | ||
| # GitHub Actions example | ||
| - name: Setup winapp CLI | ||
| uses: microsoft/setup-WinAppCli@v1 | ||
| - Install via one of: | ||
| - WinGet: `winget install Microsoft.WinAppCli --source winget` | ||
| - npm (Electron/Node): `npm install @microsoft/winappcli --save-dev` | ||
| - CI: [`setup-WinAppCli`](https://github.com/microsoft/setup-WinAppCli) GitHub Action | ||
| - Manual: [GitHub Releases](https://github.com/microsoft/WinAppCli/releases/latest) | ||
|
|
||
| - name: Initialize and Package | ||
| run: | | ||
| winapp init --no-prompt | ||
| winapp pack ./build-output --output MyApp.msix | ||
| ``` | ||
| ## Commands | ||
|
|
||
| ### Example 4: Electron App Integration | ||
| | Command | Purpose | | ||
| | ------- | ------- | | ||
| | `init` | Initialize project: SDKs (`stable`/`preview`/`experimental`/`none`), manifest, `winapp.yaml`. **`.csproj` projects skip `winapp.yaml`** and use NuGet directly. **Does not auto-generate a cert** (v0.2.0+). | | ||
| | `restore` / `update` | Restore or update SDK package versions (`--setup-sdks preview` for preview SDKs). | | ||
| | `pack <dir>` | Build MSIX. Flags: `--generate-cert`, `--cert <pfx> --cert-password`, `--self-contained` (bundles WinAppSDK runtime), `--output`. Auto-discovers third-party WinRT components from `.winmd` (v0.2.1+). | | ||
| | `run <dir> [-- <app args>]` | Pack as loose layout and launch as packaged app — ideal for IDE F5 debugging without producing an MSIX. Supports `--` arg passthrough (v0.3.1+). (v0.3.0+) | | ||
| | `create-debug-identity <exe>` | Add sparse package identity to an exe so it can call identity-gated APIs (notifications, Windows AI, shell integration) without full packaging. | | ||
| | `unregister` | Remove sideloaded dev packages registered by `run` / `create-debug-identity`. | | ||
| | `manifest` | Generate `AppxManifest.xml`; supports placeholders and qualified names. `manifest update-assets <image>` generates all required icon sizes from one source (PNG **or SVG**, v0.2.1+). | | ||
| | `cert generate` / `install` / `info` | Manage dev certs. `cert info <pfx> --password <pwd>` shows subject/issuer/validity. `--export-cer` exports the public key. `--json` available on `generate` and `info`. (v0.2.1+) | | ||
| | `sign <target> --cert <pfx>` | Sign MSIX or exe; optional timestamp server. | | ||
| | `tool` | Run Windows SDK build tools with paths configured. | | ||
| | `store` | Run Microsoft Store Developer CLI for store submission/validation/publishing. | | ||
| | `create-external-catalog` | Generate `CodeIntegrityExternal.cat` for TrustedLaunch sparse packages. | | ||
| | `ui list-windows` / `inspect` / `click` / `search` / `wait-for` / `get-focused` | UI automation via Microsoft UI Automation. All support `--json`. **Envelope changed in v0.3.1** — see [`references/ui-json-envelope.md`](./references/ui-json-envelope.md). (v0.3.0+) | | ||
| | `node create-addon` / `add-electron-debug-identity` / `clear-electron-debug-identity` | Electron/Node helpers. All commands also exposed as typed JS/TS functions from `@microsoft/winappcli` (v0.2.1+). | | ||
|
|
||
| ```bash | ||
| # Install via npm | ||
| npm install @microsoft/winappcli --save-dev | ||
| CI tip: pass `--no-prompt` to skip interactive prompts. | ||
|
|
||
| # Initialize and add debug identity for Electron | ||
| npx winapp init | ||
| npx winapp node add-electron-debug-identity | ||
| ## Workflow | ||
|
|
||
| # Package for distribution | ||
| npx winapp pack ./out --output MyElectronApp.msix | ||
| ``` | ||
| Standard init → package flow: | ||
|
|
||
| ## Guidelines | ||
| 1. **Initialize the project** in your app folder. Sets up SDK refs, manifest, and `winapp.yaml` (`.csproj` projects skip the YAML and configure NuGet directly). | ||
|
|
||
| 1. **Run `winapp init` first** - Always initialize your project before using other commands to ensure SDK setup and manifest are configured. Note: as of v0.2.0, `winapp init` no longer generates a development certificate automatically. Run `winapp cert generate` explicitly when you need to sign with a dev certificate. | ||
| 2. **Re-run `create-debug-identity` after manifest changes** - Package identity must be recreated whenever AppxManifest.xml is modified. | ||
| 3. **Use `--no-prompt` for CI/CD** - Prevents interactive prompts in automated pipelines by using default values. | ||
| 4. **Use `winapp restore` for shared projects** - Recreates the exact environment state defined in `winapp.yaml` across machines. | ||
| 5. **Generate assets from a single image** - Use `winapp manifest update-assets` with one logo to generate all required icon sizes. | ||
| ```bash | ||
|
alvinashcraft marked this conversation as resolved.
|
||
| winapp init # add --no-prompt in CI | ||
| ``` | ||
|
|
||
| ## Common Patterns | ||
| 2. **Generate a dev signing certificate** — required for sideloading. `init` no longer creates one (v0.2.0+). | ||
|
|
||
| ### Pattern: Initialize New Project | ||
| ```bash | ||
| winapp cert generate | ||
| ``` | ||
|
|
||
| ```bash | ||
| cd my-project | ||
| winapp init | ||
| # Creates: AppxManifest.xml, SDK configuration, winapp.yaml | ||
| # Note: .NET (csproj) projects skip winapp.yaml and configure NuGet packages in the .csproj directly | ||
| 3. **Build your app** with the framework's own toolchain (`dotnet build`, `npm run build`, `cargo build`, etc.). | ||
| 4. **Package as MSIX**, signing with the dev cert (or supply your own with `--cert <pfx> --cert-password`). | ||
|
|
||
| # Generate a dev signing certificate explicitly (no longer done by init) | ||
| winapp cert generate | ||
| ``` | ||
| ```bash | ||
| winapp pack ./build-output --generate-cert --output MyApp.msix | ||
| ``` | ||
|
|
||
| ### Pattern: Package with Existing Certificate | ||
| 5. **(Optional) Sign with a production cert** before distribution. | ||
|
|
||
| ```bash | ||
| winapp pack ./build-output --cert ./mycert.pfx --cert-password secret --output MyApp.msix | ||
| ``` | ||
| ```bash | ||
| winapp sign MyApp.msix --cert ./prod.pfx --cert-password $env:CERT_PWD | ||
| ``` | ||
|
|
||
| ### Pattern: Self-Contained Deployment | ||
| 6. **(Optional) Submit to the Microsoft Store** with `winapp store …` (wraps the Store Developer CLI). | ||
|
|
||
| ```bash | ||
| # Bundle Windows App SDK runtime with the package | ||
| winapp pack ./my-app --self-contained --generate-cert | ||
| ``` | ||
| ### Alternate flows | ||
|
|
||
| ### Pattern: Update Package Versions | ||
| - **Debug identity-gated APIs without packaging** (notifications, Windows AI, shell): | ||
|
|
||
| ```bash | ||
| # Update to latest stable SDKs | ||
| winapp update | ||
| ```bash | ||
| winapp create-debug-identity ./bin/MyApp.exe | ||
| ./bin/MyApp.exe | ||
|
alvinashcraft marked this conversation as resolved.
|
||
| ``` | ||
|
|
||
|
alvinashcraft marked this conversation as resolved.
|
||
| # Or update to preview SDKs | ||
| winapp update --setup-sdks preview | ||
| ``` | ||
| - **Run as packaged app for IDE F5** (loose layout; app args after `--`): | ||
|
|
||
| ## Limitations | ||
| ```bash | ||
| winapp run ./bin/Debug/net10.0-windows10.0.26100.0/win-x64 \ | ||
| --manifest ./appxmanifest.xml -- --my-flag value | ||
| ``` | ||
|
|
||
| - Windows 10 or later required (Windows-only CLI) | ||
| - Package identity debugging requires re-running `create-debug-identity` after any manifest changes | ||
| - Self-contained deployment increases package size by bundling the Windows App SDK runtime | ||
| - Development certificates are for testing only; production requires trusted certificates | ||
| - Some Windows APIs require specific capability declarations in the manifest | ||
| - `winapp init` no longer auto-generates a certificate (v0.2.0+); run `winapp cert generate` explicitly | ||
| - .NET (csproj) projects skip `winapp.yaml`; SDK packages are configured in the project file directly | ||
| - winapp CLI uses the NuGet global cache for packages (not `%userprofile%/.winapp/packages`) | ||
| - winapp CLI is in public preview and subject to change | ||
| - **Electron**: | ||
|
|
||
| ## Windows APIs Enabled by Package Identity | ||
| ```bash | ||
| npx winapp init | ||
| npx winapp node add-electron-debug-identity | ||
| npx winapp pack ./out --output MyElectronApp.msix | ||
| ``` | ||
|
|
||
| Package identity unlocks access to powerful Windows APIs: | ||
| ## Gotchas | ||
|
|
||
| | API Category | Examples | | ||
| | ------------ | -------- | | ||
| | **Notifications** | Interactive native notifications, notification management | | ||
| | **Windows AI** | On-device LLM, text/image AI APIs (Phi Silica, Windows ML) | | ||
| | **Shell Integration** | Explorer, Taskbar, Share sheet integration | | ||
| | **Protocol Handlers** | Custom URI schemes (`yourapp://`) | | ||
| | **Device Access** | Camera, microphone, location (with consent) | | ||
| | **Background Tasks** | Run when app is closed | | ||
| | **File Associations** | Open file types with your app | | ||
| - **`winapp ui --json` envelope reshaped in v0.3.1** — `ui inspect`, `ui get-focused`, `ui search`, and `ui wait-for` use new shapes; per-element `id` / `parentSelector` / `windowHandle` are removed (use `selector`). Full schemas in [`references/ui-json-envelope.md`](./references/ui-json-envelope.md). | ||
| - **`winapp init` no longer auto-generates a certificate** (v0.2.0+) — run `winapp cert generate` explicitly. The old `--no-cert` flag was removed. | ||
| - **`.csproj` projects skip `winapp.yaml`** — SDK packages live in the project file. Hybrid setups need adjustment. | ||
| - **NuGet global cache, not `%userprofile%/.winapp/packages`** (v0.2.0+) — scripts depending on the old folder will break. | ||
| - **Re-run `create-debug-identity` after any manifest change** — identity is bound at registration time. | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| | Issue | Solution | | ||
| | ----- | -------- | | ||
| | Certificate not trusted | Run `winapp cert install <cert-path>` to install to local machine store | | ||
| | Package identity not working | Run `winapp create-debug-identity` after any manifest changes | | ||
| | SDK not found | Run `winapp restore` or `winapp update` to ensure SDKs are installed | | ||
| | Signing fails | Verify certificate password and ensure cert is not expired | | ||
| | Issue | Fix | | ||
| | ----- | --- | | ||
| | Certificate not trusted | `winapp cert install <pfx>` to add to local machine store | | ||
| | Identity-gated API fails | Re-run `create-debug-identity` after manifest changes | | ||
| | SDK not found | `winapp restore` or `winapp update` | | ||
| | `register`/`unregister` errors | v0.3.1 maps `0x800704EC`→Developer Mode and `0x80073CFB`→package conflict (with actionable hint) | | ||
|
|
||
| ## References | ||
|
|
||
| - [GitHub Repository](https://github.com/microsoft/WinAppCli) | ||
| - [Full CLI Documentation](https://github.com/microsoft/WinAppCli/blob/main/docs/usage.md) | ||
| - [.NET Project Guide](https://github.com/microsoft/WinAppCli/blob/main/docs/guides/dotnet.md) | ||
| - [Sample Applications](https://github.com/microsoft/WinAppCli/tree/main/samples) | ||
| - [Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/) | ||
| - [MSIX Packaging Overview](https://learn.microsoft.com/windows/msix/overview) | ||
| - [Package Identity Overview](https://learn.microsoft.com/windows/apps/desktop/modernize/package-identity-overview) | ||
| - [winapp CLI repo](https://github.com/microsoft/WinAppCli) · [Full usage docs](https://github.com/microsoft/WinAppCli/blob/main/docs/usage.md) · [.NET guide](https://github.com/microsoft/WinAppCli/blob/main/docs/guides/dotnet.md) · [Samples](https://github.com/microsoft/WinAppCli/tree/main/samples) | ||
| - [Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/) · [MSIX overview](https://learn.microsoft.com/windows/msix/overview) · [Package identity overview](https://learn.microsoft.com/windows/apps/desktop/modernize/package-identity-overview) | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.