### Re-run Init to Install SDKs

Source: https://github.com/microsoft/winappcli/blob/main/docs/usage.md

If SDKs were skipped during initial setup (e.g., with `--setup-sdks none`), re-run the `init` command to install them while preserving existing project files like the manifest. Use `--setup-sdks stable`, `--setup-sdks preview`, or `--setup-sdks experimental` to specify the desired SDK version.

```bash
# Re-run init to install SDKs - preserves existing files (manifest, etc.)
winapp init . --use-defaults --setup-sdks stable
```

--------------------------------

### Install Dependencies and Restore Packages

Source: https://github.com/microsoft/winappcli/blob/main/samples/flutter-app/README.md

Run these commands for initial setup. 'flutter pub get' installs Dart dependencies, and 'winapp restore' fetches Windows App SDK components.

```powershell
flutter pub get

winapp restore
```

--------------------------------

### Install .NET SDK

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/dotnet.md

Install the .NET SDK using winget. A restart may be required after installation.

```powershell
winget install Microsoft.DotNet.SDK.10 --source winget
```

--------------------------------

### Install npm Dependencies and Generate Dev Certificate

Source: https://github.com/microsoft/winappcli/blob/main/samples/tauri-app/README.md

Run these commands for the first-time setup of the Tauri application. `npm install` installs project dependencies, and `winapp cert generate` creates a development certificate if one doesn't exist.

```powershell
# Install npm dependencies
npm install

# Generate a dev certificate (first time only)
winapp cert generate --if-exists skip
```

--------------------------------

### Install Visual Studio Community

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/cpp.md

Installs Visual Studio Community with the Native Desktop workload. Ensure to reboot after installation.

```powershell
winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"
```

--------------------------------

### Install @microsoft/winappcli

Source: https://github.com/microsoft/winappcli/blob/main/docs/npm-usage.md

Install the winappcli NPM package using npm.

```bash
npm install @microsoft/winappcli
```

--------------------------------

### Install WinApp CLI

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/setup.md

Install the WinApp CLI using winget or npm. Winget is recommended for non-Node projects, while npm is suitable for Electron/Node projects.

```powershell
# Via winget (recommended for non-Node projects)
winget install Microsoft.WinAppCli --source winget
```

```powershell
# Via npm (recommended for Electron/Node projects — includes Node.js SDK)
npm install --save-dev @microsoft/winappcli
```

--------------------------------

### Install winapp CLI for Electron projects using NPM

Source: https://github.com/microsoft/winappcli/blob/main/docs/README.md

Install the winapp CLI as a development dependency for Electron projects using NPM. Ensure Node.js and NPM are installed.

```bash
npm install @microsoft/winappcli --save-dev
```

--------------------------------

### Install WinApp CLI for Electron Projects

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/setup.md

Installs the WinApp CLI as a dev dependency for Electron projects and suggests using `npx` for initialization.

```bash
npm install --save-dev @microsoft/winappcli
```

--------------------------------

### Build and Run Electron Sample

Source: https://github.com/microsoft/winappcli/blob/main/samples/electron/README.md

Commands to install dependencies, build native addons, and run the Electron sample.

```pwsh
# Enter pwsh and cd to this sample
pwsh
cd <reporoot>\samples\electron

# Install/restore the project dependencies
npm install

# Build the C++ and C# addons
npm run build-all

# Run the sample
npm start
```

--------------------------------

### Electron Quick Start Commands

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/frameworks.md

Commands for setting up a new Electron project with WinApp CLI, creating native addons, and registering for debugging.

```powershell
npm install --save-dev @microsoft/winappcli
npx winapp init . --use-defaults
npx winapp node create-addon --template cs   # create a C# native addon
npx winapp node add-electron-debug-identity  # register identity for debugging
```

--------------------------------

### .NET Quick Start Commands

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/frameworks.md

Commands for initializing a .NET project with WinApp CLI, building the project, and running it with automatic identity registration.

```powershell
winapp init . --use-defaults
dotnet build <path-to-project.csproj> -c Debug -p:Platform=x64
winapp run bin\x64\Debug\<tfm>\win-x64\
```

--------------------------------

### Install Certificate to Machine

Source: https://github.com/microsoft/winappcli/blob/main/docs/usage.md

Installs a PFX certificate to the machine's certificate store. This is often required before using the certificate for signing.

```bash
winapp cert install ./mycert.pfx
```

--------------------------------

### Verify winapp CLI installation

Source: https://github.com/microsoft/winappcli/blob/main/docs/README.md

Verify that the winapp CLI has been installed correctly by running the help command. This confirms the CLI is accessible in your system's PATH.

```bash
winapp --help
```

--------------------------------

### Install Certificate

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/troubleshoot.md

Installs a certificate file into the machine's certificate store. Requires administrator privileges.

