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 |
| "appxmanifest.xml 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: , or edit to match |
winapp cert generate --manifestappxmanifest.xmlIdentity.Publisher| "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" | appxmanifest.xml already present | Use winapp manifest generate --if-exists overwrite or edit manifest directly |
Does the project have an appxmanifest.xml?
├─ No → Do you want full setup (manifest + config + optional SDKs)?
│ ├─ Yes → winapp init (adds Windows platform files to existing project)
│ └─ No, just a manifest → winapp manifest generate
└─ Yes
├─ Has winapp.yaml, cloned/pulled but .winapp/ folder missing?
│ └─ winapp restore
├─ Want newer SDK versions?
│ └─ winapp update
├─ Need a dev certificate?
│ └─ winapp cert generate (then winapp cert install for trust)
├─ Need package identity for debugging? (see [Debugging Guide](https://github.com/microsoft/WinAppCli/blob/main/docs/debugging.md))
│ ├─ Exe is in your build output folder? (most frameworks)
│ │ └─ winapp run <build-output-dir>
│ └─ Exe is separate from app code? (Electron, sparse testing)
│ └─ winapp create-debug-identity <exe>
├─ Ready to create MSIX installer?
│ └─ winapp package <build-output> --cert ./devcert.pfx
├─ Need to sign an existing file?
│ └─ winapp sign <file> <cert>
├─ Need to update app icons?
│ └─ winapp manifest update-assets ./logo.png
├─ Need to run SDK tools directly?
│ └─ winapp tool <toolname> <args>
├─ Need to publish to Microsoft Store?
│ └─ winapp store <args> (passthrough to Store Developer CLI)
└─ Need the .winapp directory path for build scripts?
└─ winapp get-winapp-path (or --global for shared cache)
Important notes:
winapp init adds files to an existing project — it does not create a new projectappxmanifest.xml, 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 | winapp run .\build\Debug --debug-output | 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 |
| 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/, appxmanifest.xml, Assets/, .gitignore update |
restore | winapp.yaml | .winapp/packages/, generated projections |
update | winapp.yaml | Updates versions in winapp.yaml, reinstalls packages |
manifest generate | Nothing | appxmanifest.xml, Assets/ |
manifest update-assets | appxmanifest.xml + source image | Regenerates Assets/ icons |
cert generate | Nothing (or appxmanifest.xml for publisher) | devcert.pfx |
cert install | Certificate file + admin | Machine certificate store |
create-debug-identity | appxmanifest.xml + exe + trusted cert | Registers sparse package with Windows |
run | Build output folder + appxmanifest.xml | Registers loose layout package, launches app |
unregister | appxmanifest.xml (auto-detect or --manifest) | Removes dev-mode package registrations |
package | Build output + appxmanifest.xml | .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 appxmanifest.xmlwinapp-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