Read-Host
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" -AsSecureStringExample 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" -MaskInputParameters
-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 |
| 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 |
| 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 |
| 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.