[Nikola Metulev (nmetulev)]

What and why

winapp --help used to open with a "Start here" block that only pointed to ui and devtools. Those are advanced features, while the first steps (new, init, run, package) only appeared further down, in the command panels. The help page of each command was a different problem: a long description line, then an ungrouped wall of options.

Root help now opens with a Quick start of four workflows: build a WinUI app, add winapp to an existing app, package for install, and automate any app's UI. Each step is a real command with a few words on what it does. An All commands: heading introduces the full list below it, so every command is still listed.

• Seven panels become four. Get Started and Run & Debug merge into Set Up & Run. Discovery, UI Automation and Performance merge into Develop & Test.
• About 11 command short descriptions are shorter, so no row wraps at 80 columns.
• The npm wrapper (npx winapp --help) adds an Electron quick start, because Electron uses the wrapper's node commands instead of winapp run.

Every other command's --help now uses one layout: a summary, a short explanation, usage, examples, arguments, subcommands, and options.

• Color, in a terminal only: headings are blue, commands and options bright white, and <placeholders> grey. Text after the first sentence of a description is grey, so you can skim, and multi-line entries get a blank line between them. Piped output, which agents read, stays plain text with no extra lines.
• run, package and init get described examples that can use other commands. For example, package starts with winapp cert generate and ends with Add-AppxPackage. Their options are grouped by purpose, for example run's Build, Launch, Package layout, and Debug and profile groups. Long placeholders are shorter: -c <name>, -f <tfm>, --exe <path>.
• Command groups such as cert, config and manifest list their subcommands. The help pages that used the old default layout still show option defaults, allowed values (--if-exists <Error|Overwrite|Skip>), (REQUIRED) markers, and arguments store and tool pass through.
• ui and devtools pages: unchanged when piped.

Six run/package option descriptions drop internal detail. For example, --debug-output no longer explains the WINAPP_DBGTOOLS_DIR variable. --cli-schema shows the same shorter text. The CLI still rejects the combinations they no longer mention, with a clear error.

Before / after

Root help, before

Root help, after (top of the page)

winapp run --help, before (the options in an 88-column terminal)

winapp run --help, after, piped (the plain text agents read)

In a terminal: winapp cert --help, and the end of winapp package --help

After: the command panels below Quick start

 All commands:

 ┌─Set Up & Run───────────────────────────────────────────────────────────────┐
 │  new                    Create a new WinUI app                             │
 │  init                   Add a manifest and SDK packages to a project       │
 │  restore                Restore SDK packages for an initialized project    │
 │  update                 Update packages in winapp.yaml                     │
 │  run                    Run an app from a project, .cs file, or folder     │
 │  create-debug-identity  Add package identity to an exe for debugging       │
 │  unregister             Unregister a sideloaded development package        │
 │  target                 Run commands and copy files on an execution target │
 └────────────────────────────────────────────────────────────────────────────┘

 ┌─Develop & Test────────────────────────────────────────────────────┐
 │  find-ui   Search WinUI controls and samples for working code     │
 │  find-api  Search the Windows APIs your project references        │
 │  devtools  Inspect and live-edit a running WinUI app's XAML       │
 │  ui        Inspect and interact with running Windows app UIs      │
 │  perf      Record WinUI timings, GC context, and process counters │
 └───────────────────────────────────────────────────────────────────┘

 ┌─Package, Sign & Publish─────────────────────────────────┐
 │  package   Create MSIX package or bundle                │
 │  manifest  Create and modify Package.appxmanifest files │
 │  cert      Development certificates for code signing    │
 │  sign      Code-sign an MSIX package or executable      │
 │  az-sign   Code-sign a file using Azure Trusted Signing │
 │  store     Run a Microsoft Store Developer CLI command  │
 └─────────────────────────────────────────────────────────┘

 ┌─Advanced───────────────────────────────────────────────────────────────────┐
 │  embed-identity           Add sparse package identity to an app's manifest │
 │  create-external-catalog  Create CodeIntegrityExternal.cat (TrustedLaunch) │
 │  tool                     Run Windows SDK tools (makeappx, signtool, etc.) │
 │  get-winapp-path          Print the path to the global .winapp directory   │
 │  config                   Show or change your per-user winapp settings     │
 └────────────────────────────────────────────────────────────────────────────┘

npm wrapper, appended after the existing Node.js section:

Electron quick start:
  npx winapp init                              add a manifest and Windows SDKs
  npx winapp node add-electron-debug-identity  run with package identity
  npx winapp node create-addon                 call Windows APIs from a native addon

Not tested / risks

• I didn't run npx winapp --help end to end. I ran the npm unit tests (346 passed), including the one for the init --help wrapper option, which now prints under its own npm wrapper heading.
• Colors appear only where winapp already uses them: Windows Terminal or VS Code, with UTF-8 output that isn't piped. Other terminals get the plain layout.
• Quick start and the examples are hand-written. To keep them from going stale, tests parse every winapp line in them against the real CLI and fail on a misspelled command or option. Add-AppxPackage and npx lines aren't checked.

Checklist

