Edit

Share via

Read-Host

  • Reference
Module:
Microsoft.PowerShell.Utility

Reads a line of input from the console.

Syntax

Read-Host
    [[-Prompt] <Object>]
    [-MaskInput]
    [<CommonParameters>]
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 1022 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: Mask input and as a plaintext 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 plaintext String object in the $pwd_string variable.

$pwd_string = Read-Host "Enter a Password" -MaskInput

Example 4: 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

-MaskInput

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 String object. This allows you to safely prompt for a password that is returned as plaintext instead of SecureString.

This parameter was added in PowerShell 7.1.

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.