Using PSReadLine key handlers
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.
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.
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.
