Edit

Read-Host

  • Reference
Module:
Microsoft.PowerShell.Utility

Reads a line of input from the console.

Syntax

Read-Host
    [[-Prompt] <Object>]
    [-AsSecureString]
    [<CommonParameters>]

Description

The Read-Host cmdlet reads a line of input from the console (stdin). You can use it to prompt a user for input. Because you can save the input as a secure string, you can use this cmdlet to prompt users for secure data, such as passwords.

Note

Read-Host has a limit of 8190 characters it can accept as input from a user.

Examples

Example 1: Save console input to a variable

This example displays the string "Please enter your age:" as a prompt. When a value is entered and the Enter key is pressed, the value is stored in the $Age variable.

$Age = Read-Host "Please enter your age"

Example 2: Save console input as a secure string

This example displays the string "Enter a Password:" as a prompt. As a value is being entered, asterisks (*) appear on the console in place of the input. When the Enter key is pressed, the value is stored as a SecureString object in the $pwd_secure_string variable.

$pwd_secure_string = Read-Host "Enter a Password" -AsSecureString

Example 3: Normalizing input

This example prompts the user to input a list of cities separated by semi-colons. It shows the string's value as typed by the user. In the example, the user added spaces between some of the entries. This could lead to an error later in the script where the code expects an exact name.

The example shows how you can convert an input string into an array of entries without any extra spaces.

$prompt = @(
    'List the cities you want weather information for.'
    'When specifying multiple cities, separate them with a semi-colon, like:'
    "'New York; Osan; Koforidua'"
) -join ' '

$cities = Read-Host $prompt

"Input cities string: `n`t'$cities'"

$splitCities = $cities -split ';'

"Split cities array:"
$splitCities | ForEach-Object -Process { "`t'$_'" }

$normalizedCities = $splitCities  | ForEach-Object -Process { $_.Trim() }

"Normalized split cities array:"
$normalizedCities | ForEach-Object -Process { "`t'$_'" }

Input cities string:
        '    New York;  Osan   ;Koforidua   '
Split cities array:
        '    New York'
        '  Osan   '
        'Koforidua   '
Normalized split cities array:
        'New York'
        'Osan'
        'Koforidua'

The example uses the -split operator to convert the input string into an array of strings. Each string in the array includes the name of a different city. However, the split strings include extra spaces. The Trim() method removes the leading and trailing spaces from each string.

Parameters

-AsSecureString

Indicates that the cmdlet displays asterisks (*) in place of the characters that the user types as input. When you use this parameter, the output of the Read-Host cmdlet is a SecureString object (System.Security.SecureString).

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Prompt

Specifies the text of the prompt. Type a string. If the string includes spaces, enclose it in quotation marks. PowerShell appends a colon (:) to the text that you enter.

Type:Object
Position:0
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Inputs

None

You can't pipe objects to this cmdlet.

Outputs

String

By default, this cmdlet returns a string.

SecureString

When you use AsSecureString parameter, this cmdlet returns a SecureString.

Notes

This cmdlet only reads from the stdin stream of the host process. Usually, the stdin stream is connected to the keyboard of the host console.