Set-PSReadlineOption
Customizes the behavior of command line editing in PSReadline.
Syntax
OptionsSet
Set-PSReadlineOption
[-EditMode <EditMode>]
[-ContinuationPrompt <String>]
[-ContinuationPromptForegroundColor <ConsoleColor>]
[-ContinuationPromptBackgroundColor <ConsoleColor>]
[-EmphasisForegroundColor <ConsoleColor>]
[-EmphasisBackgroundColor <ConsoleColor>]
[-ErrorForegroundColor <ConsoleColor>]
[-ErrorBackgroundColor <ConsoleColor>]
[-HistoryNoDuplicates]
[-AddToHistoryHandler <Func[string,bool]>]
[-CommandValidationHandler <Action[CommandAst]>]
[-HistorySearchCursorMovesToEnd]
[-MaximumHistoryCount <Int32>]
[-MaximumKillRingCount <Int32>]
[-ResetTokenColors]
[-ShowToolTips]
[-ExtraPromptLineCount <Int32>]
[-DingTone <Int32>]
[-DingDuration <Int32>]
[-BellStyle <BellStyle>]
[-CompletionQueryItems <Int32>]
[-WordDelimiters <String>]
[-HistorySearchCaseSensitive]
[-HistorySaveStyle <HistorySaveStyle>]
[-HistorySavePath <String>]
[<CommonParameters>]
ColorSet
Set-PSReadlineOption
[-TokenKind] <TokenClassification>
[[-ForegroundColor] <ConsoleColor>]
[[-BackgroundColor] <ConsoleColor>]
[<CommonParameters>]
Description
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.
Examples
Example 1: Set foreground and background colors
This example sets PSReadline to display the Comment token with green foreground text on a gray background.
Set-PSReadlineOption -TokenKind Comment -ForegroundColor Green -BackgroundColor Gray
Example 2: Set bell style
In this example, PSReadline will respond to errors or conditions that require user attention. The BellStyle is set to emit an audible beep at 1221 Hz for 60 ms.
Set-PSReadlineOption -BellStyle Audible -DingTone 1221 -DingDuration 60
Parameters
-AddToHistoryHandler
Specifies a ScriptBlock that controls which commands get added to PSReadline history.
The ScriptBlock receives the command line as input. If the ScriptBlock returns $True, the
command line is added to the history.
Parameter properties
| Type: | Func[String, Boolean] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-BackgroundColor
Specifies the background color for the token specified by the TokenKind parameter.
The acceptable values for this parameter are as follows:
- Black
- DarkBlue
- DarkGreen
- DarkCyan
- DarkRed
- DarkMagenta
- DarkYellow
- Gray
- DarkGray
- Blue
- Green
- Cyan
- Red
- Magenta
- Yellow
- White
Parameter properties
| Type: | ConsoleColor |
| Default value: | None |
| Accepted values: | Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
ColorSet
| Position: | 2 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-BellStyle
Specifies 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.
Parameter properties
| Type: | BellStyle |
| Default value: | Audible |
| Accepted values: | None, Visual, Audible |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-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, such as to correct common typographical errors.
ValidateAndAcceptLine is used to avoid cluttering your history with commands that can't work.
Parameter properties
| Type: | Action[CommandAst] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-CompletionQueryItems
Specifies 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.
Parameter properties
| Type: | Int32 |
| Default value: | 100 |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ContinuationPrompt
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.
Parameter properties
| Type: | String |
| Default value: | >> |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ContinuationPromptBackgroundColor
Specifies the background color of the continuation prompt.
The acceptable values are the same as the BackgroundColor parameter.
Parameter properties
| Type: | ConsoleColor |
| Default value: | None |
| Accepted values: | Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
OptionsSet
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ContinuationPromptForegroundColor
Specifies the foreground color of the continuation prompt.
The acceptable values are the same as the BackgroundColor parameter.
Parameter properties
| Type: | ConsoleColor |
| Default value: | None |
| Accepted values: | Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
OptionsSet
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-DingDuration
Specifies the duration of the beep when BellStyle is set to Audible.
Parameter properties
| Type: | Int32 |
| Default value: | 50ms |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-DingTone
Specifies the tone in Hertz (Hz) of the beep when BellStyle is set to Audible.
Parameter properties
| Type: | Int32 |
| Default value: | 1221 |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-EditMode
Specifies 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.
- Emacs: Key bindings emulate Bash or Emacs.
- Vi: Key bindings emulate Vi.
Parameter properties
| Type: | EditMode |
| Default value: | Windows |
| Accepted values: | Windows, Emacs, Vi |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-EmphasisBackgroundColor
Specifies the background color that's used for emphasis, such as to highlight search text.
The acceptable values are the same as the BackgroundColor parameter.
Parameter properties
| Type: | ConsoleColor |
| Default value: | None |
| Accepted values: | Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
OptionsSet
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-EmphasisForegroundColor
Specifies the foreground color that's used for emphasis, such as to highlight search text.
The acceptable values are the same as the BackgroundColor parameter.
Parameter properties
| Type: | ConsoleColor |
| Default value: | None |
| Accepted values: | Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
OptionsSet
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ErrorBackgroundColor
Specifies the background color that's used for errors.
The acceptable values are the same as the BackgroundColor parameter.
Parameter properties
| Type: | ConsoleColor |
| Default value: | None |
| Accepted values: | Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
OptionsSet
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ErrorForegroundColor
Specifies the foreground color that's used for errors.
The acceptable values are the same as the BackgroundColor parameter.
Parameter properties
| Type: | ConsoleColor |
| Default value: | None |
| Accepted values: | Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
OptionsSet
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ExtraPromptLineCount
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.
Parameter properties
| Type: | Int32 |
| Default value: | 0 |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ForegroundColor
Specifies the foreground color for the token that's specified by the TokenKind parameter.
The acceptable values are the same as the BackgroundColor parameter.
Parameter properties
| Type: | ConsoleColor |
| Default value: | None |
| Accepted values: | Black, DarkBlue, DarkGreen, DarkCyan, DarkRed, DarkMagenta, DarkYellow, Gray, DarkGray, Blue, Green, Cyan, Red, Magenta, Yellow, White |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
ColorSet
| Position: | 1 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-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.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-HistorySavePath
Specifies the path to the file where history is saved. The file name 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:
$env:APPDATA\Microsoft\Windows\PowerShell\PSReadline\$($host.Name)_history.txt
Parameter properties
| Type: | String |
| Default value: | $env:APPDATA\Microsoft\Windows\PowerShell\PSReadline\$($host.Name)_history.txt |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-HistorySaveStyle
Specifies 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.
Parameter properties
| Type: | HistorySaveStyle |
| Default value: | SaveIncrementally |
| Accepted values: | SaveIncrementally, SaveAtExit, SaveNothing |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-HistorySearchCaseSensitive
Specifies that history searching is case-sensitive in functions like ReverseSearchHistory or HistorySearchBackward.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
To turn off this option, you can run either of the following commands:
Set-PSReadlineOption -HistorySearchCursorMovesToEnd:$False
(Get-PSReadlineOption).HistorySearchCursorMovesToEnd = $False
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-MaximumHistoryCount
Specifies the maximum number of commands to save in PSReadline history.
PSReadline history is separate from PowerShell history.
Parameter properties
| Type: | Int32 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-MaximumKillRingCount
Specifies the maximum number of items stored in the kill ring.
Parameter properties
| Type: | Int32 |
| Default value: | 10 |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ResetTokenColors
Indicates that this cmdlet restores token colors to default settings.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
OptionsSet
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-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.
Parameter properties
| Type: | SwitchParameter |
| Default value: | True |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-TokenKind
Specifies the token when you set token color options with the ForegroundColor and BackgroundColor parameters.
The acceptable values for this parameter are as follows:
- None
- Comment
- Keyword
- String
- Operator
- Variable
- Command
- Parameter
- Type
- Number
- Member
Parameter properties
| Type: | TokenClassification |
| Default value: | None |
| Accepted values: | None, Comment, Keyword, String, Operator, Variable, Command, Parameter, Type, Number, Member |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
ColorSet
| Position: | 0 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-WordDelimiters
Specifies the characters that delimit words for functions like ForwardWord or KillWord.
Parameter properties
| Type: | String |
| Default value: | ;:,.[]{}()/\|^&*-=+–—― |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
Inputs
None
You can't send objects down the pipeline to Set-PSReadlineOption.
Outputs
None
Set-PSReadlineOption doesn't generate output.