Reading Help: Get-Help

Get-Help shows a command's help page once Update-Help has downloaded it, and its examples, its syntax lines and the about_ topics let you work out a command you've never seen before you run it.

Apprentice · PowerShell · Updated

After this lesson you can

  • Get a command's help with Get-Help, after Update-Help, and read its examples, its online page or an about_ topic
  • Read a command's syntax lines, telling required and optional parameters, positional names, value types and switches

Key takeaways

  • Run Update-Help -Scope CurrentUser once to download the help pages. It needs the internet, not an administrator.
  • Get-Help Stop-Process -Examples shows a command's examples, often the quickest way to learn what it does.
  • In a syntax line, square brackets mean optional, <string[]> is the kind of value a parameter takes, and a parameter with no value is a switch.
  • -Online opens the newest help in your browser, and about_ topics explain ideas rather than commands.

A forum post says a stuck program can be closed with Stop-Process -Name notepad. That command doesn't only look: it closes a program, and anything unsaved in it is lost. Before you run a command that changes something, you want to know exactly what it does. Every PowerShell command comes with a help page, and Get-Help reads it. It's how experienced people work out a command they've never used, without leaving the terminal.

First, download the help: Update-Help

The help pages don't come with PowerShell; they're downloaded separately so they can be kept up to date. Until then, Get-Help shows only what it can work out by itself:

Get-Help Stop-Process

NAME
    Stop-Process

SYNTAX
    Stop-Process [-Id] <int[]> [-PassThru] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]

    Stop-Process -Name <string[]> [-PassThru] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]

    Stop-Process [-InputObject] <Process[]> [-PassThru] [-Force] [-WhatIf] [-Confirm]
    [<CommonParameters>]


ALIASES
    spps
    kill


REMARKS
    Get-Help cannot find the Help files for this cmdlet on this computer. It is displaying only
    partial help.
        -- To download and install Help files for the module that includes this cmdlet, use
    Update-Help.
        -- To view the Help topic for this cmdlet online, type: "Get-Help Stop-Process -Online" or
           go to https://go.microsoft.com/fwlink/?LinkID=2097058.

To download the full pages, run this once, with an internet connection. It takes a minute or two:

Update-Help -Scope CurrentUser

-Scope CurrentUser saves the help in your own Documents folder, so it needs no administrator. That's what PowerShell 7 does anyway; writing it out makes it plain. -Scope AllUsers installs it for everyone on the computer, and that needs PowerShell opened with Run as administrator, which you don't need for this. A red message about one or two modules whose help couldn't be found is normal; the rest still installs. Run it again every month or so for the newest pages.

Windows PowerShell 5.1 has no -Scope: there, Update-Help always needs an administrator window.

Examples first: -Examples

A full help page is long. Start with the examples, real commands with a sentence or two on what each does:

Get-Help Stop-Process -Examples

NAME
    Stop-Process

SYNOPSIS
    Stops one or more running processes.


    --------- Example 1: Stop all instances of a process ---------

Under each title comes the command, between two lines of backticks, and then what it does. Example 1 is the forum's command, Stop-Process -Name "notepad", and the help says it stops all instances of the Notepad process on the computer: every Notepad window, not one of them. That's worth knowing before you press Enter. -Detailed adds a description of every parameter, and -Full shows everything.

Reading the syntax lines

The SYNTAX lines show every way a command can be written, one line for each. Get-Command shows the same lines, help or no help:

Get-Command Stop-Process -Syntax

Stop-Process [-Id] <int[]> [-PassThru] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]

Stop-Process -Name <string[]> [-PassThru] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]

Stop-Process [-InputObject] <Process[]> [-PassThru] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]

Square brackets, [ ], are read "optional". The rest is read like this:

  • -Name <string[]>, with no brackets, is required on that line. <string[]> is the kind of value it takes: string is text, and [] means one or more, separated by commas.
  • [-Id] <int[]> has brackets around the name only, so the name is optional but the value isn't: Stop-Process 4120 is allowed, because the value sits in the first position. int is a whole number.
  • [-Force] has no <value> after it, so it's a switch.
  • [<CommonParameters>] are a few parameters every cmdlet has. Get-Help about_CommonParameters lists them.

Each line is a different way to name the process: by its Id, by its Name, or by a process handed to it. You use one line at a time.

Online help and about_ topics

Get-Help Stop-Process -Online opens the same page in your web browser, always the newest version, with no download needed.

Some help is about ideas rather than commands. Those pages are the about_ topics (read "about topics"): Get-Help about_Wildcards explains the * from Finding a Command: Get-Command, and Get-Help about_Command_Syntax explains syntax lines in more detail. It starts like this:

Get-Help about_Command_Syntax

ABOUT_COMMAND_SYNTAX


Short description

Describes the syntax diagrams that are used in PowerShell.

Get-Help about_* lists every topic, more than 150 of them once the help is downloaded. help, a short form of Get-Help, shows a page a screen at a time: Space for the next screen, Q to stop.

On a Mac or Linux, all of this works the same; -Scope AllUsers needs sudo there instead of an administrator.

Try it. Run Update-Help -Scope CurrentUser, then Get-Help Get-Service -Examples. Which example gets only the services that are running?

Check yourself

2 questions to try on the lesson page.

So what

You never have to guess what a command does before you run it. Get-Help, its examples and its syntax lines tell you, right in the terminal, for every command PowerShell has.

Key terms

Cheat sheets

Related