Customize the behavior of command line editing in PSReadLine.
Syntax
Set-PSReadLineOption [-AddToHistoryHandler Func[string,Object]] [-AnsiEscapeTimeout int] [-BellStyle BellStyle]
[-CompletionQueryItems int] [-CommandValidationHandler Action[CommandAst]] [-Colors hashtable]
[-ContinuationPrompt string] [-DingTone int] [-DingDuration int] [-EditMode EditMode]
[-ExtraPromptLineCount int] [-HistorySearchCaseSensitive] [-HistoryNoDuplicates]
[-HistorySearchCursorMovesToEnd] [-HistorySaveStyle HistorySaveStyle] [-HistorySavePath string]
[-MaximumHistoryCount int] [-MaximumKillRingCount int] [-PromptText string[]]
[-PredictionSource PredictionSource] [-PredictionViewStyle PredictionViewStyle]
[-ShowToolTips] [-TerminateOrphanedConsoleApps] [-ViModeChangeHandler scriptblock]
[-ViModeIndicator ViModeStyle] [-WordDelimiters string] [CommonParameters]
Key
-AddToHistoryHandler
Specifies a ScriptBlock that controls how commands get added to PSReadLine history.
The ScriptBlock receives the command line as input.
The ScripBlock should return a member of the AddToHistoryOption enum, the string name of one of those
members, or a boolean value.
The list below describes the possible values and their effects.
MemoryAndFile - Add the command to the history file and the current session.
MemoryOnly - Add the command to history for the current session only.
SkipAdding - Don't add the command to the history file for current session.
$false - Same as if the value was SkipAdding.
$true - Same as if the value was MemoryAndFile.
-AnsiEscapeTimeout
This option is specific to Windows when input is redirected, for example, when running under tmux or screen.
With redirected input on Windows, many keys are sent as a sequence of characters starting with the escape character.
It's impossible to distinguish between a single escape character followed by more characters and a valid escape
sequence.
The assumption is that the terminal can send the characters faster than a user types. PSReadLine waits for this
timeout before concluding that it has received a complete escape sequence.
If you see random or unexpected characters when you type, you can adjust this timeout.
-BellStyle
How PSReadLine should respond to various error and ambiguous conditions.
Valid values:
Audible: A short beep.
Visual: Text flashes briefly.
None: No feedback.
-Colors
The Colors parameter specifies various colors used by PSReadLine.
The argument is a hash table where the keys specify the elements and the values specify the color.
For more information, see about_Hash_Tables.
Colors can be either a value from ConsoleColor, for example [ConsoleColor]::Red, or a valid ANSI escape sequence.
Valid escape sequences depend on your terminal. In PowerShell 5.0, an example escape sequence for red text
is $([char]0x1b)[91m. In PowerShell 6 and newer, the same escape sequence is `e[91m.
You can specify other escape sequences including the following types:
• ListPredictionColor - Set color for the leading > character and the trailing source name, such as
[History]. By default, it uses DarkYellow as the foreground color.
• ListPredictionSelectedColor - Set color for indicating a list item is selected.
By default, it uses DarkBlack as the background color.
• 256 color
• 24-bit color
• Foreground, background, or both
• Inverse, bold
The valid keys include:
ContinuationPrompt : The color of the continuation prompt.
Command
Comment
Default
Emphasis : The emphasis color. For example, the matching text when searching history.
Error : The error color. For example, in the prompt.
Keyword
Member
Number
Operator
Parameter
Selection : The color to highlight the menu selection or selected text.
String
Type
Variable
InlinePrediction : The color for the inline view of the predictive suggestion.
ListPrediction : The color for the leading > character and prediction source name.
ListPredictionSelected : The color for the selected prediction in list view.
-CommandValidationHandler
Specifies a ScriptBlock that is called from ValidateAndAcceptLine. If an exception is thrown, validation
fails and the error is reported.
Before throwing an exception, the validation handler can place the cursor at the point of the error to
make it easier to fix. A validation handler can also change the command line to correct common
typographical errors.
ValidateAndAcceptLine is used to avoid cluttering your history with commands that can't work.
-CompletionQueryItems int
The maximum number of completion items to show without prompting. If the number of items to show is
greater than this value, PSReadLine prompts yes/no before displaying the completion items.
-ContinuationPrompt string
Specifies the string displayed at the beginning of the subsequent lines when multi-line input is entered.
The default is double greater-than signs (>>). An empty string is valid.
-DingDuration int
The duration of the beep when BellStyle is set to Audible.
-DingTone
Specifies the tone in Hertz (Hz) of the beep when BellStyle is set to Audible.
-EditMode
The command line editing mode.
Using this parameter resets any key bindings set by Set-PSReadLineKeyHandler.
Valid values:
Windows : Key bindings emulate PowerShell, cmd, and Visual Studio. (default on Windows)
Emacs : Key bindings emulate Bash or Emacs. (default on non-Windows platforms)
Vi : Key bindings emulate Vi. Use Get-PSReadLineKeyHandler to see the key bindings
for the currently configured EditMode.
-ExtraPromptLineCount int
Specifies the number of extra lines.
If your prompt spans more than one line, specify a value for this parameter.
Use this option when you want extra lines to be available when PSReadLine displays the prompt
after showing some output.
For example, PSReadLine returns a list of completions. This option is needed less than in previous
versions of PSReadLine, but is useful when the InvokePrompt function is used.
-HistoryNoDuplicates
This option controls the recall behavior. Duplicate commands are still added to the history
file. When this option is set, only the most recent invocation appears when recalling commands.
Repeated commands are added to history to preserve ordering during recall. However, you typically
don't want to see the command multiple times when recalling or searching the history.
By default, the HistoryNoDuplicates property of the global PSConsoleReadLineOptions object is set
to True. To change the property value, you must specify the value of the SwitchParameter as follows:
-HistoryNoDuplicates:$false. You can set back to True by using just the SwitchParameter, -HistoryNoDuplicates.
Using the following command, you can set the property value directly:
(Get-PSReadLineOption).HistoryNoDuplicates = $false
-HistorySavePath string
A file path where history will be saved.
Computers running Windows or non-Windows platforms store the file in different locations.
The filename is stored in a variable $($Host.Name)_history.txt,
for example ConsoleHost_history.txt.
If you don't use this parameter, the default path is as follows:
Windows
$Env:APPDATA\Microsoft\Windows\PowerShell\PSReadLine\$($Host.Name)_history.txt
non-Windows
$Env:XDG_DATA_HOME/powershell/PSReadLine/$($Host.Name)_history.txt
$HOME/.local/share/powershell/PSReadLine/$($Host.Name)_history.txt
-HistorySaveStyle HistorySaveStyle
How PSReadLine will save history.
Valid values:
SaveIncrementally: Save history after each command is executed and share across multiple instances of PowerShell.
SaveAtExit: Append history file when PowerShell exits.
SaveNothing: Don't use a history file.
-HistorySearchCaseSensitive
Specifies that history searching is case-sensitive in functions like ReverseSearchHistory or HistorySearchBackward.
By default, the HistorySearchCaseSensitive property of the global PSConsoleReadLineOptions object is set to False.
Using this SwitchParameter sets the property value to True.
To change the property value back, you must specify the value of the SwitchParameter as follows:
-HistorySearchCaseSensitive:$false.
Using the following command, you can set the property value directly:
(Get-PSReadLineOption).HistorySearchCaseSensitive = $false
-HistorySearchCursorMovesToEnd
Indicates that the cursor moves to the end of commands that you load from history by using a search.
When this parameter is set to $false, the cursor remains at the position it was when you pressed the
up or down arrows.
By default, the HistorySearchCursorMovesToEnd property of the global PSConsoleReadLineOptions object
is set to False. Using this SwitchParameter set the property value to True.
To change the property value back, you must specify the value of the SwitchParameter as follows:
-HistorySearchCursorMovesToEnd:$false.
Using the following command, you can set the property value directly:
(Get-PSReadLineOption).HistorySearchCursorMovesToEnd = $false
-MaximumHistoryCount int
The maximum number of commands to save in PSReadLine history.
PSReadLine history is separate from PowerShell history.
-MaximumKillRingCount int
The maximum number of items stored in the kill ring.
-PredictionSource PredictionSource
The source for PSReadLine to get predictive suggestions.
Valid values:
None - Disable the predictive IntelliSense feature (default).
History - Enable the predictive IntelliSense feature and use the PSReadLine history as the only source.
Plugin - Enable the predictive IntelliSense feature and use the plugins (CommandPrediction) as the only
source. This value was added in PSReadLine 2.2.0
HistoryAndPlugin - Enable the predictive IntelliSense feature and use both history and plugin as the sources.
This value was added in PSReadLine 2.2.0
-PredictionViewStyle PredictionViewStyle
Sets the style for the display of the predictive text. The default is InlineView.
InlineView - the style as existing today, similar as in fish shell and zsh. (default)
ListView - suggestions are rendered in a drop down list, and users can select using UpArrow and DownArrow.
This parameter was added in PSReadLine 2.2.0
-PromptText
This parameter sets the value of the PromptText property. The default value is "> ".
PSReadLine analyzes your prompt function to determine how to change only the color of part of your prompt.
This analysis isn't 100% reliable. Use this option if PSReadLine is changing your prompt in unexpected ways.
Include any trailing whitespace.
The value of this parameter can be a single string or an array of two strings. The first string is the portion
of your prompt string that you want to be changed to red when there is a parse error.
The second string is an alternate string to use for when there is a parse error.
-ShowToolTips
When displaying possible completions, tooltips are shown in the list of completions.
This option is enabled by default. This option wasn't enabled by default in prior versions of PSReadLine.
To disable, set this option to $false.
This parameter and option were added in PSReadLine 2.3.4.
By default, the ShowToolTips property of the global PSConsoleReadLineOptions object is set to True.
Using this SwitchParameter sets the property value to True. To change the property value, you must specify
the value of the SwitchParameter as follows: -ShowToolTips:$false.
Using the following command, you can set the property value directly:
(Get-PSReadLineOption).ShowToolTips = $false
-TerminateOrphanedConsoleApps
This parameter sets the TerminateOrphanedConsoleApps option to $true.
On Windows, when you press Ctrl+c to terminate a process, each process attached to a console receives
a terminate signal, as opposed to just the active shell. Sometimes, when a shell has launched some
large tree of child processes, (imagine a build system, for example) some processes may exit, leaving
multiple processes concurrently trying to consume console input.
When setting the TerminateOrphanedConsoleApps option to $true, PSReadLine records the list of processes
that are currently attached to the console. Afterwards, whenever PSReadLine runs, it will get a new list
of processes attached to the console, and terminate those that aren't in the original list.
This parameter and option were added in PSReadLine 2.3.4.
-ViModeChangeHandler scriptblock
When the ViModeIndicator is set to Script, the scriptblock provided will be invoked every time
the mode changes. The scriptblock is provided one argument of type ViMode.
This parameter was introduced in PowerShell 7.
-ViModeIndicator ViModeStyle
This option sets the visual indicator for the current Vi mode. Either insert mode or command mode.
The valid values are as follows:
None : There's no indicator.
Prompt : The prompt changes color.
Cursor : The cursor changes size.
Script : User-specified text is printed.
-WordDelimiters
Specifies the characters that delimit words for functions like ForwardWord or KillWord.
Default value: ;:,.[]{}()/\|^&*-=+'"---
The Set-PSReadLineOption cmdlet customizes the behavior of the PSReadLine module when you're editing the command line. To view the PSReadLine settings, use Get-PSReadLineOption.
The options set by this command only apply to the current session. To persist any options, add them to a profile script.
Set PSReadLine to display the Comment token with green foreground text on a gray background. In the escape sequence, 32 represents the foreground color and 47 the background color:
PS C:\> Set-PSReadLineOption -Colors @{ "Comment"="`e[32;47m" }
Set only a foreground text color. For example, a bright green foreground text color for the Comment token:
PS C:\> Set-PSReadLineOption -Colors @{ "Comment"="`e[92m" }
Respond to errors or conditions that require user attention. Set the BellStyle to emit an audible beep at 1221 Hz for 60 ms:
PS C:\> Set-PSReadLineOption -BellStyle Audible -DingTone 1221 -DingDuration 60
Set multiple Set-PSReadLineOption options using a hash table:
$ss64Options = @{
EditMode = "Emacs"
HistoryNoDuplicates = $true
HistorySearchCursorMovesToEnd = $true
Colors = @{
"Command" = "#8181f7"
}
}
Set-PSReadLineOption @ss64Options
Set more than one color value in a single command:
PS C:\> Set-PSReadLineOption -Colors @{
Command = 'Magenta'
Number = 'DarkGray'
Member = 'DarkGray'
Operator = 'DarkGray'
Type = 'DarkGray'
Variable = 'DarkGreen'
Parameter = 'DarkGreen'
ContinuationPrompt = 'DarkGray'
Default = 'DarkGray'
}
Three different methods to set the colour of tokens:
PS C:\> Set-PSReadLineOption -Colors @{
# Use a ConsoleColor enum
"Error" = [ConsoleColor]::DarkRed
# 24 bit color escape sequence
"String" = "$([char]0x1b)[38;5;100m"
# RGB value
"Command" = "#8181f7"
}
When there's a parse error, PSReadLine changes a part of the prompt red. The -PromptText parameter tells PSReadLine the part of the prompt string to make red. For example, the following example creates a prompt that contains the current path followed by the greater-than character (>) and a space:
PS C:\> function prompt { "PS $PWD> " }`
PS C:\> Set-PSReadLineOption -PromptText '> ' # change the '>' character red
Set an alternate string to use when there is a parse error:
PS C:\> function prompt { "PS $PWD> " }`
PS C:\> Set-PSReadLineOption -PromptText '> ', 'X ' # replace the '>' character with a red 'X'
“I do a show. It comes on late at night on TV. And if that means I’m a late-night talk show host, then I guess I am, but in every other regard I resign my commission, I don’t care for it” ~ Craig Ferguson
Get-PSReadLineOption - Get the behavior of command line editing in PSReadLine.
