Winapp CLI

Windows App Development CLI (winapp)

The Windows App Development CLI (winapp) is a command-line interface for managing Windows SDKs, MSIX packaging, generating app identity, manifests, certificates, and using build tools with any app framework. It bridges the gap between cross-platform development and Windows-native capabilities.

When to Use This Skill

Use this skill when you need to:

• Initialize a Windows app project with SDK setup, manifests, and certificates
• Create MSIX packages from application directories
• Generate or manage AppxManifest.xml files
• Create and install development certificates for signing
• Add package identity for debugging Windows APIs
• Sign MSIX packages or executables
• Access Windows SDK build tools from any framework
• Build Windows apps using cross-platform frameworks (Electron, Rust, Tauri, Qt)
• Set up CI/CD pipelines for Windows app deployment
• Access Windows APIs that require package identity (notifications, Windows AI, shell integration)
• Publish applications to the Microsoft Store (via winapp store subcommand)
• Create external catalogs for asset management

Prerequisites

• Windows 10 or later
• winapp CLI installed via one of these methods:
  • WinGet: winget install Microsoft.WinAppCli --source winget
  • NPM (for Electron): npm install @microsoft/winappcli --save-dev
  • GitHub Actions/Azure DevOps: Use setup-WinAppCli action
  • Manual: Download from GitHub Releases

Core Commands Reference

init - Initialize Project Workspace

Initializes a directory with required assets (manifest, certificates, libraries) for building a modern Windows app.

winapp init [<base-directory>] [options]

Key Options:

v0.2.0 Breaking Change: init no longer generates a certificate automatically. Run winapp cert generate explicitly when you need a dev signing certificate. The --no-cert flag has been removed.

v0.2.0 .NET Projects: When winapp init detects a .csproj, it configures NuGet packages in the project file directly instead of creating a winapp.yaml. This is the expected behavior for .NET projects.

Example:

# Initialize with defaults
winapp init

# Initialize with preview SDKs
winapp init --setup-sdks preview

# Initialize without prompts (CI/CD)
winapp init --no-prompt

restore - Restore Workspace Packages

Restore packages from winapp.yaml (or .csproj for .NET projects) and ensure workspace is ready.

winapp restore [<base-directory>] [options]

Options:

v0.2.0 Note: winapp now uses the NuGet global cache for packages instead of %userprofile%/.winapp/packages. This avoids duplicate downloads if you already have packages cached.

Example:

# Restore packages in current directory
winapp restore

# Restore with verbose output
winapp restore --verbose

pack (package) - Create MSIX Package

Create an MSIX package from a prepared package directory.

winapp pack <input-folder> [options]

Key Options:

Examples:

# Basic packaging
winapp pack ./build-output

# Package with signing
winapp pack ./my-app --cert ./devcert.pfx --cert-password MyPassword

# Generate cert and package
winapp pack ./my-app --generate-cert --output MyApp.msix

# Self-contained deployment
winapp pack ./my-app --self-contained

manifest - AppxManifest.xml Management

Generate and manage AppxManifest.xml files.

Generate Manifest

winapp manifest generate <directory>

Example:

# Generate manifest in project directory
winapp manifest generate ./my-app

Update Image Assets

winapp manifest update-assets <image-path>

Updates image assets in AppxManifest.xml from a source image, generating all required sizes and aspect ratios.

v0.2.1: SVG files are now supported as input. The CLI converts SVG to bitmap images for all required asset sizes.

Example:

# Update all app assets from logo
winapp manifest update-assets ./images/my-logo.png

# Use SVG as source (v0.2.1+)
winapp manifest update-assets ./images/my-logo.svg

create-debug-identity - Add Package Identity for Debugging

Create and install a temporary package for debugging. Required for testing APIs that need package identity without full packaging.

winapp create-debug-identity [<entrypoint>] [options]

Options:

Example:

# Add identity to executable
winapp create-debug-identity ./bin/MyApp.exe

# With custom manifest
winapp create-debug-identity ./bin/MyApp.exe --manifest ./AppxManifest.xml

Note: Must be called every time the appxmanifest.xml is modified for changes to take effect.

cert - Certificate Management

Generate, inspect, or install development certificates.

Generate Certificate

winapp cert generate

Options:

Example:

# Generate new development certificate
winapp cert generate

# Generate with public key export
winapp cert generate -n "CN=MyCompany" -o ./devcert.pfx -p password --export-cer

View Certificate Info (v0.2.1+)

Display detailed information about a PFX certificate including subject, issuer, and validity.

winapp cert info <cert-path> [options]

Options:

Example:

# View certificate details
winapp cert info ./devcert.pfx --password password

# Get JSON output for scripting
winapp cert info ./devcert.pfx --password password --json

Install Certificate

winapp cert install <cert-path>

Example:

# Install certificate to local machine store
winapp cert install ./devcert.pfx

sign - Sign Packages

Sign a file or package with a certificate.

