Enhance PowerShell full command line help

Show usage (short) help if command line parameter is wrong #5780 We should show the full/short command line help in Bash style if a parameter is wrong.
Reformat command line help for powershell -Help #4989 We should reformat the help in Bash style:
- sort parameter list in alphabetical order.
- replace long header on powershell[.exe] [options]
Reformat command line help for powershell -Help #4989 We should add more examples in line of the help.
Add help strings in PowerShell banner #5275 Add "To get help type Help or Help followed by the command name, such as: Help Get-Process" in PowerShell banner bottom.

The Issue consider command line only powershell -Help (in bash or cmd.exe).

Ilya (@iSazonov)

Ilya (@iSazonov) this is for the PowerShell binary, correct?

We should show the full command line help in Bash style if a parameter is wrong.

Most Linux commands show usage and how to obtain help (-h, --help, man, etc.) on incorrect parameters unless their usage is very simple. Full help leads to the previous command going off console. command history is not always a given in the Linux world. I would prefer short syntax help and how to obtain the full help when I use the wrong parameters.

Mark Kraus (@markekraus)

Mark Kraus (@markekraus) The Issue is for discussion to collect ideas. :-)

I like short help on error too. We mean an interactive session where typos is a common matter - full help will going to annoy.

Ilya (@iSazonov)

Ilya (@iSazonov) by "We mean an interactive session where typos is a common matter"
Do you mean an interactive session in PowerShell?

example:

c:\> Get-Service -Nmae Get-Command

Get-Service : A parameter cannot be found that matches parameter name 'Nmae'.
At line:1 char:13
+ Get-Service -Nmae Get-Command
+             ~~~~~

SYNTAX
    Get-Service [[-Name] <String[]>] [-ComputerName <String[]>] [-DependentServices] [-Exclude <String[]>] [-Include <String[]>] [-RequiredServices] [<CommonParameters>]

    Get-Service [-ComputerName <String[]>] [-DependentServices] [-Exclude <String[]>] [-Include <String[]>] [-RequiredServices] -DisplayName <String[]> [<CommonParameters>]

    Get-Service [-ComputerName <String[]>] [-DependentServices] [-Exclude <String[]>] [-Include <String[]>] [-InputObject <ServiceController[]>] [-RequiredServices] [<CommonParameters>]

For more help on Get-Service run:
Get-Help -Name Get-Service -Full

No, the Issue consider command line only powershell -h (in bash or cmd.exe). I updated the Issue desciption.

Ok then. Something like this:

c:\> powershell -noloexisto
The argument '-noloexisto' is not recognized as the name of a script file. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

PowerShell[.exe] [-PSConsoleFile <file> | -Version <version>]
    [-NoLogo] [-NoExit] [-Sta] [-Mta] [-NoProfile] [-NonInteractive] [-Interactive]
    [-InputFormat {Text | XML}] [-OutputFormat {Text | XML}]
    [-WindowStyle <style>] [-EncodedCommand <Base64EncodedCommand>]
    [-ConfigurationName <string>]
    [-Command { - | <script-block> [-args <arg-array>]
                  | <string> [<CommandParameters>] } ]
    [-File <filePath> <args>] [-ExecutionPolicy <ExecutionPolicy>]

PowerShell[.exe] -Help | -? | /?

We can be very short and show only PowerShell[.exe] -Help | -? | /?.

I personally like being shown the syntax. that way something like this

powershell -NoUserEnvironment

doesn't require me to read the full help to see that it was supposed to be

powershell -NoProfile

Users will most often see this help when there are typos. For newbie "PowerShell[.exe] -Help" is good start.

Syntax is useful for typos, IMO.

c:\> powershell -NoPrfoile
The argument '-NoPrfoile' is not recognized as the name of a script file. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

PowerShell[.exe] [-PSConsoleFile <file> | -Version <version>]
    [-NoLogo] [-NoExit] [-Sta] [-Mta] [-NoProfile] [-NonInteractive] [-Interactive]
    [-InputFormat {Text | XML}] [-OutputFormat {Text | XML}]
    [-WindowStyle <style>] [-EncodedCommand <Base64EncodedCommand>]
    [-ConfigurationName <string>]
    [-Command { - | <script-block> [-args <arg-array>]
                  | <string> [<CommandParameters>] } ]
    [-File <filePath> <args>] [-ExecutionPolicy <ExecutionPolicy>]

PowerShell[.exe] -Help | -? | /?

then I can easily compare what I typed versus what the correct parameter is. If I have to run the full help and my command goes off screen, I can't easily compare. I may have to scroll and depending on the console I'm working in. that can be either impossible or painful.

From my limited test of Linux commands it seems most complain about the unknown parameter and just tells how to get help. However, I'm not against showing just the syntax.

Michael Klement (@mklement0)

Michael Klement (@mklement0) Could you please comment? Have you ideas?

Mark Kraus (@markekraus)

I agree that the must-have components are:

an error message that is neither drowned out by other information nor scrolled off screen
a generic tip on how to get help.

A concise syntax diagram can be helpful, but the emphasis is on concise - such as in Mark Kraus (@markekraus)'s hypothetical example - whereas the current -? output would be too wordy.

I'm not sure if POSIX mandates the format response to invalid command syntax for compliant utilities; in practice, you get instances of error message only, error message + help tip, and syntax only.

Some examples:

# BSD ls (macOS)
$ ls -y
ls: illegal option -- y
usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]

# GNU ls
$ ls -y
ls: invalid option -- 'y'
Try 'gls --help' for more information.

# BSD grep
$ grep -y
usage: grep [-abcDEFGHhIiJLlmnOoqRSsUVvwxZ] [-A num] [-B num] [-C[num]]
	[-e pattern] [-f file] [--binary-files=value] [--color=when]
	[--context[=num]] [--directories=action] [--label] [--line-buffered]
	[--null] [pattern] [file ...]


# GNU grep
Usage: ggrep [OPTION]... PATTERN [FILE]...
Try 'ggrep --help' for more information.

I really don't like scrolling so based on samples above I still suggest start with

<error message>
For more information try 'powershell -h' or Online Help https://...

Online Help link can be useful for Web/Azure scenarios.

Joey Aiello (@joeyaiello)

cc Joey Aiello (@joeyaiello) Hemant Mahawar (@HemantMahawar) for some opinions here

Navigation Menu

Repository navigation

Enhance PowerShell full command line help #4986

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Enhance PowerShell full command line help #4986

Description

Activity

markekraus commented on Oct 3, 2017

iSazonov commented on Oct 3, 2017

markekraus commented on Oct 3, 2017

iSazonov commented on Oct 3, 2017

markekraus commented on Oct 3, 2017

iSazonov commented on Oct 3, 2017

markekraus commented on Oct 3, 2017

iSazonov commented on Oct 3, 2017

markekraus commented on Oct 3, 2017

SteveL-MSFT commented on Oct 3, 2017

iSazonov commented on Oct 4, 2017

mklement0 commented on Oct 4, 2017

iSazonov commented on Oct 4, 2017

SteveL-MSFT commented on Oct 4, 2017

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions