Clipboard text support for PowerShell Core (cross-platform) and Windows PowerShell v2-v4

ClipboardText is a cross-edition, cross-platform PowerShell module that provides support for copying text to and retrieving text from the system clipboard, via the Set-ClipboardText and Get-ClipboardText cmdlets.

It is useful in the following scenarios:

• Use with PowerShell Core on (hopefully) all supported platforms.

  • As of v6.1, PowerShell Core doesn't ship with clipboard cmdlets.
  • This module fills this gap, albeit only with respect to text.
  • The implementation relies on external utilities (command-line programs) on all supported platforms:
    • Windows: clip.exe (built in)
    • macOS: pbcopy and pbpaste (built in)
    • Linux: xclip (requires installation via the system's package manager; e.g. sudo apt-get install xclip; available on X11-based freedesktop.org-compliant desktops, such as on Ubuntu)

• Use with older versions of Windows PowerShell.

  • Only since v5.0 does Windows PowerShell ship with Set-Clipboard and Get-Clipboard cmdlets.
  • This module fills the gap for v2-v4, albeit only with respect to text.
  • For implementing backward-compatible functionality, you may also use this module in v5+, in which case this module's cmdlets call the built-in ones behind the scenes.
  • On older versions, the implementation uses Windows Forms .NET types behind the scenes (namespace System.Windows.Forms)

• Use in universal scripts.

  • Universal scripts are scripts that run on both Windows PowerShell and Powershell Core, on all supported platforms, including older versions of Windows PowerShell; in this case, down to version 2.

Installation

Installation from the PowerShell Gallery

Prerequisite: The PowerShellGet module must be installed (verify with Get-Command Install-Module).
PowerShellGet comes with PowerShell version 5 or higher; it is possible to manually install it on versions 3 and 4 - see the docs.

• Current-user-only installation:

# Installation for the current user only.
PS> Install-Module ClipboardText -Scope CurrentUser

• All-users installation (requires elevation / sudo):

# Installation for ALL users.
# IMPORTANT: Requires an ELEVATED session:
#   On Windows: 
#     Right-click on the Windows PowerShell icon and select "Run as Administrator".
#   On Linux and macOS:
#     Run `sudo pwsh` from an existing terminal.
ELEV-PS> Install-Module ClipboardText -Scope AllUsers

See also: this repo's page in the PowerShell Gallery.

Manual Installation

If you're still using PowerShell v2, manual installation is your only option.

Clone this repository (as a subfolder) into one of the directories listed in the $env:PSModulePath variable; e.g., to install the module in the context of the current user, choose the following parent folders:

• Windows:
  • Windows PowerShell: $HOME\Documents\WindowsPowerShell\Modules
  • PowerShell Core: $HOME\Documents\PowerShell\Modules
• macOs, Linux (PowerShell Core):
  • $HOME/.local/share/powershell/Modules

As long as you've cloned into one of the directories listed in the $env:PSModulePath variable - copying to some of which requires elevation / sudo - and as long your $PSModuleAutoLoadingPreference is not set (the default) or set to All, calling Set-ClipboardText or Get-ClipboardText should import the module on demand - except in PowerShell v2.

To explicitly import the module, run Import-Module <path/to/module-folder>.

Example: Install as a current-user-only module:

Note: Assumes that git is installed.

# Switch to the parent directory of the current user's modules.
Set-Location $(if ($env:OS -eq 'Windows_NT') { "$HOME\Documents\{0}\Modules" -f ('WindowsPowerShell', 'PowerShell')[[bool]$IsCoreClr] } else { "$HOME/.local/share/powershell/Modules" })
# Clone this repo into subdir. 'ClipboardText'; --depth 1 gets only the latest revision.
git clone --depth 1 --quiet https://github.com/mklement0/ClipboardText

On Windows PowerShell v2, you must now explicitly load the module:

Import-Module -Verbose .\ClipboardText

Run Set-ClipboardText -? to verify that installation succeeded and that the module is loaded on demand (PSv3+): you should see brief CLI help text.

Usage

In short:

• Set-ClipboardText copies strings as-is; output from commands is copied using the same representation you see in the console, essentially obtained via Out-String; e.g.:

# Copy the full path of the current filesystem location to the clipbard:
$PWD.Path | Set-ClipboardText

# Copy the names of all files in the current directory to the clipboard:
Get-ChildItem -File -Name | Set-ClipboardText

• Get-ClipboardText retrieves text from the clipboard as an array of lines by default; use -Raw to request the text as-is, as a potentially multi-line string.

# Retrieve text from the clipboard as a single string and save it to a file:
Get-ClipboardText -Raw > out.txt

# Retrieve text from the clipboard as an array of lines and prefix each with
# a line number:
Get-ClipboardText | ForEach-Object { $i=0 } { '#{0}: {1}' -f (++$i), $_ }

For more, consult the built-in help after installation:

# Concise command-line help with terse description and syntax diagram.
Get-ClipboardText -?
Set-ClipboardText -?

# Full help, including parameter descriptions and details and examples.
Get-Help -Full Get-ClipboardText
Get-Help -Full Set-ClipboardText

# Examples only
Get-Help -Examples Get-ClipboardText
Get-Help -Examples Set-ClipboardText

License

See LICENSE.md.

Changelog

See CHANGELOG.md.