```bash
winapp cert install
```

--------------------------------

### Run npm Install

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/electron/setup.md

Execute this command to trigger the postinstall script and configure the Windows environment for your project.

```bash
npm install
```

--------------------------------

### Quick Start: Initialize, Generate Cert, Package App

Source: https://github.com/microsoft/winappcli/blob/main/docs/npm-usage.md

Demonstrates a common workflow: initializing a project, generating a development certificate, and packaging the application.

```typescript
import { init, packageApp, certGenerate } from '@microsoft/winappcli';

// Initialize a new project with defaults
await init({ useDefaults: true });

// Generate a dev certificate
await certGenerate({ install: true });

// Package the built app
await packageApp({ inputFolder: './dist', cert: './devcert.pfx' });
```

--------------------------------

### Install Certificate to Machine Store

Source: https://github.com/microsoft/winappcli/blob/main/docs/usage.md

Installs a certificate to the local machine certificate store. Requires the path to the certificate file to be installed.

```bash
winapp cert install <cert-path> [options]
```

--------------------------------

### C++ Example Using Windows App Runtime API

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/cpp.md

A C++ example that initializes WinRT, retrieves the package family name, and prints the Windows App Runtime version. This demonstrates integration with the Windows App SDK.

```cpp
#include <iostream>
#include <windows.h>
#include <appmodel.h>
#include <winrt/Microsoft.Windows.ApplicationModel.WindowsAppRuntime.h>

int main() {
    // Initialize WinRT
    winrt::init_apartment();
    
    UINT32 length = 0;
    LONG result = GetCurrentPackageFamilyName(&length, nullptr);
    
    if (result == ERROR_INSUFFICIENT_BUFFER) {
        // We have a package identity
        std::wstring familyName;
        familyName.resize(length);
        
        result = GetCurrentPackageFamilyName(&length, familyName.data());
        
        if (result == ERROR_SUCCESS) {
            std::wcout << L"Package Family Name: " << familyName.c_str() << std::endl;
            
            // Get Windows App Runtime version using the API
            auto runtimeVersion = winrt::Microsoft::Windows::ApplicationModel::WindowsAppRuntime::RuntimeInfo::AsString();
            std::wcout << L"Windows App Runtime Version: " << runtimeVersion.c_str() << std::endl;
        } else {
            std::wcout << L"Error retrieving Package Family Name" << std::endl;
        }
    } else {
        std::cout << "Not packaged" << std::endl;
    }
    
    return 0;
}
```

--------------------------------

### Run All Sample and Guide Tests

Source: https://github.com/microsoft/winappcli/blob/main/AGENTS.md

Executes all Pester tests for the samples and guides in the repository. This is useful for verifying the integrity of the samples and their corresponding documentation workflows.

```powershell
# Run all sample tests
.\scripts\test-samples.ps1
```

--------------------------------

### Install MSIX Package

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/rust.md

Installs the generated MSIX package onto the system. This can be done via double-clicking the file or using PowerShell.

```powershell
Add-AppxPackage .\rust-app.msix
```

--------------------------------

### Package Application for MSIX Installer

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/troubleshoot.md

Execute `winapp package` with your build output and certificate path to create an MSIX installer for your application.

```bash
winapp package <build-output> --cert ./devcert.pfx
```

--------------------------------

### Install winapp CLI using WinGet

Source: https://github.com/microsoft/winappcli/blob/main/docs/README.md

Install the winapp CLI using the Windows Package Manager (WinGet). This is the recommended method for most users.

```powershell
winget install Microsoft.winappcli --source winget
```

--------------------------------

### Get Command Help

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/troubleshoot.md

Display specific usage information for any WinApp CLI command.

```bash
winapp <command> --help
```

--------------------------------

### Install MSIX Package

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/cpp.md

Install the generated MSIX package on your Windows machine. You can do this by double-clicking the .msix file or using PowerShell.

```powershell
Add-AppxPackage .\cpp-app_1.0.0.0_x64.msix
```

--------------------------------

### Package Application as MSIX

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/setup.md

Creates an MSIX installer for your application. Requires a development certificate for signing.

```bash
winapp package ./bin/Release --cert ./devcert.pfx
```

--------------------------------

### Install (Trust) a Certificate

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/signing.md

Installs a certificate on the local machine, adding it to the Trusted Root Certification Authorities store. This is required before MSIX packages signed with this certificate can be installed. Requires administrator privileges.

```powershell
# Trust the certificate on this machine (requires admin/elevated terminal)
winapp cert install ./devcert.pfx
```

```powershell
# Force reinstall even if already trusted
winapp cert install ./devcert.pfx --force
```

--------------------------------

### Install Development Certificate

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/packaging-cli.md

Installs the generated PFX certificate to trust it on your development machine. Requires administrator privileges to run.

