Set-PSReadLineOption

Customizes the behavior of command line editing in PSReadLine. PowerShell reference

From the PowerShell reference 23 parameters

What it does

from the PowerShell reference, CC BY 4.0

Customizes the behavior of command line editing in PSReadLine. 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. For more information, see about_Profiles and Customizing your shell environment.

Set-PSReadLineOption [-EditMode <EditMode>] [-ContinuationPrompt <string>] [-HistoryNoDuplicates] [-AddToHistoryHandler <Func[string,Object]>] [-CommandValidationHandler <Action[CommandAst]>] [-HistorySearchCursorMovesToEnd] [-MaximumHistoryCount <int>] [-MaximumKillRingCount <int>] [-ShowToolTips] [-ExtraPromptLineCount <int>] [-DingTone <int>] [-DingDuration <int>] [-BellStyle <BellStyle>] [-CompletionQueryItems <int>] [-WordDelimiters <string>] [-HistorySearchCaseSensitive] [-HistorySaveStyle <HistorySaveStyle>] [-HistorySavePath <string>] [-AnsiEscapeTimeout <int>] [-PromptText <string[]>] [-ViModeIndicator <ViModeStyle>] [-ViModeChangeHandler <scriptblock>] [-Colors <hashtable>] [<CommonParameters>]

Set foreground and background colors

Set-PSReadLineOption -Colors @{ "Comment"="$([char]0x1b)[32;47m" }Identify

Trips 1 Sigma rule: highPotential PowerShell Obfuscation Via WCHAR/CHAR by Florian Roth (Nextron Systems)

Set bell style

Set-PSReadLineOption -BellStyle Audible -DingTone 1221 -DingDuration 60Identify

Set multiple options

$PSReadLineOptions = @{
EditMode = "Emacs"
HistoryNoDuplicates = $true
HistorySearchCursorMovesToEnd = $true
Colors = @{
"Command" = "#8181f7"
}
}
Set-PSReadLineOption @PSReadLineOptions

Identify

Set multiple color options

Set-PSReadLineOption -Colors @{
Command = 'Magenta'
Number = 'DarkGray'
Member = 'DarkGray'
Operator = 'DarkGray'
Type = 'DarkGray'
Variable = 'DarkGreen'
Parameter = 'DarkGreen'
ContinuationPrompt = 'DarkGray'
Default = 'DarkGray'
}

Identify

Set color values for multiple types

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"
}

Identify

Trips 1 Sigma rule: highPotential PowerShell Obfuscation Via WCHAR/CHAR by Florian Roth (Nextron Systems)

Use ViModeChangeHandler to display Vi mode changes

function OnViModeChange {
if ($args[0] -eq 'Command') {
# Set the cursor to a blinking block.
Write-Host -NoNewline "$([char]0x1b)[1 q"
} else {
# Set the cursor to a blinking line.
Write-Host -NoNewline "$([char]0x1b)[5 q"
}
}
Set-PSReadLineOption -ViModeIndicator Script -ViModeChangeHandler $Function:OnViModeChange

Identify

Trips 1 Sigma rule: highPotential PowerShell Obfuscation Via WCHAR/CHAR by Florian Roth (Nextron Systems)

Use HistoryHandler to filter commands added to history

$ScriptBlock = {
param ([string]$Line)

if ($Line -match "^git") {
return $false
} else {
return $true
}
}

Set-PSReadLineOption -AddToHistoryHandler $ScriptBlock

Identify

Use CommandValidationHandler to validate a command before its executed

# Load the namespace so you can use the [CommandAst] object type
using namespace System.Management.Automation.Language

Set-PSReadLineOption -CommandValidationHandler {
param([CommandAst]$CommandAst)

switch ($CommandAst.GetCommandName()) {
'git' {
$gitCmd = $CommandAst.CommandElements[1].Extent
switch ($gitCmd.Text) {
'cmt' {
[Microsoft.PowerShell.PSConsoleReadLine]::Replace(
$gitCmd.StartOffset, $gitCmd.EndOffset - $gitCmd.StartOffset, 'commit')
}
}
}
}
}
# This checks the validation script when you hit enter
Set-PSReadLineKeyHandler -Chord Enter -Function ValidateAndAcceptLine

Identify

Using the PromptText parameter

function prompt { "PS $PWD> " }
Set-PSReadLineOption -PromptText '> ' # change the '>' character red
Set-PSReadLineOption -PromptText '> ', 'X ' # replace the '>' character with a red 'X'

Identify

Its page in the reference: Set-PSReadLineOption.

Parameters

23 in the PowerShell reference

Show its 23 parameters

-AddToHistoryHandlerSpecifies 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.

-AnsiEscapeTimeoutThis 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.

-BellStyleSpecifies how PSReadLine responds to various error and ambiguous conditions. The valid values are as follows: - Audible: A short beep. - Visual: Text flashes briefly. - None: No feedback.

-ColorsThe 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: - 256 color - 24-bit color - Foreground, background, or both - Inverse, bold For more information about ANSI color codes, see the Wikipedia article ANSI escape code. The valid keys include: - ContinuationPrompt: The color of the continuation prompt. - Emphasis: The emphasis color. For example, the matching text when searching history. - Error: The error color. For example, in the prompt. - Selection: The color to highlight the menu selection or selected text. - Default: The default token color. - Comment: The comment token color. - Keyword: The keyword token color. - String: The string token color. …

-CommandValidationHandlerSpecifies 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.

-CompletionQueryItemsSpecifies the maximum number of completion items that are shown without prompting. If the number of items to show is greater than this value, PSReadLine prompts yes/no before displaying the completion items.

-ContinuationPromptSpecifies 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.

-DingDurationSpecifies the duration of the beep when BellStyle is set to Audible.

-DingToneSpecifies the tone in Hertz (Hz) of the beep when BellStyle is set to Audible

-EditModeSpecifies the command line editing mode. Using this parameter resets any key bindings set by Set-PSReadLineKeyHandler. The valid values are as follows: - Windows: Key bindings emulate PowerShell, cmd, and Visual Studio. (default) - Emacs: Key bindings emulate Bash or Emacs. - Vi: Key bindings emulate Vi. Use Get-PSReadLineKeyHandler to see the key bindings for the currently configured EditMode.

-ExtraPromptLineCountSpecifies 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.

-HistoryNoDuplicatesThis 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

-HistorySavePathSpecifies the path to the file where history is 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: $Env:APPDATA\Microsoft\Windows\PowerShell\PSReadLine\$($Host.Name)_history.txt

-HistorySaveStyleSpecifies how PSReadLine saves history. Valid values are as follows: - 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. NOTE: If you set HistorySaveStyle to SaveNothing and then set it to SaveIncrementally later in the same session, PSReadLine saves all the commands previously run in the session.

-HistorySearchCaseSensitiveSpecifies 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

-HistorySearchCursorMovesToEndIndicates 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

-MaximumHistoryCountSpecifies the maximum number of commands to save in PSReadLine history. PSReadLine history is separate from PowerShell history.

-MaximumKillRingCountSpecifies the maximum number of items stored in the kill ring.

-PromptTextThis 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.

-ShowToolTipsWhen 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. 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

-ViModeChangeHandlerWhen 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.

-ViModeIndicatorThis 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.

-WordDelimitersSpecifies the characters that delimit words for functions like ForwardWord or KillWord.

Set-PSReadLineOption

What it does

Parameters

See also