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-WinAppCliGitHub 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(.csprojprojects skip the YAML and configure NuGet directly).
winapp init # add --no-prompt in CI- Generate a dev signing certificate — required for sideloading.
initno longer creates one for non-.csprojprojects (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.msixGotchas
winapp ui --jsonenvelope reshaped in v0.3.1 —ui inspect,ui get-focused,ui search, andui wait-foruse new shapes; per-elementid/parentSelector/windowHandleare removed (useselector). Full schemas inreferences/ui-json-envelope.md.winapp initno longer auto-generates a certificate (v0.2.0+) — runwinapp cert generateexplicitly. The old--no-certflag was removed..csprojprojects skipwinapp.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-identityafter 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 |
