Provide a cleaner help output which would make it easier to use

[bcurran3]

Please update the help responses to be context sensitive and remove currently displayed info that is irrelevant. The information supplied is overwhelming to most, it would not be so overwhelming if it only showed information relevant to the current help request.

The bold info below is an example of what I believe to be irrelevant, but maybe I'm wrong and there are edge use cases.

e.g.:

C:>clist -help Chocolatey v0.10.13 List/Search Command

Chocolatey will perform a search for a package local or remote. Some may prefer to use clist as a shortcut for choco list.

NOTE: 100% compatible with older Chocolatey client (0.9.8.x and below) with options and switches. In most cases you can still pass options and switches with one dash (-). For more details, see the command reference (choco -?).

Usage

choco search <filter> [<options/switches>]
choco list <filter> [<options/switches>]
clist <filter> [<options/switches>]

Examples

choco list --local-only
choco list -li
choco list -lai
choco list --page=0 --page-size=25
choco search git
choco search git --source="'https://somewhere/out/there'"
choco search bob -s "'https://somewhere/protected'" -u user -p pass

NOTE: See scripting in the command reference (choco -?) for how to write proper scripts and integrations.

Exit Codes

Exit codes that normally result from running this command.

Normal:

• 0: operation was successful, no issues detected
• -1 or 1: an error has occurred

Enhanced:

• 0: operation was successful, no issues detected
• -1 or 1: an error has occurred
• 2: no results (enhanced)

NOTE: Starting in v0.10.12, if you have the feature 'useEnhancedExitCodes' turned on, then choco will provide enhanced exit codes that allow better integration and scripting.

If you find other exit codes that we have not yet documented, please file a ticket so we can document it at https://github.com/chocolatey/choco/issues/new/choose.

See It In Action

choco search: https://raw.githubusercontent.com/wiki/chocolatey/choco/images/gifs/choco_search.gif

Alternative Sources

Available in 0.9.10+.

WebPI This specifies the source is Web PI (Web Platform Installer) and that we are searching for a WebPI product, such as IISExpress. If you do not have the Web PI command line installed, it will install that first and then perform the search requested. e.g. choco list --source webpi

Windows Features This specifies that the source is a Windows Feature and we should install via the Deployment Image Servicing and Management tool (DISM) on the local machine. e.g. choco list --source windowsfeatures

Options and Switches

-?, --help, -h Prints out the help menu.

-d, --debug Debug - Show debug messaging.

-v, --verbose Verbose - Show verbose messaging. Very verbose messaging, avoid using under normal circumstances.

 --trace
 Trace - Show trace messaging. Very, very verbose trace messaging. Avoid
   except when needing super low-level .NET Framework debugging. Available
   in 0.10.4+.

 --nocolor, --no-color
 No Color - Do not show colorization in logging output. This overrides
   the feature 'logWithoutColor', set to 'False'. Available in 0.10.9+.

** --acceptlicense, --accept-license
 AcceptLicense - Accept license dialogs automatically. Reserved for
   future use.**

-y, --yes, --confirm Confirm all prompts - Chooses affirmative answer instead of prompting. Implies --accept-license

-f, --force Force - force the behavior. Do not use force during normal operation - it subverts some of the smart behavior for commands.

** --noop, --whatif, --what-if
 NoOp / WhatIf - Don't actually do anything.**

-r, --limitoutput, --limit-output LimitOutput - Limit the output to essential information

 --timeout, --execution-timeout=VALUE
 CommandExecutionTimeout (in seconds) - The time to allow a command to
   finish before timing out. Overrides the default execution timeout in the
   configuration of 2700 seconds. '0' for infinite starting in 0.10.4.

