Reorder root help around the app development workflow by niels9001 · Pull Request #987 · microsoft/winappCli

Niels Laute (niels9001) · 2026-10-05T13:16:30Z

Description

Reorders the winapp --help screen to follow the app development workflow (create, run, debug, discover, test, then package) and updates the root description to match.

Before this change, "Packaging & Signing" was the second group, directly under Setup. run was in the middle of "Development Tools", and low-level identity tools were mixed in with everyday commands.

New groups, in order

Group	Commands
Get Started	`new`, `init`, `restore`, `update`
Run & Debug	`run`, `create-debug-identity`, `unregister`, `target`
Discovery	`find-ui`, `find-api`
UI Automation	`ui`
Package, Sign & Publish	`package`, `manifest`, `cert`, `sign`, `az-sign`, `store`
Advanced	`embed-identity`, `create-external-catalog`, `tool`, `get-winapp-path`

Root description

Before: "CLI for Windows app development, including package identity, packaging, managing Package.appxmanifest, test certificates, Windows (App) SDK projections, and more. For use with any app framework targeting Windows"
After: "Create, run, debug, test, and package Windows apps from the command line. Works with WinUI and any other (cross-platform) app framework targeting Windows, and manages Windows SDKs, package identity, manifests, and certificates."
The root ShortDescription is updated to match.

Other changes

Removes the trailing periods from the run and unregister short descriptions, so all help rows are consistent.
Regenerates docs/cli-schema.json with build-cli.ps1 -OnlyDocs.
No command names, options, or behavior change.

Usage Example

winapp --help

Related Issue

Related to #986 (docs and README refocus on WinUI developers)

Type of Change

✨ New feature
📝 Documentation

Checklist

Tested locally on Windows:
- dotnet test --project src/winapp-CLI/WinApp.Cli.Tests/WinApp.Cli.Tests.csproj --filter "FullyQualifiedName~CustomHelpTests|FullyQualifiedName~CliSchemaTests|FullyQualifiedName~CompleteCommandTests|FullyQualifiedName~WinAppParserConfigurationTests" passed (42 tests).
- scripts/build-cli.ps1 -OnlyDocs passed.

Screenshots / Demo

 Create, run, debug, test, and package Windows apps from the command line. Works
 with WinUI and any other (cross-platform) app framework targeting Windows, and manages Windows
 SDKs, package identity, manifests, and certificates.

 ┌─Get Started──────────────┐
 │  new, init, restore, ... │
 ├─Run & Debug──────────────┤
 ├─Discovery────────────────┤
 ├─UI Automation────────────┤
 ├─Package, Sign & Publish──┤
 └─Advanced─────────────────┘

Additional Notes

The category order only affects the root help screen. Subcommand help still uses the default renderer.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-10-05T14:11:23Z

Build Metrics Report

Validation passed. All required build and validation jobs succeeded.

Binary Sizes

Artifact	Baseline	Current	Delta
CLI (ARM64)	57.42 MB	57.42 MB	📈 +3.0 KB (+0.01%)
CLI (x64)	57.46 MB	57.46 MB	📈 +3.0 KB (+0.01%)
MSIX (ARM64)	23.85 MB	23.86 MB	📈 +3.3 KB (+0.01%)
MSIX (x64)	25.32 MB	25.32 MB	📈 +0.7 KB (+0.00%)
NPM Package	49.75 MB	49.76 MB	📈 +3.9 KB (+0.01%)
NuGet Package	49.85 MB	49.86 MB	📈 +6.9 KB (+0.01%)

.NET Test Results (TRX reports)

Other suites are reflected in the overall validation status above.

✅ 8062 passed, 37 skipped out of 8099 tests in 1466.1s (+10 tests, +277.1s vs. baseline)

Test Coverage

✅ 86.4% line coverage, 81% branch coverage · ✅ no change vs. baseline

CLI Startup Time

65ms 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))) 987

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 987

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

Updated 2026-10-06 17:48:28 UTC · commit 66b4425 · workflow run

Root help and every subcommand's help listed --on, including commands that reject it. Keep a hidden recursive --on on the root so every command still parses (and rejects) it, and attach the visible option only to target-aware commands (run, unregister, ui). The CLI schema now lists --on on those commands, so the npm generator no longer needs its own target-aware list. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Copilot review overview

🟡 Changes recommended

The intended help ordering lacks regression coverage, and the user-visible --on change contradicts the stated PR scope.

Review effort: Balanced
Findings: 1 · 1

Open (2)

Document or remove unrelated --on surface changes · New
Assert intended root-help category and command order · New

