• Stars
    star
    3,700
  • Rank 11,944 (Top 0.3 %)
  • Language
    C#
  • License
    BSD 2-Clause "Sim...
  • Created over 11 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A bash inspired readline implementation for PowerShell

appveyor-build-status

PSReadLine

This module replaces the command line editing experience of PowerShell for versions 3 and up. It provides:

  • Syntax coloring
  • Simple syntax error notification
  • A good multi-line experience (both editing and history)
  • Customizable key bindings
  • Cmd and emacs modes (neither are fully implemented yet, but both are usable)
  • Many configuration options
  • Bash style completion (optional in Cmd mode, default in Emacs mode)
  • Bash/zsh style interactive history search (CTRL-R)
  • Emacs yank/kill ring
  • PowerShell token based "word" movement and kill
  • Undo/redo
  • Automatic saving of history, including sharing history across live sessions
  • "Menu" completion (somewhat like Intellisense, select completion with arrows) via Ctrl+Space

The "out of box" experience is meant to be very familiar to PowerShell users - there should be no need to learn any new key strokes.

Some good resources about PSReadLine:

  • Keith Hill wrote a great introduction (2013) to PSReadLine.
  • Ed Wilson (Scripting Guy) wrote a series (2014-2015) on PSReadLine.
  • John Savill has a video (2021) covering installation, configuration, and tailoring PSReadLine to your liking.

Installation

There are multiple ways to install PSReadLine.

Install from PowerShellGallery (preferred)

You will need the 1.6.0 or a higher version of PowerShellGet to install the latest prerelease version of PSReadLine.

Windows PowerShell 5.1 ships an older version of PowerShellGet which doesn't support installing prerelease modules, so Windows PowerShell users need to install the latest PowerShellGet (if not yet) by running the following commands from an elevated Windows PowerShell session:

Install-Module -Name PowerShellGet -Force
Exit

After installing PowerShellGet, you can get the latest prerelease version of PSReadLine by running

Install-Module PSReadLine -AllowPrerelease -Force

If you only want to get the latest stable version, run:

Install-Module PSReadLine

[!NOTE] Prerelease versions will have newer features and bug fixes, but may also introduce new issues.

If you are using Windows PowerShell on Windows 10 or using PowerShell 6+, PSReadLine is already installed. Windows PowerShell on the latest Windows 10 has version 2.0.0-beta2 of PSReadLine. PowerShell 6+ versions have the newer prerelease versions of PSReadLine.

Install from GitHub (deprecated)

With the preview release of PowerShellGet for PowerShell V3/V4, downloads from GitHub are deprecated. We don't intend to update releases on GitHub, and may remove the release entirely from GitHub at some point.

Post Installation

If you are using Windows PowerShell V5 or V5.1 versions, or using PowerShell 6+ versions, you are good to go and can skip this section.

Otherwise, you need to edit your profile to import the module. There are two profile files commonly used and the instructions are slightly different for each. The file C:\Users\[User]\Documents\WindowsPowerShell\profile.ps1 is used for all hosts (e.g. the ISE and powershell.exe). If you already have this file, then you should add the following:

if ($host.Name -eq 'ConsoleHost')
{
    Import-Module PSReadLine
}

Alternatively, the file C:\Users\[User]\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 is for powershell.exe only. Using this file, you can simply add:

Import-Module PSReadLine

In either case, you can create the appropriate file if you don't already have one.

Upgrading

When running one of the suggested commands below, be sure to exit all instances of powershell.exe, pwsh.exe or pwsh, including those opened in VSCode terminals.

Then, to make sure PSReadLine isn't loaded:

  • if you are on Windows, run the suggested command below from cmd.exe, powershell_ise.exe, or via the Win+R shortcut;
  • if you are on Linux/macOS, run the suggested command below from the default terminal (like bash or zsh).

If you are using the version of PSReadLine that ships with Windows PowerShell, you need to run: powershell -noprofile -command "Install-Module PSReadLine -Force -SkipPublisherCheck -AllowPrerelease". Note: you will need to make sure PowershellGet is updated before running this command.

If you are using the version of PSReadLine that ships with PowerShell 6+ versions, you need to run: <path-to-pwsh-executable> -noprofile -command "Install-Module PSReadLine -Force -SkipPublisherCheck -AllowPrerelease".

If you've installed PSReadLine yourself from the PowerShell Gallery, you can simply run: powershell -noprofile -command "Update-Module PSReadLine -AllowPrerelease" or <path-to-pwsh-executable> -noprofile -command "Update-Module PSReadLine -AllowPrerelease", depending on the version of PowerShell you are using.