-c, --cache, --cachelocation, --cache-location=VALUE CacheLocation - Location for download cache, defaults to %TEMP% or value in chocolatey.config file.

 --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build
 AllowUnofficialBuild - When not using the official build you must set
   this flag for choco to continue.

 --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output
 FailOnStandardError - Fail on standard error output (stderr), typically
   received when running external commands during install providers. This
   overrides the feature failOnStandardError.

 **--use-system-powershell
 UseSystemPowerShell - Execute PowerShell using an external process
   instead of the built-in PowerShell host. Should only be used when
   internal host is failing. Available in 0.9.10+.**

 **--no-progress
 Do Not Show Progress - Do not show download progress percentages.
   Available in 0.10.4+.**

 --proxy=VALUE
 Proxy Location - Explicit proxy location. Overrides the default proxy
   location of ''. Available for config settings in 0.9.9.9+, this CLI
   option available in 0.10.4+.

 --proxy-user=VALUE
 Proxy User Name - Explicit proxy user (optional). Requires explicity
   proxy (`--proxy` or config setting). Overrides the default proxy user of
   ''. Available for config settings in 0.9.9.9+, this CLI option available
   in 0.10.4+.

 --proxy-password=VALUE
 Proxy Password - Explicit proxy password (optional) to be used with
   username. Requires explicity proxy (`--proxy` or config setting) and
   user name.  Overrides the default proxy password (encrypted in settings
   if set). Available for config settings in 0.9.9.9+, this CLI option
   available in 0.10.4+.

 --proxy-bypass-list=VALUE
 ProxyBypassList - Comma separated list of regex locations to bypass on
   proxy. Requires explicity proxy (`--proxy` or config setting). Overrides
   the default proxy bypass list of ''. Available in 0.10.4+.

 --proxy-bypass-on-local
 Proxy Bypass On Local - Bypass proxy for local connections. Requires
   explicity proxy (`--proxy` or config setting). Overrides the default
   proxy bypass on local setting of 'True'. Available in 0.10.4+.

 --log-file=VALUE
 Log File to output to in addition to regular loggers. Available in 0.1-
   0.8+.

-s, --source=VALUE Source - Source location for install. Can use special 'webpi' or 'windowsfeatures' sources. Defaults to sources.

-l, --lo, --localonly, --local-only LocalOnly - Only search against local machine items.

 --idonly, --id-only
 Id Only - Only return Package Ids in the list results. Available in 0.1-
   0.6+.

 --pre, --prerelease
 Prerelease - Include Prereleases? Defaults to false.

-i, --includeprograms, --include-programs IncludePrograms - Used in conjunction with LocalOnly, filters out apps chocolatey has listed as packages and includes those in the list. Defaults to false.

-a, --all, --allversions, --all-versions AllVersions - include results from all versions.

 --version=VALUE
 Version - Specific version of a package to return.

-u, --user=VALUE User - used with authenticated feeds. Defaults to empty.

-p, --password=VALUE Password - the user's password to the source. Defaults to empty.

 --cert=VALUE
 Client certificate - PFX pathname for an x509 authenticated feeds.
   Defaults to empty. Available in 0.9.10+.

 --cp, --certpassword=VALUE
 Certificate Password - the client certificate's password to the source.
   Defaults to empty. Available in 0.9.10+.

 --page=VALUE
 Page - the 'page' of results to return. Defaults to return all results.
   Available in 0.9.10+.

 --page-size=VALUE
 Page Size - the amount of package results to return per page. Defaults
   to 25. Available in 0.9.10+.

-e, --exact Exact - Only return packages with this exact name. Available in 0.9.10+.

 --by-id-only
 ByIdOnly - Only return packages where the id contains the search filter.
   Available in 0.9.10+.

 --by-tag-only, --by-tags-only
 ByTagOnly - Only return packages where the search filter matches on the
   tags. Available in 0.10.6+.

 --id-starts-with
 IdStartsWith - Only return packages where the id starts with the search
   filter. Available in 0.9.10+.

 --order-by-popularity
 OrderByPopularity - Sort by package results by popularity. Available in
   0.9.10+.

 --approved-only
 ApprovedOnly - Only return approved packages - this option will filter
   out results not from the community repository. Available in 0.9.10+.

 --download-cache, --download-cache-only
 DownloadCacheAvailable - Only return packages that have a download cache
   available - this option will filter out results not from the community
   repository. Available in 0.9.10+.

 --not-broken
 NotBroken - Only return packages that are not failing testing - this
   option only filters out failing results from the community feed. It will
   not filter against other sources. Available in 0.9.10+.

 --detail, --detailed
 Detailed - Alias for verbose. Available in 0.9.10+.

[bcurran3]

As an addition example of what I believe to be irrelevant information displayed:

EDIT: The quoting and bold are fighting each other. Some examples are bold, some just show with the double asterix in front of them.

C:>cpack -help

Chocolatey v0.10.13 Pack Command

Chocolatey will attempt to package a nuspec into a compiled nupkg. Some may prefer to use cpack as a shortcut for choco pack.

NOTE: 100% compatible with older chocolatey client (0.9.8.32 and below) with options and switches. In most cases you can still pass options and switches with one dash (-). For more details, see the command reference (choco -?).

NOTE: You can pass arbitrary property value pairs through to nuspecs. These will replace variables formatted as $property$ with the value passed.

