winapp CLI（winappcli）の使い方｜v0.8.0の導入・主要コマンド・MSIX化・UI自動化【2026年11月】

winapp CLI（Windows App Development CLI、パッケージ名はwinappcli）は、Windowsアプリの作成・実行・デバッグ・テスト・MSIXパッケージ化を1つのコマンドで扱うMicrosoft製のツールです。Windows SDKとWindows App SDKの導入、パッケージID（package identity）の付与、マニフェストと証明書の生成も受け持ちます。2026年9月のv0.7.0でWindows Sandboxでの実行が、11月7日公開のv0.8.0でWinUI 3アプリを検査する devtools と性能を記録する perf が加わり、公式の説明もWinUI開発者を最初の対象に置く形へ変わりました。位置づけは現在もPublic Previewです。この記事では、リリースタグv0.8.0のコマンドリファレンス（usage.md）とソースコードを照合し、導入から各コマンドの使い分け、v0.6からの変更点までを整理します。

まとめ：winapp CLI v0.8.0で押さえる要点

• Windows専用です。npmパッケージの対応OSは win32 だけで、macOSやLinuxでは動きません。導入は winget install Microsoft.winappcli --source winget が基本で、Electronならnpmで入れます。
• WinUIアプリは winapp new で作り、winapp run で起動するのが現行の入口です。既存のElectron・Rust・Flutter・C++プロジェクトにWindowsの機能を足すときは winapp init から入ります。
• パッケージIDが要るAPIの検証は winapp run が基本です。v0.7.0からは --on sandbox でWindows Sandbox内に起動でき、v0.8.0からは --unique-identity で複数のworktreeを同時に登録できます。
• MSIX化は winapp pack、署名は winapp sign <ファイル> <証明書.pfx>です。証明書は位置引数で渡し、--cert では渡しません。ストア提出の winapp store はMicrosoft Store Developer CLI（msstore）を呼び出すだけのコマンドです。
• まだ0.x系のPreviewで、6週間ほどの間に3回リリースされています。手順を確認するときは、使っている版のタグを指定してドキュメントを読んでください。

以下、インストール、アプリの作成と起動、デバッグ、パッケージ化、UI自動化の順に、v0.8.0のコマンドで説明します。本記事の作成環境はmacOSのため、Windows上での実行検証は行っていません。

winapp CLIの用途と対応環境

リポジトリは microsoft/WinAppCli、ライセンスはMITで、最初の公開リリースは2025年11月4日のv0.1.0です（2026年11月11日時点のスター数は1,377）。

パッケージIDが必要になる場面

Windowsの多くのAPIは、アプリに「パッケージID」があることを前提にしています。公式READMEが例に挙げるのは、対話型の通知、エクスプローラーや共有シートへの統合、yourapp:// 形式のプロトコルハンドラー、オンデバイスAI（ローカルLLMやテキスト・画像のAPI）、ファイルの関連付け、スタートアップタスクなどです。通知のように、パッケージIDなしで使える実装方式がある機能もあります。

READMEの図は、Electronを例に、SDKの入手から登録までの12の手作業が init・node create-addon・node add-electron-debug-identity・pack の4コマンドに減ると示しています。

対応フレームワークと動作環境

公式の入門ガイドがあるのは、WinUI 3、.NET（WPF・WinForms）、.NET MAUI、C++（CMake）、Electron、Rust、Tauri、Flutterです。v0.8.0のREADMEは対象読者の筆頭を「ターミナル・VS Code・AIコーディングエージェントからアプリを作りたいWinUI開発者」に変えました。v0.6.1のREADMEでは、QtやElectronを使うクロスプラットフォームの開発者が筆頭でした。

配布形態は、スタンドアロンのCLI（WinGet・MSIXインストーラー・GitHub Releasesのzip）、npmパッケージ @microsoft/winappcli、NuGetパッケージ Microsoft.Windows.SDK.BuildTools.WinApp の3系統です。npm版はNode.js 18以上が必要です。

winapp CLIのインストール

WinGetでのインストール

もっとも簡単な経路です。winget-pkgsにはv0.8.0のマニフェストまで登録されています。

winget install Microsoft.winappcli --source winget
winapp -V

