tmux client library for PowerShell

Control tmux, connect to and create servers, navigate sessions, windows, and panes, send keys, watch for changes via control mode, capture pane contents.

Topics

Subject-by-subject, with PowerShell in every code block.

Examples

Complete programs, sourced from the code each port tests.

API reference

Types and functions of the PowerShell API.

Install

Install-Module -Name LibTmux

At a glance

Server → Session → Window → Pane. Each level of the tmux hierarchy has its own entry in the PowerShell API, with the tmux object it wraps.

Type	Wraps
`LibTmux\Get-TmuxServer`	A tmux server
`LibTmux\Get-TmuxSession`	A session, ID `$n`
`LibTmux\Get-TmuxWindow`	A window in a session, ID `@n`
`LibTmux\Get-TmuxPane`	A pane in a window, ID `%n`

What it does

Start with PowerShell

+ Error handling + Cleanup

$ErrorActionPreference = 'Stop'
Import-Module "$PSScriptRoot/modules/LibTmux/0.1.0/LibTmux.psd1"

$socket = 'libtmux-home-' + [Guid]::NewGuid().ToString('N')
$server = New-TmuxServer -SocketName $socket -ConfigurationFile /dev/null

$session = $server | New-TmuxSession `
    -Name demo -WindowName editor -Command 'exec /bin/cat'
$pane = $session | Get-TmuxPane
$null = $pane | Split-TmuxPane -Horizontal -Command 'exec /bin/cat'
$null = $session | New-TmuxWindow -Name logs -Command 'exec /bin/cat'

$captured = ($server | Get-TmuxSnapshot).Sessions |
    Select-TmuxSession -Criteria @{ Name = 'demo' } -ExactlyOne
foreach ($window in $captured.Windows) {
    '{0}: {1}' -f $window.Name, ($window.Panes.Id -join ', ')
}

$ErrorActionPreference = 'Stop'
Import-Module "$PSScriptRoot/modules/LibTmux/0.1.0/LibTmux.psd1"

try {
    $socket = 'libtmux-home-' + [Guid]::NewGuid().ToString('N')
    $server = New-TmuxServer -SocketName $socket -ConfigurationFile /dev/null

    $session = $server | New-TmuxSession `
        -Name demo -WindowName editor -Command 'exec /bin/cat'
    $pane = $session | Get-TmuxPane
    $null = $pane | Split-TmuxPane -Horizontal -Command 'exec /bin/cat'
    $null = $session | New-TmuxWindow -Name logs -Command 'exec /bin/cat'

    $captured = ($server | Get-TmuxSnapshot).Sessions |
        Select-TmuxSession -Criteria @{ Name = 'demo' } -ExactlyOne
    foreach ($window in $captured.Windows) {
        '{0}: {1}' -f $window.Name, ($window.Panes.Id -join ', ')
    }
} catch {
    $failure = [InvalidOperationException]::new(
        "tmux quickstart failed: $($_.Exception.Message)", $_.Exception)
    throw $failure
}

$ErrorActionPreference = 'Stop'
Import-Module "$PSScriptRoot/modules/LibTmux/0.1.0/LibTmux.psd1"

$session = $null
$failure = $null
try {
    $socket = 'libtmux-home-' + [Guid]::NewGuid().ToString('N')
    $server = New-TmuxServer -SocketName $socket -ConfigurationFile /dev/null

    $session = $server | New-TmuxSession `
        -Name demo -WindowName editor -Command 'exec /bin/cat'
    $pane = $session | Get-TmuxPane
    $null = $pane | Split-TmuxPane -Horizontal -Command 'exec /bin/cat'
    $null = $session | New-TmuxWindow -Name logs -Command 'exec /bin/cat'

    $captured = ($server | Get-TmuxSnapshot).Sessions |
        Select-TmuxSession -Criteria @{ Name = 'demo' } -ExactlyOne
    foreach ($window in $captured.Windows) {
        '{0}: {1}' -f $window.Name, ($window.Panes.Id -join ', ')
    }
} catch {
    $failure = $_.Exception
    throw
} finally {
    if ($session) {
        $cleanupErrors = @()
        $session | Remove-TmuxSession -Confirm:$false `
            -ErrorAction SilentlyContinue -ErrorVariable cleanupErrors
        if ($cleanupErrors) {
            if ($failure) {
                $errors = @($failure) + $cleanupErrors.Exception
                throw [AggregateException]::new(
                    'tmux operation and cleanup failed.',
                    [Exception[]]$errors)
            }
            throw $cleanupErrors[0]
        }
    }
}

