winapp-cli

Windows アプリ開発 CLI

winapp は、Windows を対象とするあらゆるフレームワーク（.NET/csproj、C++、Electron、Rust、Tauri、Flutter など）向けに、Windows SDK、MSIX パッケージング、アプリの ID、マニフェスト、証明書、署名、ストアへの公開、UI オートメーションを管理します。パブリックプレビュー版のため、内容は変更される可能性があります。

前提条件

• Windows 10 以降
• 次のいずれかの方法でインストールします。
  • WinGet：winget install Microsoft.WinAppCli --source winget
  • npm（Electron/Node）：npm install @microsoft/winappcli --save-dev
  • CI：setup-WinAppCli GitHub Action
  • 手動：GitHub Releases

コマンド

コマンド	用途
init	プロジェクトを初期化します。SDK（stable／preview／experimental／none）、マニフェスト、winapp.yaml を設定します。.csproj プロジェクトでは winapp.yaml を省略し、NuGet を直接使用します。 証明書は自動生成されません（v0.2.0 以降）。
restore / update	SDK パッケージのバージョンを復元または更新します（プレビュー SDK には --setup-sdks preview を指定します）。
pack <dir>	MSIX をビルドします。フラグ：--generate-cert、--cert <pfx> --cert-password、--self-contained（WinAppSDK ランタイムをバンドル）、--output。.winmd からサードパーティの WinRT コンポーネントを自動検出します（v0.2.1 以降）。
run <dir> [-- <app args>]	ルースレイアウトとしてパッケージ化し、パッケージ化されたアプリとして起動します。MSIX を作成せずに IDE の F5 デバッグを行うのに最適です。-- による引数のパススルーに対応しています（v0.3.1 以降）。 （v0.3.0 以降）
create-debug-identity <exe>	exe にスパースパッケージ ID を追加します。完全なパッケージ化を行わずに、ID が必要な API（通知、Windows AI、シェル統合）を呼び出せるようになります。
unregister	run／create-debug-identity によって登録されたサイドロード開発者パッケージを削除します。
manifest	AppxManifest.xml を生成します。プレースホルダーと修飾名に対応しています。manifest update-assets <image> は、1 つのソース（PNG または SVG）から必要なアイコンサイズをすべて生成します（v0.2.1 以降）。
cert generate / install / info	開発用証明書を管理します。cert info <pfx> --password <pwd> はサブジェクト／発行者／有効期間を表示します。--export-cer は公開鍵をエクスポートします。generate と info では --json を使用できます。（v0.2.1 以降）
sign <target> --cert <pfx>	MSIX または exe に署名します。タイムスタンプサーバーも指定できます。
tool	パスを設定した状態で Windows SDK のビルドツールを実行します。
store	Microsoft Store Developer CLI を実行して、ストアへの提出／検証／公開を行います。
create-external-catalog	TrustedLaunch スパースパッケージ用の CodeIntegrityExternal.cat を生成します。
ui list-windows / inspect / click / search / wait-for / get-focused	Microsoft UI Automation による UI オートメーションです。すべて --json に対応しています。inspect、get-focused、search、wait-for の JSON エンベロープは v0.3.1 で変更されました。詳しくは references/ui-json-envelope.md を参照してください（その他の ui サブコマンドの出力は v0.3.1 より前の形式のままです）。（v0.3.0 以降）
node create-addon / add-electron-debug-identity / clear-electron-debug-identity	Electron/Node 用ヘルパーです。すべてのコマンドは、@microsoft/winappcli の型付き JS/TS 関数としても利用できます（v0.2.1 以降）。

CI のヒント：--no-prompt を指定すると、対話型プロンプトを省略できます。

ワークフロー

標準的な初期化からパッケージ化までの流れ：

1. アプリのフォルダーでプロジェクトを初期化します。SDK 参照、マニフェスト、winapp.yaml を設定します（.csproj プロジェクトでは YAML を省略し、NuGet を直接設定します）。

   winapp init        # add --no-prompt in CI
   

2. 開発用署名証明書を生成します — サイドローディングに必要です。init は .csproj 以外のプロジェクトでは証明書を作成しなくなりました（v0.2.0 以降）。後続の手順で参照できるよう、出力パスを固定します。

   winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx --install
   

3. フレームワーク独自のツールチェーン（dotnet build、npm run build、cargo build など）でアプリをビルドします。

4. 手順 2 の証明書で署名し、MSIX としてパッケージ化します。

   winapp pack ./build-output --cert ./mycert.pfx --cert-password password --output MyApp.msix
   

5. 配布前に、（任意）製品版証明書で再署名します。

   winapp sign MyApp.msix --cert ./prod.pfx --cert-password $env:CERT_PWD
   

6. winapp store …（Store Developer CLI のラッパー）を使用して、（任意）Microsoft Store に提出します。

代替フロー

• パッケージ化せずに ID ゲート付き API をデバッグする (通知、Windows AI、シェル):

  winapp create-debug-identity ./bin/MyApp.exe
  ./bin/MyApp.exe
  

• IDE の F5 用にパッケージアプリとして実行する (ルーズレイアウト、アプリ引数は -- の後):

  winapp run ./bin/Debug/net10.0-windows10.0.26100.0/win-x64 \
    --manifest ./appxmanifest.xml -- --my-flag value
  

• Electron:

  npx winapp init
  npx winapp node add-electron-debug-identity
  npx winapp pack ./out --output MyElectronApp.msix
  

注意点

• winapp ui --json のエンベロープは v0.3.1 で再形成されました — ui inspect、ui get-focused、ui search、ui wait-for は新しい形状を使用します。要素ごとの id / parentSelector / windowHandle は削除されました (selector を使用してください)。完全なスキーマは references/ui-json-envelope.md にあります。
• winapp init は証明書を自動生成しなくなりました (v0.2.0 以降) — winapp cert generate を明示的に実行してください。以前の --no-cert フラグは削除されました。
• .csproj プロジェクトは winapp.yaml をスキップします — SDK パッケージはプロジェクトファイルにあります。ハイブリッド構成では調整が必要です。
• %userprofile%/.winapp/packages ではなく NuGet グローバルキャッシュ (v0.2.0 以降) — 古いフォルダに依存するスクリプトは壊れます。
• マニフェストを変更した後は create-debug-identity を再実行してください — ID は登録時にバインドされます。

トラブルシューティング

問題	修正
証明書が信頼されていない	winapp cert install <pfx> でローカルマシンストアに追加します
ID ゲート付き API が失敗する	マニフェスト変更後に create-debug-identity を再実行します
SDK が見つからない	winapp restore または winapp update
run / create-debug-identity の登録エラー 0x800704EC	開発者モードがオフです — 設定 → プライバシーとセキュリティ → 開発者向け で有効にするか (Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -Name AllowDevelopmentWithoutDevLicense -Value 1)、その後再試行します
run / create-debug-identity の登録エラー 0x80073CFB	パッケージが競合する ID で既に登録されています — winapp unregister を実行するか (別のプロジェクトツリーから登録されている場合は winapp unregister --force)、その後再試行します

参考

• winapp CLI リポジトリ · 完全な使用ドキュメント · .NET ガイド · サンプル
• Windows App SDK · MSIX の概要 · パッケージ ID の概要