winapp sign <file-path> <cert-path> [options]

Options:

Example:

# Sign MSIX package
winapp sign ./MyApp.msix ./devcert.pfx --password MyPassword

# Sign with timestamp
winapp sign ./MyApp.msix ./cert.pfx --timestamp http://timestamp.digicert.com

update - Update Packages and Tools

Update packages in winapp.yaml and install/update build tools in cache.

winapp update [options]

Options:

Example:

# Update to latest stable
winapp update

# Update to preview SDKs
winapp update --setup-sdks preview

run-buildtool (tool) - Access SDK Build Tools

Run a build tool command with Windows SDK paths configured.

winapp tool [options] [[--] <additional arguments>...]

Example:

# Run a build tool with SDK paths
winapp tool -- makeappx pack /d ./app /p ./app.msix

get-winapp-path - Get SDK Paths

Get the path to the .winapp directory.

winapp get-winapp-path [--global]

Example:

# Get local .winapp path
winapp get-winapp-path

# Get global .winapp path
winapp get-winapp-path --global

store - Microsoft Store Integration (v0.2.0+)

Run Microsoft Store Developer CLI commands directly from winapp. This wraps the msstore CLI, enabling integrated Store development workflows.

winapp store <subcommand> [options]

Available Subcommands:

Examples:

# Configure Store credentials
winapp store reconfigure --tenantId xxx --sellerId xxx --clientId xxx --clientSecret xxx

# List Store apps
winapp store apps list

# Publish to Store
winapp store publish ./my-app

# Package for Store
winapp store package ./my-app --output ./packages --arch x64,arm64

Publishing Options:

create-external-catalog - Asset Management (v0.2.0+)

Create an external catalog for streamlined asset management across applications.

winapp create-external-catalog [<output-directory>] [options]

Example:

# Create external catalog in current directory
winapp create-external-catalog

# Create in specific directory
winapp create-external-catalog ./catalogs

Common Workflows

Workflow 1: Initialize New Windows App Project

# 1. Navigate to project root
cd my-project

# 2. Initialize workspace (creates manifest, assets, SDK setup)
winapp init

# 3. Generate a development certificate for signing (v0.2.0+: no longer automatic)
winapp cert generate

# 4. Your project now has:
#    - AppxManifest.xml (or configured .csproj for .NET projects)
#    - Windows SDK configuration
#    - winapp.yaml configuration (non-.NET projects only)
#    - Development certificate (after running cert generate)

Workflow 2: Debug with Package Identity

For testing Windows APIs that require package identity (notifications, Windows AI, shell integration):

# 1. Initialize project if not done
winapp init

# 2. Build your application
# (your build command here)

# 3. Add debug identity to your executable
winapp create-debug-identity ./bin/MyApp.exe

# 4. Run your app - it now has package identity for debugging
./bin/MyApp.exe

Workflow 3: Package for Distribution

# 1. Build your application
# (your build command here)

# 2. Create MSIX package with signing
winapp pack ./build-output --generate-cert --output MyApp.msix

# Or with existing certificate
winapp pack ./build-output --cert ./mycert.pfx --cert-password secret

Workflow 4: CI/CD Pipeline Setup

# GitHub Actions example
- name: Setup winapp CLI
  uses: microsoft/setup-WinAppCli@v1

- name: Initialize and Package
  run: |
    winapp init --no-prompt
    winapp cert generate  # v0.2.0+: explicit cert generation
    winapp pack ./build-output --output MyApp.msix

Workflow 5: Electron App Integration

# 1. Install via npm
npm install @microsoft/winappcli --save-dev

# 2. Initialize project
npx winapp init

# 3. Add debug identity for Electron
npx winapp node add-electron-debug-identity

# 4. Create native addon (C++ or C#)
npx winapp node create-addon

# 5. Package for distribution
npx winapp pack ./out --output MyElectronApp.msix

Workflow 6: Publish to Microsoft Store (v0.2.0+)

# 1. Configure Store credentials (one-time setup)
winapp store reconfigure --tenantId $TENANT_ID --sellerId $SELLER_ID --clientId $CLIENT_ID --clientSecret $CLIENT_SECRET

# 2. Initialize project for Store (sets up app identity)
winapp store init ./my-app

# 3. Package for Store submission
winapp store package ./my-app --arch x64,arm64

# 4. Publish to Store
winapp store publish ./my-app

# Or publish with gradual rollout
winapp store publish ./my-app --packageRolloutPercentage 10

# Or publish as draft (no commit)
winapp store publish ./my-app --noCommit

Windows APIs Enabled by Package Identity

Package identity unlocks access to powerful Windows APIs:

Troubleshooting

Framework-Specific Guides

References

• GitHub Repository
• Full CLI Documentation
• Sample Applications
• Windows App SDK
• MSIX Packaging Overview
• Microsoft Store Developer CLI
• Package Identity Overview

Converted and distributed by TomeVault — claim your Tome and manage your conversions.