-V はv0.8.0で追加された --version の短縮形です。小文字の -v は各コマンドの --verbose を意味するので取り違えないでください。PowerShellのWinGetモジュールを使う場合は Install-WinGetPackage Microsoft.winappcli でも入ります。

npmでのインストール（Electron・Node.js）

Electronプロジェクトでは開発依存として入れ、npx winapp で呼び出します。npmの最新版は0.8.0（2026年11月7日公開）で、GitHubのリリースと版が揃っています。

npm install @microsoft/winappcli --save-dev
npx winapp --help

npm版にだけある機能が2つあります。1つはJavaScript／TypeScriptのバインディング生成（winapp init --add-js-bindings）、もう1つは後述の node 配下の4コマンドです。

GitHub ActionsとVS Code拡張

CIでは、ランナーへCLIを入れる setup-WinAppCliアクションを使います。GitHub ActionsとAzure DevOpsの両方に対応します。CI環境（GitHub Actions・Azure Pipelinesなど）では新版の確認通知が自動で止まり、手元で止めたい場合は環境変数 WINAPP_CLI_UPDATE_CHECK=0 を設定します。

VS Code拡張（Microsoft-WinAppCLI.winapp）は、プロジェクトの初期化・パッケージ化・署名をコマンドパレットから実行でき、F5でパッケージIDを付けた状態のアプリを起動します。

winapp new・runによるWinUIアプリの作成と起動

WinUIの新規開発では、new で雛形を作り、run でビルドと起動を行う2コマンドが入口です。new は公式のテンプレートパック（Microsoft.WindowsAppSDK.WinUI.CSharp.Templates）を必要に応じて入れ、dotnet new に処理を渡します。.NET SDKは自動では入らないので、先にインストールしておきます。

winapp new --name MyWinUIApp --template winui-navview --use-defaults
cd MyWinUIApp
winapp run

WinUIのアプリ用テンプレートには Package.appxmanifest が含まれるため、winapp init は不要です。

WinUIテンプレートの種類と選び方

winui-unittest のテストは dotnet test ではなく、winapp run でアプリを起動したときに実行されます。reactor 系はプレリリースの Microsoft.UI.Reactor を参照し、.NET 10 SDK以上が必要です。APIが変わる前提のテンプレートなので、業務アプリの土台には使わないほうが安全です。一覧は winapp new --list で確認できます。UIをXAMLで書くか、C#だけで書くかがテンプレート選びの分かれ目です。

winapp runの3つのモード

winapp run は、渡したものの種類で動作を切り替えます。

• フォルダーモード：マニフェストのあるビルド出力フォルダーを、ルーズレイアウトのパッケージとして登録して起動します。
• プロジェクトモード：.csproj・.sln／.slnx・C++の .vcxproj をビルドしてから起動します。C++はv0.8.0からの対応で、Visual Studio 2022 version 17.8以降（またはBuild Tools）のC++ビルドツールが必要です。
• 単一ファイルモード：.NET 10のファイルベースアプリ（.cs 1本）を、#:property 指示からマニフェストを生成してパッケージID付きで起動します。

ディレクトリを渡した場合、プロジェクトとして扱うのは直下に .csproj などがあるときだけです。.NETプロジェクトでは --aot でNative AOTとして発行してから起動できます。プロジェクトに PublishAot と PublishTrimmed の両方が有効になっている必要があり、どちらかが無効なら発行前に止まります（x64とARM64のみ、.NET SDK 8.0.300以上）。

winapp run . --aot -p PublishAot=true -p PublishTrimmed=true

winapp initによる既存プロジェクトへのSDK・マニフェスト導入

Electron・Rust・Flutter・CMakeのC++など、WinUIテンプレート以外のプロジェクトでは winapp init を使います。既定では、Package.appxmanifest とアセットの生成、Windows SDKとWindows App SDKのダウンロード、C++/WinRTヘッダーの生成、開発者モードの有効化、.gitignore の更新を行い、SDKの版を winapp.yaml に記録します。以後の restore と update はこのファイルを参照します。

# 対話を飛ばして既定値で初期化
winapp init ./my-project --use-defaults

# SDKを入れずにマニフェスト等だけ用意する（Rust・Tauri向け）
winapp init --setup-sdks none

