Attribution: Sourced from microsoft/skills by Microsoft.
Windows App Development CLI
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
- Install via one of:
- WinGet:
winget install Microsoft.WinAppCli --source winget
- npm (Electron/Node):
npm install @microsoft/winappcli --save-dev
- CI:
setup-WinAppCli GitHub Action
- Manual: GitHub Releases
Commands
| 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. JSON envelopes for inspect, get-focused, search, and wait-for changed in v0.3.1 — see references/ui-json-envelope.md (other ui subcommands keep their pre-0.3.1 output). (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+). |
CI tip: pass --no-prompt to skip interactive prompts.
Workflow
Standard init → package flow:
Initialize the project in your app folder. Sets up SDK refs, manifest, and winapp.yaml (.csproj projects skip the YAML and configure NuGet directly).
winapp init # add --no-prompt in CI
Generate a dev signing certificate — required for sideloading. init no longer creates one for non-.csproj projects (v0.2.0+). Pin the output path so later steps can reference it.
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx --install
Build your app with the framework's own toolchain (dotnet build, npm run build, cargo build, etc.).
Package as MSIX, signing with the cert from step 2.
winapp pack ./build-output --cert ./mycert.pfx --cert-password password --output MyApp.msix
(Optional) Re-sign with a production cert before distribution.
winapp sign MyApp.msix --cert ./prod.pfx --cert-password $env:CERT_PWD
(Optional) Submit to the Microsoft Store with winapp store … (wraps the Store Developer CLI).
Alternate flows
Debug identity-gated APIs without packaging (notifications, Windows AI, shell):
winapp create-debug-identity ./bin/MyApp.exe
./bin/MyApp.exe
Run as packaged app for IDE F5 (loose layout; app args after --):
winapp run ./bin/Debug/net10.0-windows10.0.26100.0/win-x64 \
--manifest ./appxmanifest.xml -- --my-flag value
Electron:
npx winapp init
npx winapp node add-electron-debug-identity
npx winapp pack ./out --output MyElectronApp.msix
Gotchas
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.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 |
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 |
run / create-debug-identity registration error 0x800704EC |
Developer Mode is off — enable it in Settings → Privacy & security → For developers (or Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -Name AllowDevelopmentWithoutDevLicense -Value 1), then retry |
run / create-debug-identity registration error 0x80073CFB |
Package already registered with a conflicting identity — run winapp unregister (or winapp unregister --force if registered from a different project tree), then retry |
References
1---2name: winapp-cli3description: Windows App Development CLI (winapp) for building, packaging, signing, debugging, and UI-automating Windows applications4---56> **Attribution:** Sourced from [microsoft/skills](https://github.com/microsoft/skills) by [Microsoft](https://microsoft.com).78# Windows App Development CLI910`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.1112## Prerequisites1314- Windows 10 or later15- Install via one of:16 - WinGet: `winget install Microsoft.WinAppCli --source winget`17 - npm (Electron/Node): `npm install @microsoft/winappcli --save-dev`18 - CI: [`setup-WinAppCli`](https://github.com/microsoft/setup-WinAppCli) GitHub Action19 - Manual: [GitHub Releases](https://github.com/microsoft/WinAppCli/releases/latest)2021## Commands2223| Command | Purpose |24| ------- | ------- |25| `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+). |26| `restore` / `update` | Restore or update SDK package versions (`--setup-sdks preview` for preview SDKs). |27| `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+). |28| `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+) |29| `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. |30| `unregister` | Remove sideloaded dev packages registered by `run` / `create-debug-identity`. |31| `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+). |32| `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+) |33| `sign <target> --cert <pfx>` | Sign MSIX or exe; optional timestamp server. |34| `tool` | Run Windows SDK build tools with paths configured. |35| `store` | Run Microsoft Store Developer CLI for store submission/validation/publishing. |36| `create-external-catalog` | Generate `CodeIntegrityExternal.cat` for TrustedLaunch sparse packages. |37| `ui list-windows` / `inspect` / `click` / `search` / `wait-for` / `get-focused` | UI automation via Microsoft UI Automation. All support `--json`. **JSON envelopes for `inspect`, `get-focused`, `search`, and `wait-for` changed in v0.3.1** — see [`references/ui-json-envelope.md`](./references/ui-json-envelope.md) (other `ui` subcommands keep their pre-0.3.1 output). (v0.3.0+) |38| `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+). |3940CI tip: pass `--no-prompt` to skip interactive prompts.4142## Workflow4344Standard init → package flow:45461. **Initialize the project** in your app folder. Sets up SDK refs, manifest, and `winapp.yaml` (`.csproj` projects skip the YAML and configure NuGet directly).4748 ```bash49 winapp init # add --no-prompt in CI50 ```51522. **Generate a dev signing certificate** — required for sideloading. `init` no longer creates one for non-`.csproj` projects (v0.2.0+). Pin the output path so later steps can reference it.5354 ```bash55 winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx --install56 ```57583. **Build your app** with the framework's own toolchain (`dotnet build`, `npm run build`, `cargo build`, etc.).594. **Package as MSIX**, signing with the cert from step 2.6061 ```bash62 winapp pack ./build-output --cert ./mycert.pfx --cert-password password --output MyApp.msix63 ```64655. **(Optional) Re-sign with a production cert** before distribution.6667 ```bash68 winapp sign MyApp.msix --cert ./prod.pfx --cert-password $env:CERT_PWD69 ```70716. **(Optional) Submit to the Microsoft Store** with `winapp store …` (wraps the Store Developer CLI).7273### Alternate flows7475- **Debug identity-gated APIs without packaging** (notifications, Windows AI, shell):7677 ```bash78 winapp create-debug-identity ./bin/MyApp.exe79 ./bin/MyApp.exe80 ```8182- **Run as packaged app for IDE F5** (loose layout; app args after `--`):8384 ```bash85 winapp run ./bin/Debug/net10.0-windows10.0.26100.0/win-x64 \86 --manifest ./appxmanifest.xml -- --my-flag value87 ```8889- **Electron**:9091 ```bash92 npx winapp init93 npx winapp node add-electron-debug-identity94 npx winapp pack ./out --output MyElectronApp.msix95 ```9697## Gotchas9899- **`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).100- **`winapp init` no longer auto-generates a certificate** (v0.2.0+) — run `winapp cert generate` explicitly. The old `--no-cert` flag was removed.101- **`.csproj` projects skip `winapp.yaml`** — SDK packages live in the project file. Hybrid setups need adjustment.102- **NuGet global cache, not `%userprofile%/.winapp/packages`** (v0.2.0+) — scripts depending on the old folder will break.103- **Re-run `create-debug-identity` after any manifest change** — identity is bound at registration time.104105## Troubleshooting106107| Issue | Fix |108| ----- | --- |109| Certificate not trusted | `winapp cert install <pfx>` to add to local machine store |110| Identity-gated API fails | Re-run `create-debug-identity` after manifest changes |111| SDK not found | `winapp restore` or `winapp update` |112| `run` / `create-debug-identity` registration error `0x800704EC` | Developer Mode is off — enable it in **Settings → Privacy & security → For developers** (or `Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -Name AllowDevelopmentWithoutDevLicense -Value 1`), then retry |113| `run` / `create-debug-identity` registration error `0x80073CFB` | Package already registered with a conflicting identity — run `winapp unregister` (or `winapp unregister --force` if registered from a different project tree), then retry |114115## References116117- [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)118- [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)
mouadja02