NOTE: cpack has been deprecated as it has a name collision with CMake. Please use choco pack instead. The shortcut will be removed in v1.

Usage

choco pack [<path to nuspec>] [<options/switches>] [<property=value>]
cpack [<path to nuspec>] [<options/switches>] (DEPRECATED)

Examples

choco pack
choco pack --version 1.2.3 configuration=release
choco pack path/to/nuspec
choco pack --outputdirectory build

NOTE: See scripting in the command reference (choco -?) for how to write proper scripts and integrations.

Exit Codes

Exit codes that normally result from running this command.

Normal:

• 0: operation was successful, no issues detected
• -1 or 1: an error has occurred

If you find other exit codes that we have not yet documented, please file a ticket so we can document it at https://github.com/chocolatey/choco/issues/new/choose.

Options and Switches

-?, --help, -h Prints out the help menu.

-d, --debug Debug - Show debug messaging.

-v, --verbose Verbose - Show verbose messaging. Very verbose messaging, avoid using under normal circumstances.

 --trace
 Trace - Show trace messaging. Very, very verbose trace messaging. Avoid
   except when needing super low-level .NET Framework debugging. Available
   in 0.10.4+.

 --nocolor, --no-color
 No Color - Do not show colorization in logging output. This overrides
   the feature 'logWithoutColor', set to 'False'. Available in 0.10.9+.

 **--acceptlicense, --accept-license
 AcceptLicense - Accept license dialogs automatically. Reserved for
   future use.**

-y, --yes, --confirm Confirm all prompts - Chooses affirmative answer instead of prompting. Implies --accept-license

-f, --force Force - force the behavior. Do not use force during normal operation - it subverts some of the smart behavior for commands.

 --noop, --whatif, --what-if
 NoOp / WhatIf - Don't actually do anything.

-r, --limitoutput, --limit-output LimitOutput - Limit the output to essential information

 **--timeout, --execution-timeout=VALUE
 CommandExecutionTimeout (in seconds) - The time to allow a command to
   finish before timing out. Overrides the default execution timeout in the
   configuration of 2700 seconds. '0' for infinite starting in 0.10.4.**

-c, --cache, --cachelocation, --cache-location=VALUE CacheLocation - Location for download cache, defaults to %TEMP% or value in chocolatey.config file.

 **--allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build
 AllowUnofficialBuild - When not using the official build you must set
   this flag for choco to continue.**

 --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output
 FailOnStandardError - Fail on standard error output (stderr), typically
   received when running external commands during install providers. This
   overrides the feature failOnStandardError.

 **--use-system-powershell
 UseSystemPowerShell - Execute PowerShell using an external process
   instead of the built-in PowerShell host. Should only be used when
   internal host is failing. Available in 0.9.10+.**

 **--no-progress
 Do Not Show Progress - Do not show download progress percentages.
   Available in 0.10.4+.**

 **--proxy=VALUE
 Proxy Location - Explicit proxy location. Overrides the default proxy
   location of ''. Available for config settings in 0.9.9.9+, this CLI
   option available in 0.10.4+.**

 **--proxy-user=VALUE
 Proxy User Name - Explicit proxy user (optional). Requires explicity
   proxy (`--proxy` or config setting). Overrides the default proxy user of
   ''. Available for config settings in 0.9.9.9+, this CLI option available
   in 0.10.4+.**

 **--proxy-password=VALUE
 Proxy Password - Explicit proxy password (optional) to be used with
   username. Requires explicity proxy (`--proxy` or config setting) and
   user name.  Overrides the default proxy password (encrypted in settings
   if set). Available for config settings in 0.9.9.9+, this CLI option
   available in 0.10.4+.**

 **--proxy-bypass-list=VALUE
 ProxyBypassList - Comma separated list of regex locations to bypass on
   proxy. Requires explicity proxy (`--proxy` or config setting). Overrides
   the default proxy bypass list of ''. Available in 0.10.4+.**

 **--proxy-bypass-on-local
 Proxy Bypass On Local - Bypass proxy for local connections. Requires
   explicity proxy (`--proxy` or config setting). Overrides the default
   proxy bypass on local setting of 'True'. Available in 0.10.4+.**

 --log-file=VALUE
 Log File to output to in addition to regular loggers. Available in 0.1-
   0.8+.

 --version=VALUE
 Version - The version you would like to insert into the package.

 --out, --outdir, --outputdirectory, --output-directory=VALUE
 OutputDirectory - Specifies the directory for the created Chocolatey
   package file. If not specified, uses the current directory.

[ferventcoder]

