Share via

Set-PSReadLineKeyHandler

  • Reference
Module:
PSReadLine

Binds keys to user-defined or PSReadLine key handler functions.

Syntax

Set-PSReadLineKeyHandler
   [-ScriptBlock] <ScriptBlock>
   [-BriefDescription <String>]
   [-Description <String>]
   [-Chord] <String[]>
   [-ViMode <ViMode>]
   [<CommonParameters>]
Set-PSReadLineKeyHandler
   [-Chord] <String[]>
   [-ViMode <ViMode>]
   [-Function] <String>
   [<CommonParameters>]

Description

The Set-PSReadLineKeyHandler cmdlet customizes the result when a key or sequence of keys is pressed. With user-defined key bindings, you can do almost anything that is possible from within a PowerShell script.

Examples

Example 1: Bind the arrow key to a function

This command binds the up arrow key to the HistorySearchBackward function. This function searches command history for command lines that start with the current contents of the command line.

Set-PSReadLineKeyHandler -Chord UpArrow -Function HistorySearchBackward

Example 2: Bind a key to a script block

This example shows how a single key can be used to run a command. The command binds the key Ctrl+B to a script block that clears the line, inserts the word "build", and then accepts the line.

Set-PSReadLineKeyHandler -Chord Ctrl+B -ScriptBlock {
    [Microsoft.PowerShell.PSConsoleReadLine]::RevertLine()
    [Microsoft.PowerShell.PSConsoleReadLine]::Insert('build')
    [Microsoft.PowerShell.PSConsoleReadLine]::AcceptLine()
}

Parameters

-BriefDescription

A brief description of the key binding. This description is displayed by the Get-PSReadLineKeyHandler cmdlet.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Chord

The key or sequence of keys to be bound to a function or script block. Use a single string to specify a single binding. If the binding is a sequence of keys, separate the keys by a comma, as in the following example:

Ctrl+X,Ctrl+L

Note

As of PSReadLine 2.0.0, the Chord parameter is case-sensitive. Meaning, Ctrl+X and Ctrl+x create different bindings.

This parameter accepts an array of strings. Each string is a separate binding, not a sequence of keys for a single binding.

Type:String[]
Aliases:Key
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Description

Specifies a more detailed description of the key binding that is visible in the output of the Get-PSReadLineKeyHandler cmdlet.

Type:String
Aliases:LongDescription
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Function

Specifies the name of an existing key handler provided by PSReadLine. This parameter lets you rebind existing key bindings, or bind a handler that is currently unbound.

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ScriptBlock

Specifies a script block value to run when the chord is entered. PSReadLine passes one or two parameters to this script block. The first parameter is a ConsoleKeyInfo object representing the key pressed. The second argument can be any object depending on the context.

Type:ScriptBlock
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ViMode

Specify which vi mode the binding applies to.

Valid values are:

  • Insert
  • Command
Type:ViMode
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Inputs

None

You cannot pipe objects to this cmdlet.

Outputs

None

This cmdlet does not generate any output.