winapp-troubleshoot

When to use

Use this skill when:

• Diagnosing errors from winapp CLI commands
• Choosing the right command for a task
• Understanding prerequisites — what each command needs and what it produces

Common errors & solutions

Command selection guide

Is the app a single .cs file (.NET file-based app)?
├─ Yes → winapp run <file>.cs  (builds it and generates the manifest for you)
└─ No → Does the project have a Package.appxmanifest?
   ├─ 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 project
• The key prerequisite for most commands is Package.appxmanifest, not winapp.yaml
• winapp.yaml is only needed for SDK version management (restore/update)
• Projects with NuGet package references (e.g., .csproj referencing Microsoft.Windows.SDK.BuildTools) can use winapp commands without winapp.yaml
• For Electron projects, use the npm package (npm install --save-dev @microsoft/winappcli) which includes Node.js-specific commands under npx winapp node

Debugging approach quick reference

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.

Prerequisites & state matrix

Debugging tips

• Add --verbose (or -v) to any command for detailed output
• Add --quiet (or -q) to suppress progress messages (useful in CI/CD)
• Run winapp --cli-schema to get the full JSON schema of all commands and options
• Run any command with --help for its specific usage information
• Use winapp get-winapp-path to find where packages are stored locally
• Use winapp get-winapp-path --global to find the shared cache location

Getting more help

• Full CLI documentation: https://github.com/microsoft/WinAppCli/blob/main/docs/usage.md
• Framework-specific guides: https://github.com/microsoft/WinAppCli/tree/main/docs/guides
• File an issue: https://github.com/microsoft/WinAppCli/issues

Related skills

• Setup & init: winapp-setup — adding Windows support to a project
• Manifest: winapp-manifest — creating and editing Package.appxmanifest
• Signing: winapp-signing — certificate generation and management
• Packaging: winapp-package — creating MSIX installers
• Identity: winapp-identity — enabling package identity for Windows APIs
• Frameworks: winapp-frameworks — framework-specific guidance (Electron, .NET, C++, Rust, Flutter, Tauri)
• MAUI: winapp-maui — packaging/signing .NET MAUI Windows apps and resolving the resizetizer manifest

CLI reference

Run winapp <command> --help for current command options, or winapp --cli-schema for the complete machine-readable command schema.