Windows App Development CLI reference

Important

The Windows App Development CLI is currently in public preview. Features and commands may change before the final release.

This page documents all available commands for the winapp CLI.

Global options

All commands support these global options:

Option	Description
`--verbose`, `-v`	Enable verbose output for detailed logging
`--quiet`, `-q`	Suppress progress messages
`--help`, `-h`	Show command help

Global cache directory

WinApp creates a directory to cache files that can be shared between multiple projects. By default, this is $UserProfile/.winapp.

To use a different location, set the WINAPP_CLI_CACHE_DIRECTORY environment variable:

$env:WINAPP_CLI_CACHE_DIRECTORY = "d:\temp\.winapp"

Setup commands

init

Initialize a directory with Windows SDK, Windows App SDK, and required assets for modern Windows development.

winapp init [base-directory] [options]

Arguments:

Argument	Description
`base-directory`	Base/root directory for the app/workspace (default: current directory)

Options:

Option	Description
`--config-dir <path>`	Directory to read/store configuration (default: current directory)
`--setup-sdks`	SDK installation mode: `stable` (default), `preview`, `experimental`, or `none`
`--ignore-config`, `--no-config`	Don't use configuration file for version management
`--no-gitignore`	Don't update .gitignore file
`--use-defaults`, `--no-prompt`	Do not prompt, and use default of all prompts
`--config-only`	Only handle configuration file operations, skip package installation

What it does:

Creates winapp.yaml configuration file
Downloads Windows SDK and Windows App SDK packages
Generates C++/WinRT headers and binaries
Creates AppxManifest.xml
Sets up build tools and enables developer mode
Updates .gitignore to exclude generated files

Automatic .NET project detection:

When a .csproj file is found in the target directory, init uses a streamlined .NET-specific flow:

Validates and updates the TargetFramework to a Windows-compatible TFM (for example, net10.0-windows10.0.26100.0)
Adds Microsoft.WindowsAppSDK and Microsoft.Windows.SDK.BuildTools as NuGet PackageReference entries directly in the .csproj
Generates appxmanifest.xml, assets, and a development certificate
Does not create a winapp.yaml or download C++ projections (use dotnet restore for NuGet packages)

Examples:

# Initialize current directory
winapp init

# Initialize with experimental packages
winapp init --setup-sdks experimental

# Initialize specific directory without prompts
winapp init ./my-project --use-defaults

# Initialize a .NET project (auto-detected from .csproj)
cd my-dotnet-app
winapp init

Tip

If you ran init with --setup-sdks none and later need the SDKs, re-run winapp init --use-defaults --setup-sdks stable. This preserves existing files (manifest, etc.).

restore

Restore packages and regenerate files based on existing winapp.yaml configuration.

winapp restore [options]

Options:

Option	Description
`--config-dir <path>`	Directory containing winapp.yaml (default: current directory)

What it does:

Reads existing winapp.yaml configuration
Downloads/updates SDK packages to specified versions
Regenerates C++/WinRT headers and binaries

Note

For .NET projects initialized with winapp init, there is no winapp.yaml. Use dotnet restore to restore NuGet packages instead.

Examples:

# Restore from winapp.yaml in current directory
winapp restore

update

Update packages to their latest versions and update the configuration file.

winapp update [options]

Options:

Option	Description
`--config-dir <path>`	Directory containing winapp.yaml (default: current directory)
`--setup-sdks`	SDK installation mode: `stable` (default), `preview`, `experimental`, or `none`

What it does:

Reads existing winapp.yaml configuration
Updates all packages to their latest available versions
Updates the winapp.yaml file with new version numbers
Regenerates C++/WinRT headers and binaries

Examples:

# Update packages to latest versions
winapp update

# Update including experimental packages
winapp update --setup-sdks experimental

Packaging commands

pack

Create MSIX packages from prepared application directories. Requires appxmanifest.xml file to be present in the target directory, in the current directory, or passed with the --manifest option.

winapp pack <input-folder> [options]

Arguments:

Argument	Description
`input-folder`	Directory containing the application files to package

Options:

Option	Description
`--output <filename>`	Output MSIX file name (default: `<name>.msix`)
`--name <name>`	Package name (default: from manifest)
`--manifest <path>`	Path to AppxManifest.xml (default: auto-detect)
`--cert <path>`	Path to signing certificate (enables auto-signing)
`--cert-password <password>`	Certificate password (default: "password")
`--generate-cert`	Generate a new development certificate
`--install-cert`	Install certificate to machine
`--publisher <name>`	Publisher name for certificate generation
`--self-contained`	Bundle Windows App SDK runtime
`--skip-pri`	Skip PRI file generation
`--executable <path>`	Path to the executable relative to the input folder. Used to resolve $targetnametoken$ placeholders in the manifest.