If you get an error like:

Remove-Item : Cannot remove item
C:\Users\{yourName}\Documents\WindowsPowerShell\Modules\PSReadLine\Microsoft.PowerShell.PSReadLine.dll: Access to the path
'C:\Users\{yourName}\Documents\WindowsPowerShell\Modules\PSReadLine\Microsoft.PowerShell.PSReadLine.dll' is denied.

or a warning like:

WARNING: The version '2.0.0' of module 'PSReadLine' is currently in use. Retry the operation after closing the applications.

Then you didn't kill all the processes that loaded PSReadLine.

Usage

To start using, just import the module:

Import-Module PSReadLine

To use Emacs key bindings, you can use:

Set-PSReadLineOption -EditMode Emacs

To view the current key bindings:

Get-PSReadLineKeyHandler

There are many configuration options, see the options to Set-PSReadLineOption. PSReadLine has help for it's cmdlets as well as an about_PSReadLine topic - see those topics for more detailed help.

To set your own custom keybindings, use the cmdlet Set-PSReadLineKeyHandler. For example, for a better history experience, try:

Set-PSReadLineKeyHandler -Key UpArrow -Function HistorySearchBackward
Set-PSReadLineKeyHandler -Key DownArrow -Function HistorySearchForward

With these bindings, up arrow/down arrow will work like PowerShell/cmd if the current command line is blank. If you've entered some text though, it will search the history for commands that start with the currently entered text.

To enable bash style completion without using Emacs mode, you can use:

Set-PSReadLineKeyHandler -Key Tab -Function Complete

Here is a more interesting example of what is possible:

