npx skills add ...
npx skills add microsoft/winappcli --skill winapp-troubleshoot
npx skills add microsoft/winappcli --skill winapp-troubleshoot
Diagnose and fix common Windows app packaging, signing, identity, and SDK errors. Use when encountering errors with MSIX packaging, certificate signing, Windows SDK setup, or app installation.
Use this skill when:
| Error | Cause | Solution |
|---|---|---|
| "winapp.yaml not found" | Running restore or update without config | Run winapp init first, or cd to the directory containing winapp.yaml |
| "Package.appxmanifest not found" | Running package, create-debug-identity, or cert generate --manifest | Run winapp init or winapp manifest generate first, or pass --manifest <path> |
| "Publisher mismatch" | Certificate publisher ≠ manifest publisher | Regenerate cert: winapp cert generate --manifest, or edit Package.appxmanifest Identity.Publisher to match |
| "Access denied" / "elevation required" | cert install without admin | Run terminal as Administrator for winapp cert install |
| "Package installation failed" | Cert not trusted, or stale package registration | winapp cert install ./devcert.pfx (admin), then Get-AppxPackage <name> | Remove-AppxPackage |
| "Certificate not trusted" | Dev cert not installed on machine | winapp cert install ./devcert.pfx (admin) |
| "Build tools not found" | First run, tools not yet downloaded | Run winapp update to download tools; ensure internet access |
| "Failed to add package identity" | Stale debug identity or untrusted cert | Get-AppxPackage *yourapp* | Remove-AppxPackage to clean up, then winapp cert install and retry |
| "Certificate file already exists" | devcert.pfx already present | Use winapp cert generate --if-exists overwrite or --if-exists skip |
| "Manifest already exists" | Package.appxmanifest already present | Use winapp manifest generate --if-exists overwrite or edit manifest directly |
run / create-debug-identity registration error 0x800704EC | Developer Mode is disabled | 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 the package was registered from a different project tree), then retry |
Important notes:
winapp init adds files to an existing project — it does not create a new projectPackage.appxmanifest, not winapp.yamlwinapp.yaml is only needed for SDK version management (restore/update).csproj referencing Microsoft.Windows.SDK.BuildTools) can use winapp commands without winapp.yamlnpm install --save-dev @microsoft/winappcli) which includes Node.js-specific commands under npx winapp node| Goal | Command | Key detail |
|---|---|---|
| Run with identity (most common) | winapp run .\build\Debug | Registers loose layout + launches; add --with-alias for console apps |
| Attach debugger to running app | winapp run .\build\Debug → attach to PID | Misses startup code |
| Register identity, launch manually | winapp run .\build\Debug --no-launch | Launch via start shell:AppsFolder\<AUMID> or execution alias — not the exe directly |
| F5 startup debugging (IDE launches exe) | winapp create-debug-identity .\bin\myapp.exe | Exe has identity regardless of how it's launched; best for debugging activation/startup code |
| Capture OutputDebugString + crash dump | winapp run .\build\Debug --debug-output | On crash, writes minidump and shows exception type, message, and faulting methods. Blocks other debuggers — use --no-launch if you need VS Code/WinDbg |
| Run and auto-clean | winapp run .\build\Debug --unregister-on-exit | Unregisters the dev package after the app exits |
| Launch and detach (CI) | winapp run .\build\Debug --detach | Returns immediately after launch; use --json to get PID for scripting |
| Clean up stale registration | winapp unregister | Removes dev-mode packages for the current project |
Visual Studio users: If you have a packaging project, VS already handles identity and debugging from F5 — you likely don't need winapp for debugging. These workflows are for VS Code, terminal, and frameworks VS doesn't natively package.
For full details, see the Debugging Guide.
| Command | Requires | Creates/Modifies |
|---|---|---|
init | Existing project (any framework) | winapp.yaml, .winapp/, Package.appxmanifest, Assets/, .gitignore update |
restore | winapp.yaml | .winapp/packages/, generated projections |
update | winapp.yaml | Updates versions in winapp.yaml, reinstalls packages |
manifest generate | Nothing | Package.appxmanifest, Assets/ |
manifest update-assets | Package.appxmanifest + source image | Regenerates Assets/ icons |
cert generate | Nothing (or Package.appxmanifest for publisher) | devcert.pfx |
cert install | Certificate file + admin | Machine certificate store |
create-debug-identity | Package.appxmanifest + exe + trusted cert | Registers sparse package with Windows |
run | Build output folder + Package.appxmanifest | Registers loose layout package, launches app |
unregister | Package.appxmanifest (auto-detect or --manifest) | Removes dev-mode package registrations |
package | Build output + Package.appxmanifest | .msix file |
sign | File + certificate | Signed file (in-place) |
create-external-catalog | Directory with executables | CodeIntegrityExternal.cat |
tool <name> | Nothing (auto-downloads tools) | Runs SDK tool directly |
store | Nothing (auto-downloads Store CLI) | Passthrough to Microsoft Store Developer CLI |
get-winapp-path | Nothing | Prints .winapp directory path |
--verbose (or -v) to any command for detailed output--quiet (or -q) to suppress progress messages (useful in CI/CD)winapp --cli-schema to get the full JSON schema of all commands and options--help for its specific usage informationwinapp get-winapp-path to find where packages are stored locallywinapp get-winapp-path --global to find the shared cache locationwinapp-setup — adding Windows support to a projectwinapp-manifest — creating and editing Package.appxmanifestwinapp-signing — certificate generation and managementwinapp-package — creating MSIX installerswinapp-identity — enabling package identity for Windows APIswinapp-frameworks — framework-specific guidance (Electron, .NET, C++, Rust, Flutter, Tauri)winapp get-winapp-pathPrint the path to the .winapp directory. Use --global for the shared cache location, or omit for the project-local .winapp folder. Useful for build scripts that need to reference installed packages.
| Option | Description | Default |
|---|---|---|
--global | Get the global .winapp directory instead of local | (none) |
winapp toolRun Windows SDK tools directly (makeappx, signtool, makepri, etc.). Auto-downloads Build Tools if needed. For most tasks, prefer higher-level commands like 'package' or 'sign'. Example: winapp tool makeappx pack /d ./folder /p ./out.msix
Aliases: run-buildtool
winapp storeRun a Microsoft Store Developer CLI command. This command will download the Microsoft Store Developer CLI if not already downloaded. Learn more about the Microsoft Store Developer CLI here: https://aka.ms/msstoredevcli