--setup-sdks の値は stable（既定）・preview・experimental・none の4つです。none では winapp.yaml は作られません。CIのように標準入力が対話できない環境では自動的に既定値が使われ、警告が1行出ます。

プロジェクト種別の自動判別

ディレクトリを指定せず対話モードで実行すると、カレントディレクトリ以下を幅優先で探し、対応するプロジェクトを最大10件まで見つけます。--use-defaults 付きや非対話環境では探索せず、カレントディレクトリをそのまま初期化します。手がかりは次のファイルです。

.csproj の場合はSDKを PackageReference として直接追加し、winapp.yaml は作りません。

既存exeへのパッケージIDの付与（sparse）

動いているデスクトップアプリに、SDKを入れずにパッケージIDだけを足したい場合は --exe と --sparse を組み合わせます。--exe だけを指定するとエラーになります。

winapp init --exe ./bin/Release/net8.0-windows/MyApp.exe --sparse --use-defaults

生成されるのはIDだけを持つsparse用の appxmanifest.xml です。続けて次の3手順で登録まで進めます。pack は --cert か --generate-cert を付けたときだけ署名します。

winapp pack ./sparse/appxmanifest.xml --cert ./devcert.pfx
winapp embed-identity ./bin/Release/net8.0-windows/MyApp.exe
Add-AppxPackage -Path ./MyApp.identity.msix -ExternalLocation <インストール先>

最後の Add-AppxPackage は、配布時にはインストーラー側で実行します。

パッケージID付きデバッグの方式と使い分け

パッケージIDが必要なAPIを開発中に試す方法は2つあります。基本は winapp run で、フォルダー全体を実際のMSIXインストールに近い形で登録し、デバッガー用のプロセスIDを返します。公式は.NET・C++・Rust・Flutter・Tauriでこちらを推奨しています。

# 登録だけ行い、IDEから起動してデバッグする
winapp run ./bin/Debug --no-launch

# 起動してすぐ戻る（CI向け・PIDをJSONで受け取る）
winapp run . --detach --json

もう1つの winapp create-debug-identity は、単一のexeにsparseパッケージでIDを結び付けます。Electronのように electron.exe が node_modules の下にある構成や、sparseパッケージ自体の挙動を確かめたい場合に使います。既定ではパッケージ名とアプリケーションIDの末尾に .debug が付き、付けたくなければ --keep-identity を指定します。どちらで登録したパッケージも winapp unregister で外せます。

debug-outputによるクラッシュ原因の表示

winapp run --debug-output は OutputDebugString と初回例外を拾い、クラッシュ時はミニダンプを取って例外の型・メッセージ・スタックトレースをソースの行番号付きで表示します。WinUI 3アプリでは、格納された例外（stowed exception）を解析してHRESULTとXAMLの呼び出し経路まで出します。--symbols を足すとMicrosoft Symbol Serverからシンボルを取得し、ネイティブの関数名まで解決します。

1つのプロセスにアタッチできるデバッガーは1つだけなので、--debug-output の実行中はVisual StudioやVS Codeのデバッガーを使えません。併用したい場合は --no-launch で登録だけ行います。

unique-identityによる複数worktreeの同時登録

同じパッケージのアプリを2つのworktreeで同時に動かすと、後から登録した側が前の登録を置き換えます。v0.8.0で追加された --unique-identity を付けると、パスから導いた別のパッケージ名・パッケージファミリー名・アプリデータが割り当てられ、並べて登録できます。

winapp run .\worktree-a\MyApp.csproj --unique-identity --detach
winapp run .\worktree-b\MyApp.csproj --unique-identity --detach

対象はアプリが1つのフルパッケージに限られ、プロトコルハンドラー・ファイルの関連付け・COMサーバーなどの拡張を持つマニフェストや、sparseパッケージ、バンドルは拒否されます。分かれるのはパッケージIDだけで、ポートやミューテックスなどのシステム資源は共有されたままです。AIエージェントに複数ブランチを並行作業させるときに使います。

MSIXパッケージ化と証明書による署名

winapp packによるMSIXの作成