Set-PSReadLineKeyHandler -Chord '"',"'" `
                         -BriefDescription SmartInsertQuote `
                         -LongDescription "Insert paired quotes if not already on a quote" `
                         -ScriptBlock {
    param($key, $arg)

    $line = $null
    $cursor = $null
    [Microsoft.PowerShell.PSConsoleReadLine]::GetBufferState([ref]$line, [ref]$cursor)

    if ($line.Length -gt $cursor -and $line[$cursor] -eq $key.KeyChar) {
        # Just move the cursor
        [Microsoft.PowerShell.PSConsoleReadLine]::SetCursorPosition($cursor + 1)
    }
    else {
        # Insert matching quotes, move cursor to be in between the quotes
        [Microsoft.PowerShell.PSConsoleReadLine]::Insert("$($key.KeyChar)" * 2)
        [Microsoft.PowerShell.PSConsoleReadLine]::GetBufferState([ref]$line, [ref]$cursor)
        [Microsoft.PowerShell.PSConsoleReadLine]::SetCursorPosition($cursor - 1)
    }
}

In this example, when you type a single quote or double quote, there are two things that can happen. If the character following the cursor is not the quote typed, then a matched pair of quotes is inserted and the cursor is placed inside the the matched quotes. If the character following the cursor is the quote typed, the cursor is simply moved past the quote without inserting anything. If you use Resharper or another smart editor, this experience will be familiar.

Note that with the handler written this way, it correctly handles Undo - both quotes will be undone with one undo.

The sample profile file has a bunch of great examples to check out. This file is included when PSReadLine is installed.

See the public methods of [Microsoft.PowerShell.PSConsoleReadLine] to see what other built-in functionality you can modify.

If you want to change the command line in some unimplmented way in your custom key binding, you can use the methods:

    [Microsoft.PowerShell.PSConsoleReadLine]::GetBufferState
    [Microsoft.PowerShell.PSConsoleReadLine]::Insert
    [Microsoft.PowerShell.PSConsoleReadLine]::Replace
    [Microsoft.PowerShell.PSConsoleReadLine]::SetCursorPosition

Developing and Contributing

Please see the Contribution Guide for how to develop and contribute.

Building

To build PSReadLine on Windows, Linux, or macOS, you must have the following installed:

  • .NET Core SDK 2.1.802 or a newer version
  • The PowerShell modules InvokeBuild and platyPS

The build script build.ps1 can be used to bootstrap, build and test the project.

  • Bootstrap: ./build.ps1 -Bootstrap
  • Build:
    • Targeting .NET 4.6.2 (Windows only): ./build.ps1 -Configuration Debug -Framework net462
    • Targeting .NET Core: ./build.ps1 -Configuration Debug -Framework netcoreapp2.1
  • Test:
    • Targeting .NET 4.6.2 (Windows only): ./build.ps1 -Test -Configuration Debug -Framework net462
    • Targeting .NET Core: ./build.ps1 -Test -Configuration Debug -Framework netcoreapp2.1

After build, the produced artifacts can be found at <your-local-repo-root>/bin/Debug. In order to isolate your imported module to the one locally built, be sure to run pwsh -NonInteractive -NoProfile to not automatically load the default PSReadLine module installed. Then, load the locally built PSReadLine module by Import-Module <your-local-repo-root>/bin/Debug/PSReadLine/PSReadLine.psd1.

Change Log

The change log is available here.

Licensing

PSReadLine is licensed under the 2-Clause BSD License.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

More Repositories

1

PowerShell

PowerShell for every system!
C#
45,459
star
2

Win32-OpenSSH

Win32 port of OpenSSH
7,290
star
3

PSScriptAnalyzer

Download ScriptAnalyzer from PowerShellGallery
C#
1,842
star
4

vscode-powershell

Provides PowerShell language and debugging support for Visual Studio Code
TypeScript
1,687
star
5

DscResources

Central repository for PowerShell Desired State Configuration (DSC) resources.
772
star
6

ConsoleGuiTools

Modules that mix PowerShell and GUIs/CUIs!
C#
772
star
7

platyPS

Write PowerShell External Help in Markdown
C#
765
star
8

PowerShellEditorServices

A common platform for PowerShell development support in any editor or application!
C#
623
star
9

Polaris

A cross-platform, minimalist web framework for PowerShell
PowerShell
507
star
10

PSResourceGet

PSResourceGet is the package manager for PowerShell
C#
483
star
11

PowerShellGetv2

PowerShellGet is the Package Manager for PowerShell
PowerShell
430
star
12

PowerShell-RFC

RFC (Request for Comments) documents for community feedback on design changes and improvements to PowerShell ecosystem
PowerShell
430
star
13

PowerShell-Docker

Repository for building PowerShell Docker images
Dockerfile
400
star
14

Crescendo

a module for wrapping native applications in a PowerShell function and module
PowerShell
397
star
15

SecretManagement

PowerShell module to consistent usage of secrets through different extension vaults
C#
321
star
16

JEA

Just Enough Administration
PowerShell
254
star
17

PowerShellGallery

PowerShell
228
star
18

Operation-Validation-Framework

PowerShell
223
star
19

DSC

This repo is for the DSC v3 project
Rust
192
star
20

SHiPS

Simple Hierarchy in PowerShell - developing PowerShell provider got so much easier
C#
188
star
21

PSSwagger

The cmdlet generator from OpenAPI (f.k.a Swagger) specification
PowerShell
164
star
22

PowerShellStandard

C#
157
star
23

SecretStore

C#
155
star
24

PSPrivateGallery

DSC Resources and Configurations to deploy and manage Private PowerShell Gallery
PowerShell
148
star
25

CompletionPredictor

C#
145
star
26

GPRegistryPolicyParser

PowerShell
140
star
27

WindowsCompatibility

Module that allows Windows PowerShell Modules to be used from PSCore6
PowerShell
137
star
28

PowerShell-Tests

Pester based tests for testing PowerShell
PowerShell
130
star
29

PowerShell-IoT

Interact with I2C, SPI & GPIO devices using PowerShell Core!
C#
130
star
30

PSDscResources

PowerShell
129
star
31

EditorSyntax

PowerShell syntax highlighting for editors (VS Code, Atom, SublimeText, TextMate, etc.) and GitHub!
PowerShell
127
star
32

Modules

C#
111
star
33

Phosphor

A library and PowerShell module for generating user interfaces from PowerShell modules
TypeScript
109
star
34

GPRegistryPolicy

PowerShell
102
star
35

Community-Blog

Submissions for posts to the PowerShell Community Blog -https://devblogs.microsoft.com/powershell-community
102
star
36

psl-omi-provider

PSRP Linux support library
C
100
star
37

Microsoft.PowerShell.Archive

Archive PowerShell module contains cmdlets for working with ZIP archives
C#
93
star
38

PSArm

PSArm is a PowerShell module that provides a PowerShell-embedded domain-specific language (DSL) for Azure Resource Manager (ARM) templates
C#
77
star
39

Remotely

Enable remote execution of scripts. Works with Pester.
PowerShell
74
star
40

TextUtility

Microsoft.PowerShell.TextUtility module
C#
64
star
41

PSDesiredStateConfiguration

Source for https://www.powershellgallery.com/packages/PSDesiredStateConfiguration module
PowerShell
59
star
42

ProjectMercury

An interactive shell to work with AI-powered assistance providers
C#
56
star
43

Demo_CI

PowerShell
55
star
44

PowerShellGet

This module provide functions used with PowerShellGet v3 to provide compatibility with scripts expecting PowerShellGet v2
PowerShell
55
star
45

DscResource.Tests

Common meta tests for PowerShell DSC resources repositories.
PowerShell
51
star
46

PowerShell-Native

C++
48
star
47

Whitepapers

Staging area for new documents and whitepapers
46
star
48

AzurePSDrive

Navigate Azure Resources Just like A FileSystem
PowerShell
41
star
49

ContainerProvider

ContainerImageProvider
PowerShell
38
star
50

PrivateCloud.DiagnosticInfo

PowerShell
38
star
51

PackageManagementProviderResource

Modules with DSC resources for the PackageManagement(aka OneGet) providers.
PowerShell
37
star
52

Pager

Project for console pager, which is published as a NuGet package Microsoft.PowerShell.Pager
C#
34
star
53

MarkdownRender

C#
32
star
54

DSC-Samples

Samples and tutorials for DSC v3
Go
29
star
55

PlasterBuild

Provides common build tasks for PowerShell module projects
PowerShell
29
star
56

PowerShell-Snap

PowerShell
28
star
57

SelfSignedCertificate

A module for generating self-signed certificates in PowerShell Core
PowerShell
27
star
58

CimPSDrive

SHiPS based provider to navigate CIM classes and namespaces
PowerShell
27
star
59

DscConfigurations

PowerShell
27
star
60

tree-sitter-PowerShell

JavaScript
25
star
61

GitHub-Actions

PowerShell
25
star
62

MMI

C#
24
star
63

Microsoft.PowerShell.Kubectl

PowerShell module to manage Kubernetes
PowerShell
23
star
64

LibreSSL

C
22
star
65

ODataUtils

PowerShell Module to generate cmdlets from an OData endpoint
PowerShell
22
star
66

ThreadJob

PowerShell
22
star
67

WmiNamespaceSecurityDsc

This module contains DSC resources to manage WMI Namespace Security.
PowerShell
21
star
68

FileUtility

C#
21
star
69

UnixCompleters

C#
20
star
70

Homebrew-Tap

Ruby
19
star
71

underhanded-powershell

Underhanded PowerShell Contest Repository
PowerShell
18
star
72

Hardware-Management-Module

PowerShell
17
star
73

generator-powershell

Create PowerShell modules and scripts using Yeoman!
JavaScript
16
star
74

Announcements

PowerShell Team Announcements
15
star
75

JsonAdapter

C#
14
star
76

PowerShellModuleCoverage

Track issues related to using Windows PowerShell modules with PowerShell
13
star
77

whatsnew

PowerShell
13
star
78

PSRelease

PowerShell
11
star
79

AwsDscToolkit

AWS DSC Toolkit
PowerShell
10
star
80

DscResource.Template

PowerShell
10
star
81

command-not-found

C#
10
star
82

TemplateConfig

Provides template for organizing DSC configuration scripts and supporting modules
PowerShell
10
star
83

SystemLocaleDsc

DSC Resource for configuring Windows System Locale
PowerShell
9
star
84

SmartPackageProvider

A PackageManagement provider to find and install packages using search engines
C#
9
star
85

xDisk

PowerShell
8
star
86

psl-pester

Fork of Pester for compatibility with PowerShell on Linux.
PowerShell
8
star
87

PowerShell-Blog-Samples

Samples for the PowerShell blog
PowerShell
8
star
88

ZLib

C
7
star
89

AWSBootStrapper

PowerShell
6
star
90

WSAProvider

A PackageManagement provider to find and install packages for Appx based packaging format
PowerShell
6
star
91

PowerShellGetDsc

DSCResources for the PowerShellGet module
PowerShell
5
star
92

DscConfiguration.Tests

Test automation scripts for evaluating the quality of DSC Configurations using Azure virtual machines and Azure Automation DSC.
PowerShell
5
star
93

SILDeploymentHelper

PowerShell
4
star
94

vscode-powershellise-keybindings

A Visual Studio Code extension that configures PowerShell ISE keybindings.
TypeScript
4
star
95

PSPackageProject

PowerShell
4
star
96

Compliance

3
star
97

.github

3
star
98

ISEAddOnExamples

3
star
99

pscore-docs-dotnet

PowerShell
2
star
100

JsonAdapterFeedbackPredictor

1
star