```powershell
# Run PowerShell as Administrator
winapp cert install ~
devcert.pfx
```

--------------------------------

### packageApp()

Source: https://github.com/microsoft/winappcli/blob/main/docs/npm-usage.md

Creates an MSIX installer from your built app. This command should be run after building your app. A manifest (Package.appxmanifest or appxmanifest.xml) is required for packaging.

```APIDOC
## packageApp()

### Description
Create MSIX installer from your built app. Run after building your app. A manifest (Package.appxmanifest or appxmanifest.xml) is required for packaging - it must be in current working directory, passed as --manifest or be in the input folder. Use --cert devcert.pfx to sign for testing.

### Function Signature
```typescript
function packageApp(options: PackageOptions): Promise<WinappResult>
```

### Parameters
#### Options
- **inputFolder** (string | string[]) - Required - One or more input folders with package layout. Pass multiple folders to create an MSIX bundle (e.g., winapp pack ./publish/x64 ./publish/arm64).
- **cert** (string | undefined) - Optional - Path to signing certificate (will auto-sign if provided)
- **certPassword** (string | undefined) - Optional - Certificate password (default: password)
- **executable** (string | undefined) - Optional - Path to the executable relative to the input folder.
- **generateCert** (boolean | undefined) - Optional - Generate a new development certificate
- **installCert** (boolean | undefined) - Optional - Install certificate to machine
- **manifest** (string | undefined) - Optional - Path to AppX manifest file (default: auto-detect from input folder or current directory)
- **name** (string | undefined) - Optional - Package name (default: from manifest)
- **output** (string | undefined) - Optional - Output file name for the generated package (.msix) or bundle (.msixbundle). Defaults to <name>_<version>_<arch>.msix for single packages, or <name>_<version>_<arch1>_<arch2>.msixbundle for bundles.
- **publisher** (string | undefined) - Optional - Publisher name for certificate generation
- **selfContained** (boolean | undefined) - Optional - Bundle Windows App SDK runtime for self-contained deployment
- **skipPri** (boolean | undefined) - Optional - Skip PRI file generation

*Also accepts CommonOptions (`quiet`, `verbose`, `cwd`).*
```

--------------------------------

### Install MSIX Package

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/electron/packaging.md

Install the generated MSIX package by double-clicking the file or using the Add-AppxPackage PowerShell command. Ensure you replace placeholders with your actual application name and architecture.

```powershell
# Option 1 output:
Add-AppxPackage .\out\<your-app-name>.msix

# Option 2 output:
Add-AppxPackage .\out\make\msix\<arch>\<your-app-name>.msix
```

--------------------------------

### Initialize WinApp Project

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/setup.md

Initialize a new WinApp project. This command can be run interactively or non-interactively, and allows skipping SDK installation or using preview SDKs.

```powershell
# Interactive — prompts for app name, publisher, SDK channel, etc.
# Automatically searches for compatible projects (Tauri, Electron, .NET, Rust, C++, Flutter)
winapp init
```

```powershell
# Non-interactive — accepts all defaults (stable SDKs, current folder name as app name)
winapp init . --use-defaults
```

```powershell
# Skip SDK installation (just manifest + config)
winapp init . --use-defaults --setup-sdks none
```

```powershell
# Install preview SDKs instead of stable
winapp init . --use-defaults --setup-sdks preview
```

--------------------------------

### Install MSIX for Testing

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/package.md

Commands to trust a development certificate and install an MSIX package for testing purposes. Includes uninstallation instructions.

```powershell
# Trust the dev certificate first (one-time, requires admin)
winapp cert install ./devcert.pfx

# Install the MSIX
Add-AppxPackage ./myapp.msix

# Uninstall if needed
Get-AppxPackage *myapp* | Remove-AppxPackage
```

--------------------------------

### Update package.json for Cross-Platform Setup

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/electron/setup.md

Configure your package.json to use the cross-platform postinstall script. This ensures Windows-specific setup only runs on Windows.

```json
{
  "scripts": {
    "postinstall": "node scripts/postinstall.js"
  }
}
```

--------------------------------

### Install GitHub Copilot CLI Plugin for WinApp CLI

Source: https://github.com/microsoft/winappcli/blob/main/README.md

Install the GitHub Copilot CLI plugin to enable auto-discovery of WinApp CLI skills and agents. This command is run globally and works across all projects.

```bash
copilot plugin install microsoft/WinAppCli
```

--------------------------------

### Example Package.appxmanifest Structure

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/manifest.md

A standard Package.appxmanifest file for a Windows application. Key fields like Identity, Properties, Resources, Applications, and Capabilities are shown.

