gem-hunter
Language: C#
winapp, the Windows App Development CLI, is a single command-line interface for managing Windows SDKs, packaging, generating app identity, manifests, certificates, and using build tools with any app framework.
Important
⚠️ Status: Public Preview — The Windows App Development CLI (WinApp CLI) is experimental and in active development. We'd love your feedback! Share your thoughts by creating an issue.
Note
The main branch contains work that is in active development. Documentation, features, and behavior here may differ from what is publicly released. For the latest stable version, see the latest release. To try the newest in-progress build, see Install from latest build below.
The Windows App Development CLI (WinApp CLI) is a single command-line interface for creating, running, debugging, testing, and packaging Windows apps. It manages Windows SDKs, app identity, manifests, certificates, and build tools for WinUI and any other app framework.
Whether you're building with WinUI, .NET/Win32, CMake, Electron, or Rust, this CLI gives you access to:
winapp new and launch them with winapp runwinapp ui, and ground AI coding agents with find-ui and find-apiFull documentation is published on Microsoft Learn: Windows App Development CLI.
Perfect for:
Many Windows APIs require your app to have package identity, enabling you to leverage some of the OS components Windows offers, that you wouldn't otherwise have access to. With identity, your app gains access to user-first features like notifications, OS integration, and on-device AI.
Our goal is to support developers wherever they are, with the tools and frameworks they already use. Based on feedback from developers shipping cross-platform apps on Windows, we built this CLI to streamline integrating with the Windows developer platform - handling SDK setup, header generation, manifests, certificates, and packaging in just a few commands:
Without WinApp CLI, setting up a project involves 12 manual steps—downloading SDKs, generating headers, creating manifests, and more. With the CLI, it's just 4 commands.
A few examples of what package identity and MSIX packaging unlock:
yourapp:// URIs)yoursite.com opens your app).xyz files with your app)Check out our getting started guides for step by step instructions of how to setup your environment, generate manifests, assets, and certificate, how to debug APIs that require package identity, and how to MSIX package your app.
Additional guides:
.cs file with package identity, no project file or manifest requiredwinapp init --add-js-bindings. See task-focused guides:
The easiest way to use the CLI is via WinGet (Windows Package Manager). In Terminal, run:
winget install Microsoft.winappcli --source winget
Or, if you prefer a PowerShell terminal, you can use the WinGet PowerShell cmdlet (from the Microsoft.WinGet.Client module):
Install-WinGetPackage Microsoft.winappcli
You can install the CLI for Electron projects via NPM:
npm install @microsoft/winappcli --save-dev
For CI/CD pipelines on GitHub Actions or Azure DevOps, use the setup-WinAppCli action to automatically install the CLI on your runners/agents.
Download the latest build from GitHub Releases
Caution
These builds are from the main branch and may include unreleased features, breaking changes, or experimental functionality. Use at your own risk.
Download the latest CI build artifacts directly (no GitHub login required):
| Artifact | Description |
|---|---|
| CLI Binaries | Native CLI executables (win-x64, win-arm64) |
| npm Package | @microsoft/winappcli .tgz package |
| MSIX Packages | MSIX installer bundle (self-signed) |
| NuGet Packages | NuGet .nupkg packages |
The direct links above are provided by nightly.link, a third-party service. If they stop working, you can download the same artifacts from GitHub Actions directly:
main)Note: Downloading artifacts from GitHub Actions requires you to be signed in to GitHub.
Open the PR's Build and Package run and download cli-binaries, npm-package,
msix-packages, or nuget-packages from Artifacts. The build-artifacts job
summary also links to each download.
Packages appear before validation finishes. They are experimental builds,
not evidence that tests passed. Wait for build-and-package to succeed if you
need a fully validated build. If a download is not available yet, check the
build-artifacts job for progress or errors. A new commit cancels older runs of
the same PR.
Once installed (see Installation above), verify the installation by calling the CLI:
winapp --help
or if using Electron/Node.js
npx winapp --help
Setup Commands:
new - Create a new WinUI app from an official Windows App SDK templateinit - Initialize project with Windows SDK and App SDKrestore - Restore packages and dependenciesupdate - Update packages and dependencies to latest versionsApp Identity & Debugging:
perf - Record and query WinUI operation trees, layout/scrolling timings, and managed GC suspension contextrun - Run app as a packaged application for debugging (loose layout registration)create-debug-identity - Add sparse package identity to an existing exeembed-identity - Connect an exe to its sparse identity package by embedding the <msix> elementunregister - Remove sideloaded dev packages registered by run or create-debug-identitymanifest - Generate and manage AppxManifest.xml filesSee also: Debugging Guide — choosing between winapp run and create-debug-identity, IDE setup, and debugging scenarios.
Packaging, Certificates & Signing:
pack - Create MSIX packages from a project or prepared directoriescert - Generate and install development certificatessign - Sign MSIX packages and executablesaz-sign - Sign with Azure Trusted Signing (cloud-managed identity, no local PFX)create-external-catalog - Generate CodeIntegrityExternal.cat for TrustedLaunch sparse packagesSee also: Security guidance — what development certificates and Developer Mode change on your machine, safe handling of devcert.pfx, and production signing.
Development Tools:
tool - Access Windows SDK toolsstore - Run Microsoft Store Developer CLI commandsget-winapp-path - Get paths to installed SDK componentsconfig - Show or change your per-user winapp settingscomplete - Tab completion for PowerShell, bash, zsh, and fishUI Automation & Sandbox:
ui - Inspect and interact with running app UIs through UI Automation (screenshots, element trees, clicks, and text input). See the UI Automation guidetarget - Run commands, copy files, and capture the desktop inside Windows Sandbox. See Windows Sandbox executiondevtools - Inspect, comment on and live-edit a running WinUI app (guide)Discovery (agent-first — built for AI coding agents to ground generated code in real metadata and real samples, and usable by hand):
find-api - Search and inspect the Windows/WinRT API surface (types, members, enums, namespaces) a project referencesfind-ui - Search WinUI controls & samples (WinUI 3 Gallery + Windows Community Toolkit, including its helpers, converters, and behaviors; Reactor is opt-in via --source reactor) for a working code exampleNode.js/Electron Specific:
node create-addon - Generate native C# or C++ addonsnode generate-bindings - Generate JavaScript/TypeScript bindings for WinRT APIsnode add-electron-debug-identity - Add identity to Electron processesnode clear-electron-debug-identity - Remove identity from Electron processesThe full CLI usage can be found here: Documentation Use WinApp CLI from JavaScript or TypeScript: NPM programmatic guide
This repository includes samples demonstrating how to use the CLI with various frameworks:
| Sample | Description |
|---|---|
| C++ App | Native C++ Win32 application with CMake |
| C++ WinUI App | Packaged C++/WinRT WinUI 3 app (Visual Studio .vcxproj, XAML) launched via winapp run <vcxproj> |
| .NET Console | .NET console application |
| .NET File-Based App | Single .cs file app with package identity, run via winapp run app.cs — no project or manifest |
| WPF App | WPF desktop application |
| WinUI App | Packaged WinUI 3 app registered and launched via winapp run <csproj> |
| WinUI Unpackaged App | Unpackaged WinUI 3 app launched via winapp run <csproj> |
| WinUI Solution | Multi-project .sln (app + test project) demonstrating winapp run solution-mode auto-selection |
| C++ WinUI App | WinUI 3 window built in C++ with CMake, without XAML or MSBuild |
| .NET MAUI App | .NET MAUI Windows project packaged and signed with winapp |
| Electron | Electron Forge app with appxmanifest, assets, native C++ addon, and C# addon |
| Electron WinML | Electron app using Windows ML for image classification |
| Node.js WinUI 3 | Native WinUI 3 controls created directly from JavaScript |
| Rust App | Rust application using Windows APIs |
| Tauri App | Tauri cross-platform app with Rust backend |
| Flutter App | Flutter desktop app with package identity and Windows App SDK |
| Sparse App | WPF app with production sparse packaging (identity-only MSIX) and an Inno Setup installer |
The WinApp VS Code Extension brings WinApp CLI into Visual Studio Code. It can initialize projects, debug with package identity, package, sign, and more without leaving the editor. Press F5 to launch your app with identity and automatically attach a debugger.
Install it from the Visual Studio Marketplace. Check out the repo for the WinApp VS Code Extension at microsoft/WinAppVSCE.
This repo ships two plugins, each published to the GitHub Copilot, Claude Code, and Codex marketplaces on every release:
winappcli (plugins/winapp/): an agent plus skills for winapp commands, workflows, and troubleshooting. It conforms to the Agent Plugins 1.0 specification.winui (plugins/winui/): skills for building, packaging, and testing WinUI 3 apps.GitHub Copilot CLI (global — works across all projects)
copilot plugin marketplace add microsoft/WinAppCli copilot plugin install winappcli@winappcli copilot plugin install winui@winappcli
Claude Code
claude plugin marketplace add microsoft/WinAppCli claude plugin install winappcli@winappcli claude plugin install winui@winappcli
Codex
codex plugin marketplace add microsoft/WinAppCli
Then install winappcli and winui from the Plugins directory.
File an issue, feature request or bug: please ensure that you are not filing a duplicate issue
Need help or have questions about the Windows App Development CLI? Visit our Support Guide for information about our issue templates and triage process.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
To build the CLI:
# Build the CLI and package for npm, NuGet, and MSIX from the repo root
.\scripts\build-cli.ps1
The binaries and packages will be placed in the artifacts folder. The build
also builds and stages the matching DevTools engines beside each winapp.exe.
Install the Visual Studio C++ x64/x86 and ARM64 build tools before a full build.
Npm packaging requires PowerShell 7.3 or newer for tarball verification.
From src\winapp-npm, npm run build-x64 or npm run build-arm64 builds only
that architecture and its engines, without running tests.
Developer-facing AI skills live under .github/skills/.
Before pushing a PR, you can ask Copilot CLI (or any agent that reads skill
files) to "review my PR" — the pr-review
skill fans out parallel sub-agents covering security, correctness and tests,
CLI UX, alternative solutions, necessity and simplicity, shipping surfaces
(docs/samples/packaging), and a different-model cross-check. It then builds and
runs the CLI to validate the critical findings, and prints a short list to
stdout.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.