Using PSReadLine key handlers

Article
03/29/2023

The PSReadLine module provides key handlers that map PSReadLine functions to keyboard chords. Keyboard chords are a sequence of one or more keystrokes that are pressed at the same time. For example, the chord Ctrl+Spacebar is the combination of the Ctrl and Spacebar keys pressed at the same time. A PSReadLine function is a predefined action that can be performed on a command line. For example, the MenuComplete function allows you to choose from a list of options from a menu complete the input on the command line.

PSReadLine has several predefined key handlers that are bound by default. You can also define your own custom key handlers. Run the following command to list the key handlers that are currently defined.

Get-PSReadLineKeyHandler

You can also get a list of all unbound PSReadLine functions that are available to be bound to a key chord.

Get-PSReadLineKeyHandler -Unbound

You can use the Set-PSReadLineKeyHandler cmdlet to bind a function to a key handler. The following command binds the MenuComplete function to the chord Ctrl+Spacebar.

Set-PSReadLineKeyHandler -Chord 'Ctrl+Spacebar' -Function MenuComplete

Finding key names and chord bindings

The names of the keys in the chord are defined by the [System.ConsoleKey] enumeration. For more information, see System.ConsoleKey documentation. For example, the name of the 2 key in [System.ConsoleKey] is D2, whereas the name of the 2 key on the numeric keypad is NumPad2. You can use the [System.Console]::ReadKey() method to find the name of the key you pressed.

[System.Console]::ReadKey()

The following output shows the information returned by the ReadKey() method for the Ctrl+2 key chord.

KeyChar Key Modifiers
------- --- ---------
        D2   Control

For the PSReadLine key handler cmdlets, this chord is represented as Ctrl+D2. The following example binds this chord to a function.

Set-PSReadLineKeyHandler -Chord 'Ctrl+D2' -Function MenuComplete

You can bind multiple cords to a single function. By default, the BackwardDeleteChar function is bound to two chords.

Get-PSReadLineKeyHandler -Chord Backspace, Ctrl+h

Key       Function           Description
---       --------           -----------
Backspace BackwardDeleteChar Delete the character before the cursor
Ctrl+h    BackwardDeleteChar Delete the character before the cursor

Note

The Chord parameter is case-sensitive. Meaning, you can create different bindings for Ctrl+X and Ctrl+x.

On Windows, you can also use the Alt+? key chord to show the function bound to the next key chord you enter. When you type Alt+? you see the following prompt:

what-is-key:

When you hit the Backspace key you get the following response:

Backspace: BackwardDeleteChar - Delete the character before the cursor

Key handlers on non-Windows computers

The key codes generated by your keyboard can be different depending on the operating system and terminal application you are using.

macOS

The Macintosh keyboard doesn't have an Alt key like Windows and Linux systems. Instead, it has the ⌥ Option key. macOS uses this key differently than the Alt key on other systems. However, you can configure the terminal and iTerm2 applications on macOS to treat it as an Alt key.

Configuring the Terminal application

Open the Settings window from the App bar in Terminal.app. Select Profiles and choose the profile you want to configure. Select the Keyboard tab of the configuration options. Below the list of keys, select the Use Option as Meta Key setting. This setting allows the ⌥ Option key to act as Alt in the Terminal application.

Screenshot of Terminal.app settings.

Configuring the iTerm2 application

Open the Settings window from the App Bar in iTerm.app. Select Profiles and choose the profile you want to configure. Select the Keys tab of the configuration options. Select the Esc+ option for both the Left Option Key and Right Option Key settings. This setting allows the ⌥ Option key to act as Alt in the iTerm application.

Screenshot of iTerm.app settings.

Note

The exact steps may vary depending on the versions of macOS and the terminal applications. These examples were captured on macOS Ventura 13.2.1 and iTerm2 v3.4.16.

Linux

On Linux platforms, the key code generated can be different than other systems. For example:

Ctrl+[ is the same as Escape
Ctrl+Spacebar generates the key codes for Ctrl+D2. If you want to map a function Ctrl+Spacebar you must use the chord Ctrl+D2.
```
Set-PSReadLineKeyHandler -Chord 'Ctrl+D2' -Function MenuComplete
```

Use the ReadKey() method to verify the key codes generated by your keyboard.

Commonly used key handlers

Here are a few commonly used key handlers that are bound by default on Windows. Note that the key binding may be different on non-Windows platforms.

MenuComplete

Complete the input by selecting from a menu of possible completion values.

Default chord: Ctrl+Spacebar

The following example shows the menu of possible completions for commands beginning with select.

PS C:\> select<Ctrl+Spacebar>
select                   Select-Object            Select-PSFPropertyValue  Select-Xml
Select-AzContext         Select-PSFConfig         Select-PSMDBuildProject
Select-AzSubscription    Select-PSFObject         Select-String

Select-Object

Use the arrow keys to select the completion you want. Press the Enter key to complete the input. As you move through the selections, help for the selected command is displayed below the menu.

ClearScreen

This function clears the screen similar to the cls or clear commands.

Default chord: Ctrl+l

SelectCommandArgument

Selects the next argument on the command line.

Default chord: Alt+a

You may have command in your history that you want to run again with different parameter values. You can use the chord to cycle through each parameter and change the value as needed.

New-AzVM -ResourceGroupName myRGName -Location eastus -Name myVM

Pressing Alt+a selects the next parameter argument in turn: myRGName, eastus, myVM.

GotoBrace

Moves the cursor to the matching brace.

Default chord: Ctrl+]

This functions moves your cursor to the closing brace that matches the brace at the current cursor position on the command line. The function works for brackets ([]), braces ({}), and parentheses, (()).

DigitArgument

Start or accumulate a numeric argument use to repeat a keystroke the specified number of times.

Default chord: Alt+0 through Alt+9

For example, typing Alt+4+# enters #### on the command line.