```xml
<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
         xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
         xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities">
  <Identity Name="MyApp" Publisher="CN=MyPublisher" Version="1.0.0.0" />
  <Properties>
    <DisplayName>My App</DisplayName>
    <PublisherDisplayName>My Publisher</PublisherDisplayName>
    <Logo>Assets\StoreLogo.png</Logo>
  </Properties>
  <Resources>
    <Resource Language="en-us" />
  </Resources>
  <Applications>
    <Application Id="App" Executable="myapp.exe" EntryPoint="Windows.FullTrustApplication">
      <uap:VisualElements DisplayName="My App" Description="My Application"
        Square150x150Logo="Assets\Square150x150Logo.png"
        Square44x44Logo="Assets\Square44x44Logo.png" BackgroundColor="transparent" />
    </Application>
  </Applications>
  <Capabilities>
    <rescap:Capability Name="runFullTrust" />
  </Capabilities>
</Package>
```

--------------------------------

### Troubleshooting: Add No Sandbox Flag

Source: https://github.com/microsoft/winappcli/blob/main/samples/electron-winml/README.md

Workaround for blank window or crash issues by adding the `--no-sandbox` flag to the start script in `package.json`.

```json
"scripts": {
    "start": "electron . --no-sandbox"
  }
```

--------------------------------

### Launch C++ App Configuration

Source: https://github.com/microsoft/winappcli/blob/main/docs/debugging.md

Example launch configuration for a C++ application using the WinApp CLI. Ensure the debuggerType is set to 'cppvsdbg'.

```jsonc
{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch C++ App",
    "debuggerType": "cppvsdbg"
}
```

--------------------------------

### Verify winapp CLI installation for Electron/Node.js projects

Source: https://github.com/microsoft/winappcli/blob/main/docs/README.md

Verify the winapp CLI installation when used within an Electron or Node.js project context. This command uses npx to execute the CLI.

```bash
npx winapp --help
```

--------------------------------

### Specify Output Directory for Loose Layout Package

Source: https://github.com/microsoft/winappcli/blob/main/docs/usage.md

This example illustrates how to define a specific directory where the loose layout package will be created.

```bash
winapp run ./bin/Release --output-appx-directory ./AppXDebug
```

--------------------------------

### Package Application for MSIX

Source: https://github.com/microsoft/winappcli/blob/main/docs/npm-usage.md

Creates an MSIX installer from your built app. Run after building your app. A manifest is required for packaging. Use --cert to sign for testing.

```bash
winapp package ./dist --manifest Package.appxmanifest --cert ./devcert.pfx
```

--------------------------------

### Get Windows SDK Component Paths

Source: https://github.com/microsoft/winappcli/blob/main/docs/usage.md

Retrieve paths to installed Windows SDK components, including workspace directories, package installations, and header locations.

```bash
winapp get-winapp-path [options]
```

--------------------------------

### Get WinApp Path

Source: https://github.com/microsoft/winappcli/blob/main/docs/npm-usage.md

Prints the path to the .winapp directory. Use the --global flag for the shared cache location or omit it for the project-local .winapp folder. Useful for build scripts that need to reference installed packages.

```typescript
function getWinappPath(options?: GetWinappPathOptions): Promise<WinappResult>
```

--------------------------------

### Troubleshooting: Install Development Certificate

Source: https://github.com/microsoft/winappcli/blob/main/samples/electron-winml/README.md

Reinstalls the development certificate as an administrator to resolve certificate errors.

```bash
npx winapp cert install .\devcert.pfx
```

--------------------------------

### Generate Base Package.appxmanifest

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/packaging-cli.md

Generate a starting Package.appxmanifest file and necessary assets for your CLI executable using the winapp CLI.

```powershell
winapp manifest generate --executable .\yourcli.exe
```

--------------------------------

### Basic Postinstall Script for Windows SDKs

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/electron/setup.md

Add this script to your package.json to automatically restore Windows SDKs and register your Electron app with a debug identity after npm install.

```json
{
  "scripts": {
    "postinstall": "winapp restore && winapp node add-electron-debug-identity"
  }
}
```

--------------------------------

### Postinstall Script for Electron 42+

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/electron/setup.md

For Electron 42 and newer, explicitly download the binary before restoring SDKs and adding debug identity. Use the --no-install flag with npx to ensure it uses the locally installed Electron binary.

```json
{
  "scripts": {
    "postinstall": "npx --no-install install-electron && winapp restore && winapp node add-electron-debug-identity"
  }
}
```

--------------------------------

### Run Installed App

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/rust.md

Executes the installed Rust application from any terminal by its registered name. This confirms the MSIX installation and execution alias.

```powershell
rust-app
```

--------------------------------

### Install Development Certificate

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/electron/packaging.md

Before installing an MSIX package, you need to install the development certificate. This command must be run with Administrator privileges.

```bash
# Run as Administrator:
npx winapp cert install .\devcert.pfx
```

--------------------------------

