WinAppCLI: The CLI Tool for Rapid Windows App Development
WinAppCLI: The CLI Tool for Rapid Windows App Development
Build, package, and deploy Windows applications from the terminal with a single, unified command‑line interface.
Why WinAppCLI?
Modern cross‑platform frameworks (Electron, .NET, C++, Rust, Tauri…) deliver great user experiences, but deploying for Windows still feels like a separate, error‑prone process. You need to:
- Install and manage the full Windows and Windows App SDK toolsets.
- Generate AppxManifest.xml files that encode identity, capabilities, and shortcut information.
- Create and maintain development certificates.
- Package your app as an MSIX or EXE.
- Sign binaries, set version numbers, and configure Store‑ready metadata.
Doing each of these manually is tedious and easy to get wrong. WinAppCLI consolidates these tasks into a tiny, well‑maintained open‑source project.
- One tool for multiple frameworks – Electron, .NET, C++, Rust, Tauri.
- Zero‑friction SDK installation – automatically fetches the latest Windows SDK and App SDK.
- Instant app identity – add temporary identities for debugging without full packaging.
- Fast, reproducible MSIX generation – ready for CI/CD pipelines.
- Open source – MIT licensed and fully auditable.
Quick Start
1. Install WinAppCLI
| Platform | Command |
|---|---|
| Windows (via WinGet) | winget install Microsoft.winappcli --source winget |
| Node / Electron | npm install @microsoft/winappcli --save-dev |
| CI Environments | Use the GitHub Actions setup‑WinAppCli action or install via winget on the runner |
For local development you can also download the latest release from the GitHub releases page. |
2. Verify the installation
winapp --help
You should see a help menu with commands such as init, package, cert, and manifest.
3. Initialize a project
# In a new or existing Electron project
winapp init
This pulls the necessary SDKs, creates placeholders for certificates, and writes a winapp.example.yaml (you can rename it to winapp.yaml). |
Core Commands Overview
| Command | Purpose |
|---|---|
init |
Initializes SDKs and generates scaffolding for manifests and identity |
restore |
Restores SDK packages and dependencies |
update |
Updates SDKs to the latest versions |
package |
Builds an MSIX or EXE package from a source directory |
create-debug-identity |
Adds a temporary app identity for debugging |
manifest |
Generates or updates AppxManifest.xml |
cert |
Creates or updates a development certificate |
sign |
Signs an MSIX or EXE with the specified certificate |
tool |
Exposes Windows SDK command‑line tools |
node create-addon |
Generates C# or C++ addons for Electron |
node add-electron-debug-identity |
Adds debugging identity to Electron processes |
A full reference is available in the official docs.
Sample Projects
The repository ships a collection of ready‑to‑run samples that show practical usage across multiple stacks. Each sample contains a winapp.yaml and a short README.
- Electron – Uses Electron Forge, a native C++ addon, and a C# module.
- Electron WinML – Demonstrates image classification with Windows ML.
- C++ (Win32) – A pure‑C++ application built with CMake.
- .NET Console – Showcases the .NET WinAppSDK wrapper.
- WPF – A classic Windows Presentation Foundation UI.
- Rust – Utilizes the windows-rs crate for native APIs.
- Tauri – A Rust backend powering a cross‑platform front end.
Running a sample is as simple as:
cd samples/electron
npm install
npx winapp init
npx winapp package
The resulting dist directory contains an MSIX packaged application ready for sideloading or Store submission.
CI/CD Integration
WinAppCLI is designed to fit seamlessly into modern pipelines.
GitHub Actions
- name: Setup WinAppCLI
uses: microsoft/setup-winappcli@v1
- name: Build and Sign
run: |
winapp init
winapp package
winapp sign --certificate myCert.pfx --password ${{ secrets.CERT_PASSWORD }}
Azure DevOps
Add the official setup-WinAppCli task to your pipeline or install via winget on the agent.
The CLI exposes environment variables (e.g., WINAPP_SDK_PATH) that allow you to reference installed SDKs in other tools.
Common Challenges & Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
winapp: unrecognized command |
CLI not on PATH | Verify installation, re‑run winget install or npm add the local node_modules/.bin to PATH |
| Signing fails with The certificate was not found | Incorrect cert path or password | Provide full path with --certificate flag, use --password or environment variable WINAPP_CERT_PASSWORD |
| App identity conflicts between Electron and .NET builds | Duplicate identity in winapp.yaml |
Remove or rename conflicting identity entries |
| MSIX install fails with signature is missing | Certificate not trusted | Install the dev certificate into Trusted Root Certification Authorities on the test machine |
| --- |
Contributing
WinAppCLI is an open‑source project under the MIT license. Feel free to:
- Open issues – bug reports, feature ideas, or usage questions.
- Submit pull requests – fixes, enhancements, or new language bindings.
- Contribute samples – add support for another framework or build system.
All contributors must sign Microsoft’s Contributor License Agreement. Check the CONTRIBUTING.md for details.
Final Thoughts
WinAppCLI turns the daunting task of Windows app packaging into a repeatable, scriptable process. Whether you’re an Electron developer looking to add native Windows features, a .NET developer who wants quick MSIX packaging, or a CI engineer who needs reliable build steps, this CLI is a powerful addition to your toolchain.
Give it a spin: install it via WinGet or NPM, try out a sample, and let us know what you think. With community contributions and a Microsoft‑backed roadmap, WinAppCLI is set to become the de‑facto standard for Windows app development in the cross‑platform era.