winapp pack（正式名は package、pack は別名）は、ビルド済みフォルダーかプロジェクトからMSIXを作ります。v0.7.0からは .csproj を、v0.8.0からはC++の .vcxproj を渡すと、ビルドとパッケージ化と署名を1回で行います。

# プロジェクトをReleaseでビルドし、arm64向けに作って署名する
winapp pack ./MyApp.csproj -c Release --arch arm64 --cert ./devcert.pfx

# ビルド済みフォルダーから、証明書の生成とインストールも行う
winapp pack ./dist --generate-cert --install-cert --self-contained

# 複数フォルダーを渡すと .msixbundle になる（ストア提出用は署名しない）
winapp pack ./publish/x64 ./publish/arm64

--self-contained はWindows App SDKのランタイムを同梱します。マニフェストの $targetnametoken$ は、入力フォルダー直下のexeが1つなら自動で埋まり、0個か複数なら --executable での指定を求められます。.NETのプロジェクトモードが作るのは単体の .msix か、アーキテクチャ別のバンドルだけです。ストア提出用のアップロード形式（StoreUpload）や、言語・解像度別に分けたバンドルが必要なら、SDK付属のパッケージ化コマンドを直接使います。

開発用証明書の生成とMSIXへの署名

開発用証明書は winapp cert generate で作ります。発行者はマニフェストと一致させる必要があり、--manifest を渡せば自動で取り出されます。有効期間の既定は365日、パスワードの既定は公開されている文字列 password です。この証明書は手元の検証専用で、配布するビルドの署名には使いません。

winapp cert generate --manifest ./Package.appxmanifest
winapp cert install ./devcert.pfx
winapp sign ./MyApp.msix ./devcert.pfx

winapp sign は、署名するファイルと証明書の2つを位置引数で受け取ります。v0.6.1のusage.mdには --cert で証明書を渡す例が載っていましたが、v0.6.1の時点でも実装（SignCommand.cs）は位置引数でした。v0.8.0は未知のオプションをエラーにするため、古い例を写すと失敗します。証明書を渡すオプション --cert があるのは pack のほうです。

配布用の署名にローカルのPFXを使いたくない場合は、Azure Trusted Signingを使う winapp az-sign があります。Azure側の署名アカウントと証明書プロファイルのほか、端末にx64版.NET 8以降のランタイムとVisual C++再頒布可能パッケージ（x64）が必要です。winappを入れただけではこの2つは揃いません。

Microsoft Storeへの提出

winapp store は、Microsoft Store Developer CLI（msstore）が未取得ならダウンロードし、引数をそのまま msstore へ渡すコマンドです。提出の処理と使えるサブコマンドは msstore 側の仕様に従います。

winapp store publish ./myapp.msix --appId <your-app-id>

Partner Centerのアカウント作成、アプリ登録、審査は従来どおり必要です。

winapp uiによる実行中アプリの検査・操作

winapp ui は、Windows UI Automation（UIA）を通じて実行中のアプリを検査・操作するコマンド群です。v0.8.0のサブコマンドは22個で、v0.7.0で他の winapp ui に操作の順番を譲る yield が加わりました。対象はWinUI 3・WPF・WinForms・Win32・Electronのいずれでも構いません。UIAそのものの仕組みはUIAutomationの解説記事で扱っています。

winapp ui inspect -a notepad
winapp ui search Button -a notepad
winapp ui invoke Close -a notepad
winapp ui screenshot -a notepad

対象アプリの指定は -a で、プロセス名・ウィンドウタイトル・PIDのどれでも構いません。v0.8.0では、1要素を対象にするコマンドすべてに --type・--root・--class-name が付き、click と hover に座標指定の --at x,y が加わりました。

CIで使える動詞と使えない動詞

サブコマンドは、UIAのパターン経由で操作するものと、OSレベルの入力を合成するものに分かれます。ロックされた画面のCIランナーで動くのは前者だけです。

send-keys の既定は対象ウィンドウのメッセージキューへ直接送る方式で、前面に出す必要がありません。ただしWinUI 3やUWPのXAMLコントロールは子ウィンドウを持たないため、この方式ではキーが届かず、警告を出したうえで終了コード0で終わります。テストが成功に見えるので注意が必要です。CIでWinUI 3の入力を試すなら、set-value や invoke で置き換えられないかを先に検討します。