### Launch App with Custom Manifest and Arguments

Source: https://github.com/microsoft/winappcli/blob/main/docs/usage.md

Shows how to specify a custom manifest file and pass command-line arguments to the application during launch.

```bash
winapp run ./dist --manifest ./out/Package.appxmanifest --args "--my-flag value"
```

--------------------------------

### Install or Update winapp CLI

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/packaging-cli.md

Install the winapp CLI using Windows Package Manager or update it to the latest version if you already have it installed.

```powershell
# Install (or update if already installed)
winget install microsoft.winappcli --source winget
```

--------------------------------

### Install Development Certificate

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/identity.md

Use `winapp cert install` to install a development certificate, which is required for identity registration. This command may require administrator privileges.

```powershell
winapp cert install ./devcert.pfx
```

--------------------------------

### run()

Source: https://github.com/microsoft/winappcli/blob/main/docs/npm-usage.md

Creates a packaged layout, registers the Application, and launches the packaged application. It accepts various options to control the deployment and execution process.

```APIDOC
## run()

### Description
Creates packaged layout, registers the Application, and launches the packaged application.

### Method
run(options: RunOptions): Promise<WinappResult>

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
**Options:**
- `inputFolder` (string) - Required - Input folder containing the app to run
- `appArgs` (string | string[] | undefined) - Optional - Arguments to pass to the launched application. Provide after -- (e.g., winapp run . -- --flag value).
- `args` (string | undefined) - Optional - Command-line arguments to pass to the application. Alternatively, use -- followed by arguments to avoid escaping (e.g., winapp run . -- --flag value).
- `clean` (boolean | undefined) - Optional - Remove the existing package's application data (LocalState, settings, etc.) before re-deploying. By default, application data is preserved across re-deployments.
- `debugOutput` (boolean | undefined) - Optional - Capture OutputDebugString messages and first-chance exceptions from the launched application. Only one debugger can attach to a process at a time, so other debuggers (Visual Studio, VS Code) cannot be used simultaneously. Use --no-launch instead if you need to attach a different debugger. Cannot be combined with --no-launch or --json.
- `detach` (boolean | undefined) - Optional - Launch the application and return immediately without waiting for it to exit. Useful for CI/automation where you need to interact with the app after launch. Prints the PID to stdout (or in JSON with --json).
- `executable` (string | undefined) - Optional - Path to the executable relative to the input folder. Use to disambiguate when the manifest contains a $targetnametoken$ placeholder and multiple .exe files are present in the input folder.
- `json` (boolean | undefined) - Optional - Format output as JSON
- `manifest` (string | undefined) - Optional - Path to the Package.appxmanifest (default: auto-detect from input folder or current directory)
- `noLaunch` (boolean | undefined) - Optional - Only create the debug identity and register the package without launching the application
- `outputAppxDirectory` (string | undefined) - Optional - Output directory for the loose layout package. If not specified, a directory named AppX inside the input-folder directory will be used.
- `symbols` (boolean | undefined) - Optional - Download symbols from Microsoft Symbol Server for richer native crash analysis. Only used with --debug-output. First run downloads symbols and caches them locally; subsequent runs use the cache.
- `unregisterOnExit` (boolean | undefined) - Optional - Unregister the development package after the application exits. Only removes packages registered in development mode.
- `withAlias` (boolean | undefined) - Optional - Launch the app using its execution alias instead of AUMID activation. The app runs in the current terminal with inherited stdin/stdout/stderr. Requires a uap5:ExecutionAlias in the manifest. Use "winapp manifest add-alias" to add an execution alias to the manifest.

*Also accepts [CommonOptions](#commonoptions) (`quiet`, `verbose`, `cwd`).*
```

--------------------------------

### Initialize Project for Windows Development

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/electron/setup.md

Run the winapp init command to set up your project for Windows development. This command configures the app manifest, assets, and SDKs.

```bash
npx winapp init .
```

--------------------------------

### Publish and Package .NET Application as MSIX

Source: https://github.com/microsoft/winappcli/blob/main/samples/dotnet-app/README.md

This command publishes the application and packages it into an MSIX file in a single step. Ensure the development certificate is installed before running this command.

```powershell
dotnet publish
```

--------------------------------

### init()

Source: https://github.com/microsoft/winappcli/blob/main/docs/npm-usage.md

Initializes a Windows app project by setting up the Package.appxmanifest, downloading SDKs, and generating projections. It can also manage versioning with winapp.yaml and supports interactive or default configurations.