What it does:

Validates and processes AppxManifest.xml files
Resolves $placeholder$ tokens in the manifest (see Manifest placeholders)
Ensures proper framework dependencies
Updates side-by-side manifests with registrations
Handles self-contained Windows App SDK deployment
Signs package if certificate provided

Examples:

# Package directory with auto-detected manifest
winapp pack ./dist

# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx

# Package with generated and installed certificate and self-contained runtime
winapp pack ./dist --generate-cert --install-cert --self-contained

# Package with explicit executable
winapp pack ./dist --executable MyApp.exe

create-debug-identity

Create app identity for debugging without full MSIX packaging using external location/sparse packaging.

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

Arguments:

Argument	Description
`entrypoint`	Path to executable (.exe) or script that needs identity

Options:

Option	Description
`--manifest <path>`	Path to AppxManifest.xml (default: `./appxmanifest.xml`)
`--no-install`	Don't install the package after creation
`--keep-identity`	Keep the manifest identity as-is, without appending `.debug` to the package name and application ID

What it does:

Modifies executable's side-by-side manifest
Registers sparse package for identity
Enables debugging of identity-requiring APIs

Examples:

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

# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml

Manifest commands

manifest generate

Generate AppxManifest.xml from templates.

winapp manifest generate [directory] [options]

Arguments:

Argument	Description
`directory`	Directory to generate manifest in (default: current directory)

Options:

Option	Description
`--package-name <name>`	Package name (default: folder name)
`--publisher-name <name>`	Publisher CN (default: `CN=<current user>`)
`--version <version>`	Version (default: "1.0.0.0")
`--description <text>`	Description (default: "My Application")
`--entrypoint <path>`	Entry point executable or script
`--template <type>`	Template type: `packaged` (default) or `sparse`
`--logo-path <path>`	Path to logo image file
`--if-exists <Error\\|Overwrite\\|Skip>`	Behavior if the file already exists (default: Error)

Templates:

packaged - Standard packaged app manifest
sparse - App manifest using sparse/external location packaging

Manifest placeholders

Generated manifests use $placeholder$ tokens (dollar-sign delimited) that are resolved automatically at packaging time:

Placeholder	Resolved to	Example
$targetnametoken$	Executable name without extension	`Executable="$targetnametoken$.exe"` becomes `Executable="MyApp.exe"`
$targetentrypoint$	`Windows.FullTrustApplication`	Always resolved automatically

How placeholders are resolved:

winapp pack resolves $targetnametoken$ using the --executable option or by auto-detecting the single .exe in the input folder.
winapp create-debug-identity resolves $targetnametoken$ from the entrypoint argument when provided.
winapp manifest generate --executable extracts metadata from the executable but keeps $targetnametoken$.exe in the manifest for later resolution.

Tip

Keeping $targetnametoken$ in your checked-in manifest avoids hard-coding executable names and works with both winapp pack and Visual Studio builds.

Examples:

# Generate standard manifest interactively
winapp manifest generate

# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite

manifest update-assets

Generate all required MSIX image assets from a single source image.

winapp manifest update-assets <image-path> [options]

Arguments:

Argument	Description
`image-path`	Path to source image file (PNG, JPG, GIF, etc.)

Options:

Option	Description
`--manifest <path>`	Path to AppxManifest.xml file (default: search current directory)

Takes a single source image and automatically generates all 12 required MSIX image assets at the correct dimensions. Assets are saved to the Assets directory relative to the manifest location.

Examples:

# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png

# Specify manifest location explicitly
winapp manifest update-assets mylogo.png --manifest ./dist/appxmanifest.xml

Certificate and signing commands

cert generate

Generate development certificates for package signing.

winapp cert generate [options]

Options:

Option	Description
`--manifest <appxmanifest.xml>`	Extract publisher information from appxmanifest.xml
`--publisher <name>`	Publisher name for certificate
`--output <path>`	Output certificate file path
`--password <password>`	Certificate password (default: "password")
`--valid-days <days>`	Number of days the certificate is valid (default: 365)
`--install`	Install the certificate to the local machine store after generation
`--if-exists <Error\\|Overwrite\\|Skip>`	Behavior if the certificate file already exists (default: Error)