$ErrorActionPreference = 'Stop'
Import-Module "$PSScriptRoot/modules/LibTmux/0.1.0/LibTmux.psd1"

$session = $null
$failure = $null
try {
    $socket = 'libtmux-home-' + [Guid]::NewGuid().ToString('N')
    $server = New-TmuxServer -SocketName $socket -ConfigurationFile /dev/null

    $session = $server | New-TmuxSession `
        -Name demo -WindowName editor -Command 'exec /bin/cat'
    $pane = $session | Get-TmuxPane
    $null = $pane | Split-TmuxPane -Horizontal -Command 'exec /bin/cat'
    $null = $session | New-TmuxWindow -Name logs -Command 'exec /bin/cat'

    $captured = ($server | Get-TmuxSnapshot).Sessions |
        Select-TmuxSession -Criteria @{ Name = 'demo' } -ExactlyOne
    foreach ($window in $captured.Windows) {
        '{0}: {1}' -f $window.Name, ($window.Panes.Id -join ', ')
    }
} catch {
    $failure = [InvalidOperationException]::new(
        "tmux quickstart failed: $($_.Exception.Message)", $_.Exception)
    throw $failure
} finally {
    if ($session) {
        $cleanupErrors = @()
        $session | Remove-TmuxSession -Confirm:$false `
            -ErrorAction SilentlyContinue -ErrorVariable cleanupErrors
        if ($cleanupErrors) {
            if ($failure) {
                $errors = @($failure) + $cleanupErrors.Exception
                throw [AggregateException]::new(
                    'tmux operation and cleanup failed.',
                    [Exception[]]$errors)
            }
            throw $cleanupErrors[0]
        }
    }
}

Run this example

PowerShell 7.4.20 with PSResourceGet 1.1.1, POSIX shell and tmux on Linux.

Save the program above as quickstart.ps1 in a new directory, along with the files below.

Cleanup is omitted; the private tmux server and its temporary files may remain. Select Cleanup to remove them when the program finishes. The program stops its private tmux server and removes any temporary files it created when it finishes. Error handling adds diagnostics; every version checks required results and deadlines.

Setup and run

pwsh -NoLogo -NoProfile -Command '
  $ErrorActionPreference = "Stop"
  $null = New-Item -ItemType Directory -Path ./modules -Force
  Save-PSResource -Name LibTmux -Version 0.1.0 `
    -Path ./modules -TrustRepository
'

unset TMUX TMUX_PANE
export ENV=/dev/null BASH_ENV=/dev/null SHELL=/bin/sh
pwsh -NoLogo -NoProfile -File quickstart.ps1

Expected output

editor: %0, %1
logs: %2

Library revision: 2c30121b7733.

Typed API

Typed objects instead of parsed format strings: LibTmux\Get-TmuxPane
Filtering and queries over tmux objects: LibTmux\New-TmuxQuery

What you get over the tmux CLI

Connect to or start a tmux server: LibTmux\Connect-TmuxServer
Traversal from a server down to its panes: LibTmux\Get-TmuxSnapshot
Send keys to a pane: LibTmux\Send-TmuxKey
Watch for changes through tmux control mode: LibTmux\Watch-TmuxEvent
Capture pane contents: LibTmux\Get-TmuxPaneContent
Arguments passed as a list, with no shell quoting: LibTmux\Invoke-TmuxCommand

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

tmux client library for PowerShell

Guides

Topics

Examples

API reference

Install

At a glance

What it does

Start with PowerShell

Setup and run

Expected output

Typed API

What you get over the tmux CLI