Windows Sandboxでのアプリ実行と前提条件

v0.7.0からは、ホストでビルドしたアプリをWindows Sandbox内で登録・起動し、そのまま winapp ui で操作できます。v0.7.0以降の target コマンドはSandbox内でのコマンド実行やファイルのコピー、デスクトップ全体の画面取得を担います。

winapp target snapshot sandbox
winapp run . --on sandbox --detach
winapp ui inspect --on sandbox -a MyApp
winapp target exec sandbox -- dotnet --info

前提は、対応エディションのWindows 11 24H2以降、ハードウェア仮想化の有効化、Windows Sandbox機能の有効化です。winappは機能の有効化もWindowsの再起動も行わないため、事前に自分で設定します。target snapshot を使えば、Sandboxを起動せずに前提がそろっているかを確認できます。

Sandboxで隔離されるのは実行環境だけです。公式のSandbox実行ガイドは、プロジェクトの評価・復元・コンパイルはホストで走るため、信頼できないプロジェクトのビルドが安全になるわけではないと明記しています。Windowsで同時に動かせるSandboxは1つだけで、中のアプリはユーザー・レジストリ・ネットワークを共有します。

WinUI 3専用のdevtoolsとperf

v0.8.0で追加された2つのコマンドは、どちらもWinUI 3アプリが対象です。

winapp devtools は、実行中のWinUI 3アプリのXAMLツリーを調べ、プロパティをその場で書き換え、バインディングの問題を診断します。要素にコメントを残しておくと、AIエージェントが winapp devtools comments list で読み取り、コードの修正に使えます。WinUIプロジェクトを winapp run で起動すると既定でツールバーが出ます。止めるには --devtools off を付けるか、winapp config set run.devtools off でユーザー単位の既定を変えます。インスペクターのウィンドウはWindows App SDK 1.7以降が必要です。CI環境（CI 変数あり）・--on sandbox・ビルド出力フォルダーの起動では自動では起動しません。

winapp perf は、WinUI 3のレイアウト・描画・入力・スクロールをETWで記録し、UIスレッドの重い処理やXAMLリソースを順位付けします。

winapp run . --profile .\traces\startup --detach
winapp perf stop <キャプチャID>
winapp perf analyze .\traces\startup --json

解析は記録を止めてから行います。キャプチャIDは run が返します。記録の既定は30秒・生データ512MiBまでで、--profile-duration-sec（1〜300）と --profile-max-size-mib（1〜1024）で変えられます。記録はローカル実行のときだけ使え、--on sandbox とは併用できません。

AIコーディングエージェント向けの検索機能とプラグイン

v0.8.0の find-ui と find-api は、AIエージェントが推測でコードを書かないための検索コマンドです。どちらも --json で機械可読の結果を返します。

• find-ui：WinUI 3 GalleryとWindows Community Toolkitから、動くXAMLとC#の例を探します。WPFやWinFormsは対象外です。v0.7.0から検索データが本体に同梱され、ネットワークが無くても動きます。GitHubに届く環境では最大24時間ごとに更新します。
• find-api（v0.7.0で追加）：プロジェクトが参照する .winmd／.dll から、使えるWindows Runtime APIの型・メンバー・列挙を検索します。初回にプロジェクトの復元結果から索引を作るため、先に winapp restore か dotnet restore を実行しておきます。

リポジトリはエージェント用のプラグインを2つ配布しています。winappのコマンドと手順を扱う winappcli と、WinUI 3アプリの作成・パッケージ化・テストを扱う winui です。GitHub Copilot CLI・Claude Code・Codexの各マーケットプレイスに、リリースのたびに公開されます。Claude Codeでの入れ方は次のとおりです（Codexでは install の代わりに add を使います）。

claude plugin marketplace add microsoft/WinAppCli
claude plugin install winappcli@winappcli
claude plugin install winui@winappcli

Claude Codeのプラグインの仕組みと選び方は、Claude Codeのおすすめ拡張機能（プラグイン）の記事にまとめています。

Electron・Node.js専用のnodeコマンド

node 配下の4コマンドはnpmパッケージでのみ使え、WinGetで入れたCLIには現れません。