• Tests added or updated: CompactCommandHelpTests covers several things. Every command's help lists its subcommands and options and fits 88 columns. Colored help has the same text as plain help. Defaults, allowed values, (REQUIRED) and argument shapes are kept, and the ui pages are unchanged. Every option is in one group, and every example parses. RootHelp_* covers the Quick start. Command: dotnet run --project src\winapp-CLI\WinApp.Cli.Tests\WinApp.Cli.Tests.csproj -c Release --no-build -- --filter "FullyQualifiedName~CompactCommandHelpTests|FullyQualifiedName~UiHelpTests|FullyQualifiedName~CustomHelpTests|FullyQualifiedName~DevToolsHelpTests|FullyQualifiedName~TargetSelectionParser|FullyQualifiedName~ConfigCommandTests|FullyQualifiedName~UiCommandTests|FullyQualifiedName~Perf". Result: passed, 1370 total and 0 failed. The full suite locally: every failure was environmental (nuget.org blocked on a corp machine, native test fixture not built, npm dist not built).
• Tested locally on Windows: Release build with 0 warnings, and the help rendered in Windows Terminal as shown above.
• Docs, samples, and plugins/winapp/skills/: none quote the help output or the changed descriptions. docs\usage.md keeps the full detail for the shortened options.

Notes for reviewers

• Quick start shows ui and devtools as --help on purpose. Those help pages are curated guides for agents (Agent-first winapp ui help and unknown-command suggestions #942, WinUI DevTools: inspect, comment on and live-edit a running WinUI app #943).
• package says <.csproj|folder> because it doesn't accept a .vcxproj, while run does ([Feature]: winapp package should accept a C++ .vcxproj like winapp run does #1115).
• Colors are raw terminal codes written only when BannerHelper.UseEmoji is true. Widths are computed on the plain text, so the layout is identical with and without color.
• The new placeholder names (HelpName) contain no |. The npm generator turns | into a TypeScript union type, so these don't change the npm API.
• restore now reads "Restore SDK packages for an initialized project". .NET projects set up by init have no winapp.yaml.

[Copilot]

🟡 Changes recommended

The WinUI Quick start omits entering the generated project directory, causing its next command to target the wrong folder.

1 open finding

• Enter generated project before running it · New

What changed in this PR

Root help now introduces common workflows before the full command list, making setup and everyday tasks easier to find.

Changes:

• Adds native CLI and Electron Quick start examples.
• Consolidates command panels and shortens descriptions.
• Tests Quick start placement and command parsing.

File	Description
src/​winapp-npm/​src/​cli.ts	Adds Electron Quick start.
src/​winapp-CLI/​WinApp.Cli/​Helpers/​CustomHelpAction.cs	Renders workflow examples before commands.
src/​winapp-CLI/​WinApp.Cli/​Commands/​WinAppRootCommand.cs	Consolidates command panels.
src/​winapp-CLI/​WinApp.Cli/​Commands/​ToolCommand.cs	Shortens tool description.
src/​winapp-CLI/​WinApp.Cli/​Commands/​RunCommand.cs	Shortens run description.
src/​winapp-CLI/​WinApp.Cli/​Commands/​RestoreCommand.cs	Revises restore description.
src/​winapp-CLI/​WinApp.Cli/​Commands/​PerfCommand.cs	Shortens performance description.
src/​winapp-CLI/​WinApp.Cli/​Commands/​InitCommand.cs	Simplifies initialization description.
src/​winapp-CLI/​WinApp.Cli/​Commands/​FindUiCommand.cs	Simplifies control-search description.
src/​winapp-CLI/​WinApp.Cli/​Commands/​FindApiCommand.cs	Simplifies API-search description.
src/​winapp-CLI/​WinApp.Cli/​Commands/​EmbedIdentityCommand.cs	Shortens identity description.
src/​winapp-CLI/​WinApp.Cli/​Commands/​DevToolsCommand.cs	Shortens live-inspection description.
src/​winapp-CLI/​WinApp.Cli/​Commands/​CreateExternalCatalogCommand.cs	Shortens catalog description.
src/​winapp-CLI/​WinApp.Cli/​Commands/​CreateDebugIdentityCommand.cs	Simplifies debug-identity description.
src/​winapp-CLI/​WinApp.Cli.Tests/​UiHelpTests.cs	Checks workflow rendering and parsing.

🧠 Review effort: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

⏳ Build in progress — metrics below are from a previous commit and will update when the current build finishes.

Build Metrics Report

Validation passed. All required build and validation jobs succeeded.

Binary Sizes

Artifact	Baseline	Current	Delta
CLI (ARM64)	64.74 MB	64.78 MB	📈 +37.5 KB (+0.06%)
CLI (x64)	64.68 MB	64.72 MB	📈 +36.5 KB (+0.06%)
MSIX (ARM64)	26.80 MB	26.82 MB	📈 +25.0 KB (+0.09%)
MSIX (x64)	28.40 MB	28.43 MB	📈 +32.4 KB (+0.11%)
NPM Package	55.85 MB	55.88 MB	📈 +32.3 KB (+0.06%)
NuGet Package	55.98 MB	56.01 MB	📈 +28.7 KB (+0.05%)

.NET Test Results (TRX reports)

Other suites are reflected in the overall validation status above.

✅ 10517 passed, 43 skipped out of 10560 tests in 1727.1s (+18 tests, -713.9s vs. baseline)

Test Coverage

✅ 87.3% line coverage, 81.5% branch coverage · ✅ no change vs. baseline

CLI Startup Time

79ms median (x64, winapp --version) · ✅ no change vs. baseline

Try This Build

Installs the MSIX for your architecture, replacing any previously installed build. Needs the GitHub CLI — the command offers to install it and sign you in if it is missing.

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) 1116

Switching between builds often?

Put the tool on your PATH once:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) -AddToPath

Then this build is just:

winapp-pr 1116

Run winapp-pr with no arguments to pick from a list of open PRs.

---

Updated 2026-10-16 23:15:10 UTC · commit 74061cf · workflow run