Perhaps we should look to provide less information by default and then provide something like --full-help that would provide quite a bit more?

[bcurran3]

I've always thought that choco -? gave too much information and had been planning on opening an issue specifically to request breaking it up for a long time. Chocolatey v0.10.13's current help output is 277 lines long - 10 "pages" long in a standard/default Command Prompt. Although not the purpose of this particular issue, I'm happy to see you willing to consider revising the built-in help system.

IMHO choco -? should only display the "Commands" and not the "How To Pass Options / Switches, "Scripting / Integration - Best Practices / Style Guide," or "Default Options and Switches." IMHO the former three should be broken into sub-help and displayed upon request of that sub-help. (choco --switches, choco --integration)

Being picky "Default Options and Switches" is a misnomer. None of the displayed switch options are active by default, they must be explicitly expressed.

---

But back to the original intent of this issue, please filter out all irrelevant information from CHOCO COMMAND -? commands.

Another example: (better highlighted)

CHOCO PIN -? yields the following information that I believe is irrelevant:

 --acceptlicense, --accept-license
 AcceptLicense - Accept license dialogs automatically. Reserved for
   future use.

 --timeout, --execution-timeout=VALUE
 CommandExecutionTimeout (in seconds) - The time to allow a command to
   finish before timing out. Overrides the default execution timeout in the
   configuration of 2700 seconds. '0' for infinite starting in 0.10.4.

-c, --cache, --cachelocation, --cache-location=VALUE CacheLocation - Location for download cache, defaults to %TEMP% or value in chocolatey.config file.

 --allowunofficial, --allow-unofficial, --allowunofficialbuild, --allow-unofficial-build
 AllowUnofficialBuild - When not using the official build you must set
   this flag for choco to continue.

 --failstderr, --failonstderr, --fail-on-stderr, --fail-on-standard-error, --fail-on-error-output
 FailOnStandardError - Fail on standard error output (stderr), typically
   received when running external commands during install providers. This
   overrides the feature failOnStandardError.

 --use-system-powershell
 UseSystemPowerShell - Execute PowerShell using an external process
   instead of the built-in PowerShell host. Should only be used when
   internal host is failing. Available in 0.9.10+.

 --no-progress
 Do Not Show Progress - Do not show download progress percentages.
   Available in 0.10.4+.

 --proxy=VALUE
 Proxy Location - Explicit proxy location. Overrides the default proxy
   location of ''. Available for config settings in 0.9.9.9+, this CLI
   option available in 0.10.4+.

 --proxy-user=VALUE
 Proxy User Name - Explicit proxy user (optional). Requires explicity
   proxy (`--proxy` or config setting). Overrides the default proxy user of
   ''. Available for config settings in 0.9.9.9+, this CLI option available
   in 0.10.4+.

 --proxy-bypass-list=VALUE
 ProxyBypassList - Comma separated list of regex locations to bypass on
   proxy. Requires explicity proxy (`--proxy` or config setting). Overrides
   the default proxy bypass list of ''. Available in 0.10.4+.

 --proxy-bypass-on-local
 Proxy Bypass On Local - Bypass proxy for local connections. Requires
   explicity proxy (`--proxy` or config setting). Overrides the default
   proxy bypass on local setting of 'True'. Available in 0.10.4+.

I'll admit I haven't tried them, but I can't fathom any of the above switches being relevant to the pin command; that's about 50 lines of noise.

Obviously if the "Default Options and Switches" is moved to a sub-menu then the above wouldn't be displayed with the command help and the noise would be (re)moved as a result. I see the possible appearance of the noise returning via a future command such as CHOCO PIN --SWITCHES which is why I still request that only actual usable switches for (in this example) the pin command be displayed.

[ferventcoder]

Default Options and Switches are really the global options and switches. Perhaps "Default" is the wrong term - which is to say they can be passed to any command. They may not always apply to the context of every command though (as you pointed out).

[ferventcoder]

It feels like there are a few things we are talking about here. Let's focus this one on reducing to relevant, high level help by default, and allowing someone to ask for more detailed help with an additional switch. This is similar to what PowerShell has with it's help menu and what I'd like to emulate.

[mark-zacharias]

Is this still on the roadmap? The choco command line help is practically useless with the wall of text it provides every time. I have to scroll up past the wall to see if there was anything relevant or sometimes just give up open a web browser and start searching for help.
Sometimes I just get frustrated and move on to doing something else like downloading the package and installing manually.

[pauby]

This is still something we very much want to do.

[pauby]

We implemented the --online to provide online help for each command.