JSバインディングを使うと、ファイルピッカー、通知、オンデバイスLLMのPhi Silica、Windows MLによるONNXモデルの実行をJavaScriptから呼べます。Phi SilicaにはCopilot+ PCと、マニフェストでの systemAIModels の宣言が必要です。v0.8.0のElectron導入ガイドには、sparseパッケージでIDを付けたElectronアプリが起動直後に落ちる、または画面が白くなる既知の問題が残っています。開発中に限り、起動スクリプトへ --no-sandbox を足す回避策が案内されています。

v0.6.1からv0.8.0までの変更点

v0.6.1以降の主な追加機能を、v0.7.0・v0.7.1・v0.8.0のGitHubのリリース日（UTC）とあわせて並べます。

流れとしては、v0.7でAIエージェントとSandboxの土台を作り、v0.8でWinUI 3の検査と性能測定を足した形です。v0.6.1までの記事や社内手順書がある場合は、find-ui の更新間隔（7日から24時間へ）と、winapp sign の書き方の2点を見直してください。

winapp CLIを採用すべき場面と避ける場面

採用を勧めるのは次の場面です。

• Visual Studioを使わずにWinUI 3アプリを作る場面。VS CodeやAIエージェントから new・run・pack だけで開発を回せます。
• Electron・Tauri・Flutterのアプリに通知やオンデバイスAIを足す場面。パッケージIDの付与とMSIX化の手作業が減ります。
• パッケージIDが必要なAPIを開発中に試す場面。まず既存アプリの検証用exeに create-debug-identity でIDを付けると、ビルド構成を変えずに評価できます。

一方、本番の配布パイプラインの中核に据えるのはまだ早いと判断します。READMEは「experimental and in active development」と明記しており、v0.6.1からv0.8.0までの約11週間で、find-api・target・devtools・perf・config の5コマンドが増えました。macOSやLinuxのランナーでは動かないため、クロスプラットフォームのCIではWindowsランナーを分ける必要があります。Windows向けの業務アプリを新たに作る場合、どのフレームワークと配布方式を選ぶかで保守費が変わります。判断に迷う場合は業務用・Webアプリ開発の支援もご相談いただけます。

よくある質問

winapp CLIとwinappcliは別のツールですか？

同じツールです。正式名はWindows App Development CLI、実行コマンドは winapp、npmパッケージは @microsoft/winappcli、WinGetのIDは Microsoft.winappcli です。呼び方が配布経路ごとに違うだけです。

winapp CLIはVisual Studioの代わりになりますか？

WinUI 3アプリの作成からパッケージ化までは、Visual Studioを開かずに行えます。ただしC++のビルドにはVisual Studio 2022 version 17.8以降かBuild Toolsが必要で、エディタやデバッガーを置き換えるツールではありません。

winapp CLIとWindows App SDKは何が違いますか？

Windows App SDKは、WinUI 3や通知、オンデバイスAIなどのAPIを提供するライブラリとランタイムです。winapp CLIはそれを使う側の道具で、SDKのダウンロードと版の管理（init・restore・update）、起動時に必要なWindows App Runtimeの導入、パッケージ化を受け持ちます。

winapp CLIは無料で使えますか？

MITライセンスのオープンソースで、無料で使えます。ただしPublic Previewのため、コマンドは正式版までに変わる可能性があります。az-sign で使うAzure Trusted Signingの利用料はAzure側で別にかかります。

開発用証明書を作るコマンドは何ですか？

winapp cert generate です。cert 配下には generate・info・install の3つがあり、cert create はありません。v0.7.0からは cert install が公開鍵だけの .cer も受け付けます。

関連記事

• WinUI 3とは？WPFとの違い・将来性・弱点と始め方【Windows App SDK 2.5】
• UIAutomationとは｜Windows UI自動化の仕組みとC#・Python・VBA実装【2026年版】
• Electronはオワコンか？採用状況・将来性とUIの作り方【Electron 45で実測】
• WPFとは？2026年も現役か・WinFormsやWinUI 3との違いと.NET 10での使い方
• .NET MAUIの将来性は？サポート期限・Xamarin後継・Flutter比較と.NET 11の変化