cert install

Install certificate to machine certificate store.

winapp cert install <cert-path>

Arguments:

Argument	Description
`cert-path`	Path to certificate file to install

Examples:

# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx

# Install certificate to machine
winapp cert install ./mycert.pfx

sign

Sign MSIX packages and executables with certificates.

winapp sign <file-path> [options]

Arguments:

Argument	Description
`file-path`	Path to MSIX package or executable to sign

Options:

Option	Description
`--cert <path>`	Path to signing certificate
`--cert-password <password>`	Certificate password (default: "password")

Examples:

# Sign MSIX package
winapp sign MyApp.msix --cert ./mycert.pfx

# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-password mypassword

Utility commands

tool

Access Windows SDK tools directly. Uses tools available in Microsoft.Windows.SDK.BuildTools.

winapp tool <tool-name> [tool-arguments]

Available tools:

makeappx - Create and manipulate app packages
signtool - Sign files and verify signatures
mt - Manifest tool for side-by-side assemblies
And other Windows SDK tools from Microsoft.Windows.SDK.BuildTools

Examples:

# Use signtool to verify signature
winapp tool signtool verify /pa MyApp.msix

store

Run a Microsoft Store Developer CLI command. This command downloads the Microsoft Store Developer CLI if not already downloaded. Learn more at Microsoft Store Developer CLI.

winapp store [args...]

Arguments:

Argument	Description
`args...`	Arguments to pass directly to the `msstore` CLI

Examples:

# List all apps in your Microsoft Partner Center account
winapp store app list

# Publish a package to the Microsoft Store
winapp store publish ./myapp.msix --appId <your-app-id>

get-winapp-path

Get paths to installed Windows SDK components.

winapp get-winapp-path [options]

Returns paths to the .winapp workspace directory, package installation directories, and generated header locations.

Node.js/Electron commands

These commands are available in the NPM package only.

node create-addon

Generate native C++ or C# addon templates with Windows SDK and Windows App SDK integration.

npx winapp node create-addon [options]

Options:

Option	Description
`--name <name>`	Addon name (default: "nativeWindowsAddon")
`--template`	Select type of addon: `cs` or `cpp` (default: `cpp`)
`--verbose`	Enable verbose output

What it does:

Creates addon directory with template files
Generates binding.gyp and addon files with Windows SDK examples
Installs required npm dependencies
Adds build script to package.json

Examples:

# Generate addon with default name
npx winapp node create-addon

# Generate custom named C# addon
npx winapp node create-addon --name myWindowsAddon --template cs

node add-electron-debug-identity

Add app identity to Electron development process by using sparse packaging. Requires an appxmanifest.xml (create one with winapp init or winapp manifest generate).

Important

There is a known issue with sparse packaging Electron applications which causes the app to crash on start or not render web content. The issue has been fixed in Windows but hasn't propagated to all devices yet. You can disable sandboxing in your Electron app with the --no-sandbox flag as a workaround. This issue does not affect full MSIX packaging.

To undo the Electron debug identity, use winapp node clear-electron-debug-identity.

npx winapp node add-electron-debug-identity [options]

Options:

Option	Description
`--manifest <path>`	Path to custom appxmanifest.xml (default: appxmanifest.xml in current directory)
`--no-install`	Do not install or modify dependencies; only configure the Electron debug identity
`--keep-identity`	Keep the manifest identity as-is, without appending `.debug`
`--verbose`	Enable verbose output

Examples:

# Add identity to Electron development process
npx winapp node add-electron-debug-identity

# Use a custom manifest file
npx winapp node add-electron-debug-identity --manifest ./custom/appxmanifest.xml

node clear-electron-debug-identity

Remove package identity from the Electron debug process by restoring the original electron.exe from backup.

npx winapp node clear-electron-debug-identity [options]

Options:

Option	Description
`--verbose`	Enable verbose output

Examples:

# Remove identity from Electron development process
npx winapp node clear-electron-debug-identity

Feedback

Was this page helpful?

Last updated on 2026-03-05

Share via

Windows App Development CLI reference

Global options

Global cache directory

Setup commands

init

restore

update

Packaging commands

pack

create-debug-identity

Manifest commands

manifest generate

Manifest placeholders

manifest update-assets

Certificate and signing commands

cert generate

cert install

sign

Utility commands

tool

store

get-winapp-path

Node.js/Electron commands

node create-addon

node add-electron-debug-identity

node clear-electron-debug-identity

Related topics

Feedback

Additional resources