Wrong documentation or argument order

[danielniccoli]

Brief description of your issue

Actual command syntax does not reflect documentation.

Command help winget list --help shows:

Windows Package Manager (Preview) v1.4.2161-preview
Copyright (c) Microsoft Corporation. All rights reserved.

The list command displays the packages installed on the system, as well as whether an update is available. Additional options can be provided to filter the output, much like the search command.

usage: winget list [[-q] <query>] [<options>]

The following command aliases are available:
  ls

The following arguments are available:
  -q,--query                  The query used to search for a package

The following options are available:
  --id                        Filter results by id
  --name                      Filter results by name
  --moniker                   Filter results by moniker
  -s,--source                 Find package using the specified source
  --tag                       Filter results by tag
  --cmd,--command             Filter results by command
  -n,--count                  Show no more than specified number of results (between 1 and 1000)
  -e,--exact                  Find package using exact match
  --header                    Optional Windows-Package-Manager REST source HTTP header
  --accept-source-agreements  Accept all source agreements during source operations

More help can be found at: https://aka.ms/winget-command-list

Note the argument order: winget list [[-q] <query>] [<options>]

Using this command syntax, I get an error:

PS C:\> winget list Element.Element --id
Windows Package Manager (Preview) v1.4.2161-preview
Copyright (c) Microsoft Corporation. All rights reserved.

Argument value required, but none found : '--id'

Steps to reproduce

To show the help: winget list --help

Write a query according to the usage in the help: winget list Element.Element --id

Expected behavior

Proper results. For example:

Name    Id              Version Available Source
------------------------------------------------
Element Element.Element 1.11.5            winget
Element Element.Element 1.10.1  1.11.5    winget

Actual behavior

Error Argument value required, but none found : '--id'

Environment

Windows Package Manager (Preview) v1.4.2161-preview
Copyright (c) Microsoft Corporation. All rights reserved.

Windows: Windows.Desktop v10.0.22000.978
System Architecture: X64
Package: Microsoft.DesktopAppInstaller v1.19.2161.0

Logs: %LOCALAPPDATA%\Packages\Microsoft.DesktopAppInstaller_8wekyb3d8bbwe\LocalState\DiagOutputDir

Links               
---------------------------------------------------------------------------
Privacy Statement   https://aka.ms/winget-privacy
License Agreement   https://aka.ms/winget-license
Third Party Notices https://aka.ms/winget-3rdPartyNotice
Homepage            https://aka.ms/winget
Windows Store Terms https://www.microsoft.com/en-us/storedocs/terms-of-sale

[denelon]

@JohnMcPMS any ideas on this one?

[JohnMcPMS]

I see how this can be confusing; many of our parameters are of the form --<name> <value>, while some are flags and some of them are able to be positional. The help doesn't do a great job of explaining which are which admittedly.

For your case, you would want to put the --id before, like winget list --id Element.Element.

I think that we could probably improve here with something like:

The following options are available:
  --id <value>                        Filter results by id

Do you have a suggestion on how the help could provide clarity?

[danielniccoli]

Do you have a suggestion on how the help could provide clarity?

Before I can make a suggestion, I need to have more information. How does --query works differently from --id, --name or --moniker. Is --query mutually exclusive to --id, --name or --moniker? Are they all mutually exclusive?

In general, I'd advice so simply follow POSIX convention with the command line arguments and their docs, and it should all fall into place.

[rltas]

This is similarly confusing:

PS C:\Users\rltas> winget list --name --exact "Windows Subsystem for Linux Preview"
No installed package found matching input criteria.

PS C:\Users\rltas> winget list --exact --name "Windows Subsystem for Linux Preview"
Name                                ID           Version  Source
------------------------------------------------------------------
Windows Subsystem for Linux Preview 9P9TQF7MRM4R 0.70.4.0 msstore