```APIDOC
## init()

### Description
Starts the initialization process for a Windows app, setting up the development environment. This includes creating the Package.appxmanifest, downloading necessary SDKs and packages, and generating projections. It can also create a winapp.yaml file for version management if SDK packages are managed, and operates interactively by default.

### Function Signature
```typescript
function init(options?: InitOptions): Promise<WinappResult>
```

### Options
#### Base Options

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `baseDirectory` | `string | undefined` | No | Base/root directory for the winapp workspace, for consumption or installation. |
| `configDir` | `string | undefined` | No | Directory to read/store configuration (default: the selected project directory, or current directory if no project is detected) |
| `configOnly` | `boolean | undefined` | No | Only handle configuration file operations (create if missing, validate if exists). Skip package installation and other workspace setup steps. |
| `ignoreConfig` | `boolean | undefined` | No | Don't use configuration file for version management |
| `noGitignore` | `boolean | undefined` | No | Don't update .gitignore file |
| `setupSdks` | `SdkInstallMode | undefined` | No | SDK installation mode: 'stable' (default), 'preview', 'experimental', or 'none' (skip SDK installation) |
| `useDefaults` | `boolean | undefined` | No | Do not prompt; requires an explicit project directory (e.g., winapp init . --use-defaults) |

*Also accepts [CommonOptions](commonoptions) (`quiet`, `verbose`, `cwd`).*
```

--------------------------------

### Install CMake

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/cpp.md

Installs or updates CMake using the winget package manager.

```powershell
winget install Kitware.CMake --source winget
```

--------------------------------

### Initialize Windows App Project

Source: https://github.com/microsoft/winappcli/blob/main/docs/npm-usage.md

Use `init` to set up a new Windows application project. It handles manifest creation, SDK and package downloads, and generates configuration files like winapp.yaml for version management. It can be run interactively or with default settings.

```typescript
function init(options?: InitOptions): Promise<WinappResult>
```

--------------------------------

### Initialize Project with winapp CLI

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/cpp.md

Initializes a new project with the winapp CLI, setting up the app manifest, assets, and Windows App SDK headers for C++ development.

```powershell
winapp init .
```

--------------------------------

### Initialize WinApp CLI

Source: https://github.com/microsoft/winappcli/blob/main/docs/dotnet-run-support.md

Use this command to initialize the WinApp CLI for your project. This is typically the first step before running the application.

```bash
winapp init
```

--------------------------------

### Install MSIX Package

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/packaging-cli.md

Installs the generated MSIX package onto your system. This allows you to run your CLI application.

```powershell
Add-AppxPackage .\MyCliPackage.msix
```

--------------------------------

### Install Rust Toolchain

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/rust.md

Install or update the Rust toolchain using winget. This is a prerequisite for developing Rust applications.

```powershell
winget install Rustlang.Rustup --source winget
```

--------------------------------

### WinAppCli Postinstall Script

Source: https://github.com/microsoft/winappcli/blob/main/samples/electron/README.md

The postinstall script in package.json that sets up the project with winappcli commands.

```json
"postinstall": "winapp restore && winapp cert generate --if-exists skip && winapp node add-electron-debug-identity"
```

--------------------------------

### Prepare Packaging Directory

Source: https://github.com/microsoft/winappcli/blob/main/samples/rust-app/README.md

Creates a directory for packaging and copies the release-built executable into it. This prepares the application files for MSIX packaging.

```powershell
mkdir msix
copy .\target\release\rust-app.exe .\msix\
```

--------------------------------

### Install Development Certificate

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/dotnet.md

Installs the development certificate required for signing the MSIX package. This command must be run with administrator privileges.

```powershell
winapp cert install .\devcert.pfx
```

--------------------------------

### Run Tool

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/troubleshoot.md

Executes an SDK tool directly. The tool is automatically downloaded if not present.

```bash
winapp tool <name>
```

--------------------------------

### Install Electron Forge MSIX Maker

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/electron/packaging.md

Install the '@electron-forge/maker-msix' package as a development dependency to integrate MSIX packaging into the Electron Forge workflow.

```bash
npm install --save-dev @electron-forge/maker-msix
```

--------------------------------

### Run Installed MSIX Application

Source: https://github.com/microsoft/winappcli/blob/main/samples/dotnet-app/README.md

After installing the MSIX package (by double-clicking the .msix file), the application can be run from anywhere using its executable name.

```powershell
dotnet-app
```

--------------------------------

### Initialize Project Directory

Source: https://github.com/microsoft/winappcli/blob/main/docs/usage.md

Initializes a directory with the necessary Windows SDK, Windows App SDK, and other required assets for modern Windows development. Supports various project types and configuration options.

```bash
winapp init [base-directory] [options]
```

```bash
# 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
```

--------------------------------

### Install MSIX Package with PowerShell

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/flutter.md

Use this PowerShell command to install a generated .msix package onto your system. Ensure you are in the directory containing the .msix file.

```powershell
Add-AppxPackage .\flutterapp.msix
```

--------------------------------

### Install MSIX Package with PowerShell

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/tauri.md