What changed in this PR

Reorders root help around the app-development workflow and changes where --on is advertised.

Changes:

Reorders and renames root help categories and descriptions.
Exposes --on only on target-aware commands.
Regenerates CLI schema and npm documentation.

File	Description
`src/winapp-npm/src/winapp-commands.ts`	Regenerates wrappers for relocated `--on`.
`src/winapp-npm/scripts/generate-commands.mjs`	Simplifies recursive-option generation.
`src/winapp-CLI/WinApp.Cli/Telemetry/Events/CommandInvokedEvent.cs`	Recognizes both selector declarations.
`src/winapp-CLI/WinApp.Cli/Commands/WinAppRootCommand.cs`	Reorders help and relocates `--on`.
`src/winapp-CLI/WinApp.Cli/Commands/UnregisterCommand.cs`	Normalizes short description.
`src/winapp-CLI/WinApp.Cli/Commands/RunCommand.cs`	Normalizes short description.
`src/winapp-CLI/WinApp.Cli/Commands/ExecutionTargetSelection.cs`	Splits visible and hidden selector options.
`src/winapp-CLI/WinApp.Cli.Tests/TargetSelectionParserTests.cs`	Tests selector placement.
`src/winapp-CLI/WinApp.Cli.Tests/ExecutionTargetSelectionTests.cs`	Tests selector visibility.
`src/winapp-CLI/WinApp.Cli.Tests/CustomHelpTests.cs`	Updates category-name assertion.
`docs/npm-usage.md`	Regenerates npm API documentation.
`docs/cli-schema.json`	Regenerates CLI schema.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+        Options.Add(ExecutionTargetSelection.UnsupportedOnOption);
+
+        foreach (var targetAwareCommand in Subcommands.OfType<ITargetAwareCommand>().Cast<Command>())
+        {
+            targetAwareCommand.Options.Add(ExecutionTargetSelection.OnOption);


+            ("Get Started", [typeof(NewCommand), typeof(InitCommand), typeof(RestoreCommand), typeof(UpdateCommand)]),
+            ("Run & Debug", [typeof(RunCommand), typeof(CreateDebugIdentityCommand), typeof(UnregisterCommand), typeof(TargetCommand)]),
+            ("Discovery", [typeof(FindUiCommand), typeof(FindApiCommand)]),
+            ("UI Automation", [typeof(UiCommand)]),
+            ("Package, Sign & Publish", [typeof(PackageCommand), typeof(ManifestCommand), typeof(CertCommand), typeof(SignCommand), typeof(AzSignCommand), typeof(MSStoreCommand)]),
+            ("Advanced", [typeof(EmbedIdentityCommand), typeof(CreateExternalCatalogCommand), typeof(ToolCommand), typeof(GetWinappPathCommand)])


Niels Laute (niels9001) and others added 2 commits October 5, 2026 15:16

Reorder root help around the app development workflow

5e95a34

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Mention cross-platform frameworks in root description

0da54d9

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Nikola Metulev (nmetulev) and others added 2 commits October 6, 2026 09:27

Merge branch 'main' into niels9001/cli-help-order

d998c46

Nikola Metulev (nmetulev) approved these changes Oct 6, 2026

View reviewed changes

Nikola Metulev (nmetulev) marked this pull request as ready for review October 6, 2026 18:11

Copilot AI balanced review requested due to automatic review settings October 6, 2026 18:11

Nikola Metulev (nmetulev) merged commit 831eeb3 into main Oct 6, 2026
38 checks passed

Nikola Metulev (nmetulev) deleted the niels9001/cli-help-order branch October 6, 2026 18:11

Copilot started reviewing on behalf of Nikola Metulev (nmetulev) October 6, 2026 18:12

View session

Copilot AI reviewed Oct 6, 2026

View reviewed changes

Navigation Menu

Repository navigation

Reorder root help around the app development workflow - #987

Reorder root help around the app development workflow#987
Nikola Metulev (nmetulev) merged 4 commits into
mainfrom
niels9001/cli-help-order

Niels Laute (niels9001) commented Oct 5, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Niels Laute (niels9001) commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Usage Example

Related Issue

Type of Change

Checklist

Screenshots / Demo

Additional Notes

Uh oh!

github-actions Bot commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Build Metrics Report

Binary Sizes

.NET Test Results (TRX reports)

Test Coverage

CLI Startup Time

Try This Build

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Niels Laute (niels9001) commented Oct 5, 2026 •

edited

Loading

github-actions Bot commented Oct 5, 2026 •

edited

Loading