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

• winapp CLI repo · Full usage docs · .NET guide · Samples

• Windows App SDK · MSIX overview · Package identity overview