Use this PowerShell command to install a Tauri application packaged as an MSIX file. Ensure you are in the directory containing the MSIX file.

```powershell
Add-AppxPackage .\tauri-app.msix
```

--------------------------------

### Cross-Platform Postinstall Script

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/electron/setup.md

This JavaScript file conditionally runs Windows-specific setup only on Windows machines, preventing errors for developers on other platforms. It handles Electron binary download and SDK restoration.

```javascript
if (process.platform === 'win32') {
  const { execSync } = require('child_process');
  const fs = require('fs');
  const path = require('path');

  // Electron 42+ ships an `install-electron` bin and skips the postinstall download.
  // Run it only when present, and use `--no-install` so npx never silently fetches
  // anything from the registry.
  const installElectronBin = path.join(
    'node_modules', '.bin',
    process.platform === 'win32' ? 'install-electron.cmd' : 'install-electron'
  );
  const steps = [];
  if (fs.existsSync(installElectronBin)) {
    steps.push('npx --no-install install-electron');
  }
  steps.push(
    'npx winapp restore',
    'npx winapp cert generate --if-exists skip',
    'npx winapp node add-electron-debug-identity'
  );

  try {
    execSync(steps.join(' && '), { stdio: 'inherit' });
  } catch (error) {
    console.warn('Warning: Windows-specific setup failed. If you are not developing Windows features, you can ignore this.');
  }
} else {
  console.log('Skipping Windows-specific setup on non-Windows platform.');
}
```

--------------------------------

### Install MSIX Certificate

Source: https://github.com/microsoft/winappcli/blob/main/samples/tauri-app/README.md

Installs the development certificate required for the MSIX package. This command requires administrator privileges and should be run only the first time a certificate is used.

```powershell
# Install certificate (first time only, requires admin)
winapp cert install .\devcert.pfx
```

--------------------------------

### Basic C++ main.cpp

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/cpp.md

A simple "Hello, world!" program for a C++ application.

```cpp
#include <iostream>

int main() {
    std::cout << "Hello, world!" << std::endl;
    return 0;
}
```

--------------------------------

### WinApp CLI Crash Exception Telemetry Example

Source: https://github.com/microsoft/winappcli/blob/main/docs/telemetry.md

This example shows the format of data collected when the WinApp CLI crashes. It includes the exception type and a stack trace of the CLI code.

```console
System.IO.IOException
  at System.IO.FileStream.Write(Byte[] buffer, Int32 offset, Int32 count)
  at WinApp.Cli.Services.MsixService.GenerateManifest()
  at WinApp.Cli.Commands.ManifestGenerateCommand.Handler.InvokeAsync(InvocationContext context)
  at WinApp.Cli.Program.Main(String[] args)
```

--------------------------------

### Create Distribution Directory

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/flutter.md

Create a 'dist' directory and copy release build artifacts into it.

```powershell
mkdir dist
copy .\build\windows\x64\runner\Release\* .\dist\ -Recurse
```

--------------------------------

### Get WinApp Directory Path

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/troubleshoot.md

Use `winapp get-winapp-path` to retrieve the path to the `.winapp` directory, which can be useful for build scripts. Use `--global` to get the path to the shared cache.

```bash
winapp get-winapp-path
```

--------------------------------

### Remove Stale App Package

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/troubleshoot.md

This PowerShell command removes a stale or conflicting AppX package registration, which can help resolve installation or identity errors before retrying `winapp cert install` or other commands.

```powershell
Get-AppxPackage <name> | Remove-AppxPackage
```

--------------------------------

### Create WinML Addon with Project Root Path

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/electron/winml-addon.md

Instantiate the WinML addon by providing the project root path. This is crucial for locating model files and native dependencies. The method automatically selects the optimal execution provider (CPU, GPU, or NPU).

```csharp
[JSExport]
public static async Task<Addon> CreateAsync(string projectRoot)
{
    if (!Path.Exists(projectRoot))
    {
        throw new Exception("Project root is invalid.");
    }

    var addon = new Addon(projectRoot);
    addon.PreloadNativeDependencies();

    string modelPath = Path.Join(projectRoot, "models", @"squeezenet1.1-7.onnx");
    await addon.InitModel(modelPath, ExecutionProviderDevicePolicy.DEFAULT, null, false, null);

    return addon;
}
```

--------------------------------

### certInstall

Source: https://github.com/microsoft/winappcli/blob/main/docs/npm-usage.md

Trusts a certificate on the local machine, which requires administrator privileges. This command should be run before installing MSIX packages signed with development certificates. It accepts the path to the certificate file and has options to force installation and provide a password.

```APIDOC
## certInstall()

### Description
Trust a certificate on this machine (requires admin). Run before installing MSIX packages signed with dev certificates. Example: winapp cert install ./devcert.pfx. Only needed once per certificate.

### Function Signature
```typescript
function certInstall(options: CertInstallOptions): Promise<WinappResult>
```

### Options
#### Common Options
- `quiet` (boolean | undefined) - No - Suppress progress messages.
- `verbose` (boolean | undefined) - No - Enable verbose output.
- `cwd` (string | undefined) - No - Working directory for the CLI process (defaults to process.cwd()).

#### CertInstallOptions
- `certPath` (string) - Yes - Path to the certificate file (PFX or CER)
- `force` (boolean | undefined) - No - Force installation even if the certificate already exists
- `password` (string | undefined) - No - Password for the PFX file

### Returns
- `Promise<WinappResult>` - A promise that resolves with the WinappResult object.
```

--------------------------------

### Full Smoke Test Example

Source: https://github.com/microsoft/winappcli/blob/main/docs/ui-automation.md

A comprehensive example of a smoke test using WinAppCLI. It covers launching the application, waiting for the main page, interacting with UI elements to add and save an item, and verifying its appearance and dialog closure.

```powershell
# Launch
$app = winapp run .\build-output --detach --json | ConvertFrom-Json

# Verify app loaded
winapp ui wait-for "Main Page" -a $app.ProcessId -t 30000

# Interact and assert
winapp ui invoke "Add Item" -a $app.ProcessId
winapp ui set-value "Item Name" "Test Item" -a $app.ProcessId
winapp ui invoke "Save" -a $app.ProcessId
winapp ui wait-for "Test Item" -a $app.ProcessId -t 5000              # assert item appeared in list
winapp ui wait-for "Save" -a $app.ProcessId --gone -t 3000            # assert save dialog closed

# Visual verification
winapp ui screenshot -a $app.ProcessId -o smoke-test.png
```

--------------------------------

### Keep Original Package Identity

Source: https://github.com/microsoft/winappcli/blob/main/docs/fragments/skills/winapp-cli/identity.md

Registers a sparse package for your executable while preserving the original package name from the manifest. By default, '.debug' is appended to avoid conflicts with installed MSIX versions. Use this carefully if you have both a debug identity and an installed MSIX.

```powershell
winapp create-debug-identity ./myapp.exe --keep-identity
```

--------------------------------

### Build C# Addon

Source: https://github.com/microsoft/winappcli/blob/main/samples/electron/csAddon/README.md

Run this command to compile the C# code and generate the addon assembly.

```bash
npm run build-csAddon
```

--------------------------------

### Uninstall CLI Application

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/packaging-cli.md

Removes the installed MSIX package from your system.

```powershell
Get-AppxPackage *YourCLI* | Remove-AppxPackage
```

--------------------------------

### Create C# Native Addon

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/electron/phi-silica-addon.md

Use the winapp CLI to create a new C# native addon project. This command sets up the necessary files and scripts for building and cleaning the addon.

```bash
npx winapp node create-addon --template cs
```

--------------------------------

### Get Local WinApp Path

Source: https://github.com/microsoft/winappcli/blob/main/docs/npm-usage.md

Retrieves the full path to the local .winapp directory.

```typescript
function getLocalWinappPath(): string
```

--------------------------------

### Prepare Distribution Directory

Source: https://github.com/microsoft/winappcli/blob/main/docs/guides/rust.md

Copies the release-built executable to a 'dist' directory. This prepares the necessary files for packaging the application.

```powershell
mkdir dist
copy .\target\release\rust-app.exe .\dist\
```

--------------------------------

### Get Global WinApp Path

Source: https://github.com/microsoft/winappcli/blob/main/docs/npm-usage.md

Retrieves the full path to the global .winapp directory.

```typescript
function getGlobalWinappPath(): string
```

--------------------------------

### Using Selectors for UI Elements

Source: https://github.com/microsoft/winappcli/blob/main/docs/ui-automation.md

Examples demonstrating how to use different types of selectors (AutomationId, Semantic Slug, Plain Text) to target UI elements within an application.

```bash
winapp ui invoke MinimizeButton -a myapp
winapp ui invoke btn-close-d1a0 -a myapp
winapp ui invoke Submit -a myapp
```

--------------------------------

### Create Unsigned Multi-Architecture Bundle

Source: https://github.com/microsoft/winappcli/blob/main/docs/usage.md

Creates an unsigned .msixbundle for Microsoft Store submission by packaging multiple architecture-specific input folders.

```bash
winapp pack ./publish/x64 ./publish/arm64
```

--------------------------------

### SdkInstallMode Type

Source: https://github.com/microsoft/winappcli/blob/main/docs/npm-usage.md

Specifies the installation mode for SDK components. Can be 'stable', 'preview', 'experimental', or 'none'.

```typescript
type SdkInstallMode = "stable" | "preview" | "experimental" | "none"
```