# Capture, refresh and raw commands

Source: https://libtmux.org/en/powershell/latest/guides/capture/

> Capture, refresh and raw commands: LibTmux documentation.

[`Get-TmuxPaneContent`](<https://libtmux.org/en/powershell/latest/reference/libtmux-get-tmuxpanecontent/>) reads rendered text from a native [`LibTmux.Pane`](<https://libtmux.org/en/csharp/latest/reference/libtmux-pane/>).
[`Update-TmuxPane`](<https://libtmux.org/en/powershell/latest/reference/libtmux-update-tmuxpane/>) reads current pane metadata into a replacement handle.
Both accept a pane directly or through the pipeline and borrow its daemon.
[`Invoke-TmuxCommand`](<https://libtmux.org/en/powershell/latest/reference/libtmux-invoke-tmuxcommand/>) accepts a native [`LibTmux.Server`](<https://libtmux.org/en/csharp/latest/reference/libtmux-server/>) and literal tmux
arguments for operations that do not yet have a dedicated cmdlet.

Use the explicit endpoint and pane selection described in
[Read tmux objects](https://libtmux.org/en/powershell/latest/guides/read/). The examples below assume `$pane` and `$server`
refer to that selected pane and server. None chooses a global active server.

## Capture text

Return one string per captured screen line:

<!-- example: capture.lines -->
```powershell
$pane | Get-TmuxPaneContent
```

Capture the retained history as one string, joining wrapped screen lines:

<!-- example: capture.history -->
```powershell
$pane | Get-TmuxPaneContent -History -JoinWrappedLines -Raw
```

Capture an inclusive range, from ten lines before the visible screen through
its fifth line. Zero identifies the top visible line; negative values address
scrollback. Omitted bounds use tmux's normal visible-screen bounds.

<!-- example: capture.range -->
```powershell
$pane | Get-TmuxPaneContent -StartLine -10 -EndLine 4
```

`-History` selects the oldest retained history and cannot be combined with
`-StartLine`. It can be combined with `-EndLine`. `-Raw` emits exactly one
string per pane, joining the core's captured lines with LF and adding no
extra trailing newline. Internal empty lines remain empty lines. An empty
capture emits no objects normally and one empty string with `-Raw`.

This is rendered terminal text, not original process output or a byte-exact
stream. Sending input does not establish command completion: use a cooperative
wait channel or control event before asserting captured results.

| Switch | Effect |
| --- | --- |
| [`JoinWrappedLines`][-joinwrappedlines] | Join lines that wrapped on screen; tmux applies this in place of trailing-space handling. |
| [`EscapeSequences`][-escapesequences] | Include terminal escape sequences representing captured attributes. |
| [`EscapeNonPrintable`][-escapenonprintable] | Represent nonprintable bytes with octal escapes. |
| [`PreserveTrailingSpaces`][-preservetrailingspaces] | Retain trailing spaces. |
| [`TrimTrailingSpaces`][-trimtrailingspaces] | Request tmux's trailing-space trimming behavior. |
| [`AlternateScreen`][-alternatescreen] | Capture the alternate screen. |
| [`Quiet`][-quiet] | Return empty content when an alternate screen is absent; other failures remain errors. |
| [`ModeScreen`][-modescreen] | Capture a mode screen, such as copy mode. |
| [`Pending`][-pending] | Capture an incomplete pending escape sequence. |
| [`Hyperlinks`][-hyperlinks] | Include supported hyperlink capture metadata. |
| [`LineNumbers`][-linenumbers] | Include supported line-number metadata. |
| [`LineFlags`][-lineflags] | Include supported line-flag metadata. |

`-PreserveTrailingSpaces` and `-TrimTrailingSpaces` together terminate with
[`Tmux.InvalidCapture`][gettmuxpanecontentcommand] before dispatch.
Version-dependent switches retain the core's capability policy; availability
depends on the tmux version and the core connection's configuration.

## Refresh captured metadata

Retain the replacement returned by an explicit refresh:

<!-- example: capture.refresh -->
```powershell
$currentPane = $pane | Update-TmuxPane
```

The original `$pane` keeps its previously captured values. Refresh observes
tmux and returns another native [`LibTmux.Pane`](<https://libtmux.org/en/csharp/latest/reference/libtmux-pane/>); it does not mutate terminal
state or acquire ownership of the daemon. It uses the core's refresh and
identity rules. Repeated linked-window placement refresh remains subject to
the core's contextual-target limitations.

## Run literal tmux arguments

Pass each argument as a separate array element. The adapter does not join
arguments into a shell command or expand their contents.

<!-- example: capture.raw-list -->
```powershell
$server | Invoke-TmuxCommand -Arguments @(
    'list-sessions', '-F', '#{session_name}'
)
```

For tmux features without a dedicated cmdlet, use the same literal argument
boundary. This creates a named paste buffer, reads its text and removes only
that buffer:

<!-- example: capture.buffer -->
```powershell
& {
    $name = 'libtmux-' + [guid]::NewGuid().ToString('N')
    $quiet = @{ Confirm = $false; ErrorAction = 'Stop' }
    $created = $false
    try {
        $set = @('set-buffer', '-b', $name, 'hello from PowerShell')
        $null = $server | Invoke-TmuxCommand -Arguments $set @quiet
        $created = $true
        $show = @('show-buffer', '-b', $name)
        $shown = $server | Invoke-TmuxCommand -Arguments $show @quiet
        $shown.StandardOutputLines
    } finally {
        if ($created) {
            $delete = @('delete-buffer', '-b', $name)
            $server | Invoke-TmuxCommand -Arguments $delete @quiet | Out-Null
        }
    }
}
```

This returns `hello from PowerShell`. [`StandardOutput`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxcommandresult-standardoutput/>) retains bytes when
line projection is unsuitable. For copy mode, use raw `copy-mode` and
`send-keys -X` commands with an explicit pane ID.
`Get-TmuxPaneContent -ModeScreen` reads its rendered screen. Copy-mode
commands change the pane's mode, so leave it explicitly with
`send-keys -X cancel` when finished.

Empty non-command arguments are preserved. The first argument must name a
command or alias. An empty, whitespace or leading-option argument terminates
with [`Tmux.InvalidCommand`][invoketmuxcommandcommand] before confirmation or
dispatch. Select the socket on the server handle; global options such as `-S`,
`-L` and `-f` cannot replace the command name. Pipeline input must be a native
[`LibTmux.Server`](<https://libtmux.org/en/csharp/latest/reference/libtmux-server/>); an object with similarly named properties does not bind as an
endpoint.

Raw commands can mutate tmux or execute shell work. They always support
`-WhatIf` and `-Confirm`, including for commands the caller knows are reads.
Confirmation precedes discovery and dispatch. Preview shows the endpoint and
command name; argument contents are not included in the confirmation text.

<!-- example: capture.raw-preview -->
```powershell
$server | Invoke-TmuxCommand -Arguments @('kill-session', '-t', '$3') -WhatIf
```

Successful execution emits a native [`LibTmux.TmuxCommandResult`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxcommandresult/>) with exit code,
logical arguments, stdout/stderr bytes and projected lines. A nonzero exit emits
no success result and writes [`Tmux.CommandFailed`][invoketmuxcommandcommand].
Its original [`TmuxCommandException.Result`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxcommandexception-result/>) retains those diagnostics, and its
[`Dispatch`](<https://libtmux.org/en/csharp/latest/reference/libtmux-libtmuxexception-dispatch/>) is [`Dispatched`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxdispatchstate-dispatched/>). Transport failures preserve their original exception
and dispatch uncertainty. No mutation is automatically retried.

Capture and refresh failures use
[`Tmux.PaneCaptureFailed`][gettmuxpanecontentcommand] and
[`Tmux.PaneRefreshFailed`][updatetmuxpanecommand]. Each error retains the failed
owner, allowing later pipeline owners to continue unless `-ErrorAction Stop` is
selected. Cancellation uses the same core token and pipeline lifecycle as the
read cmdlets; it does not imply rollback or termination of shell work.

The [capture integration test](https://github.com/libtmux/libtmux-powershell/blob/b06c64f844f3173de66b187eaeaf3915814318c6/tests/Capture.Tests.ps1) exercises these
contracts against an owned daemon with explicit output readiness, literal
argument round trips, error results, refresh replacement and zero-dispatch
`-WhatIf`. It owns its sockets, child processes and temporary files.

[-joinwrappedlines]: https://libtmux.org/en/powershell/latest/reference/libtmux-get-tmuxpanecontent/#LibTmux%5CGet-TmuxPaneContent.parameter.JoinWrappedLines
[-escapesequences]: https://libtmux.org/en/powershell/latest/reference/libtmux-get-tmuxpanecontent/#LibTmux%5CGet-TmuxPaneContent.parameter.EscapeSequences
[-alternatescreen]: https://libtmux.org/en/powershell/latest/reference/libtmux-get-tmuxpanecontent/#LibTmux%5CGet-TmuxPaneContent.parameter.AlternateScreen
[-quiet]: https://libtmux.org/en/powershell/latest/reference/libtmux-get-tmuxpanecontent/#LibTmux%5CGet-TmuxPaneContent.parameter.Quiet
[gettmuxpanecontentcommand]: https://github.com/libtmux/libtmux-powershell/blob/b06c64f844f3173de66b187eaeaf3915814318c6/src/LibTmux.PowerShell/GetTmuxPaneContentCommand.cs
[invoketmuxcommandcommand]: https://github.com/libtmux/libtmux-powershell/blob/b06c64f844f3173de66b187eaeaf3915814318c6/src/LibTmux.PowerShell/InvokeTmuxCommandCommand.cs
[updatetmuxpanecommand]: https://github.com/libtmux/libtmux-powershell/blob/b06c64f844f3173de66b187eaeaf3915814318c6/src/LibTmux.PowerShell/UpdateTmuxPaneCommand.cs
[-escapenonprintable]: https://libtmux.org/en/powershell/latest/reference/libtmux-get-tmuxpanecontent/#LibTmux%5CGet-TmuxPaneContent.parameter.EscapeNonPrintable
[-preservetrailingspaces]: https://libtmux.org/en/powershell/latest/reference/libtmux-get-tmuxpanecontent/#LibTmux%5CGet-TmuxPaneContent.parameter.PreserveTrailingSpaces
[-trimtrailingspaces]: https://libtmux.org/en/powershell/latest/reference/libtmux-get-tmuxpanecontent/#LibTmux%5CGet-TmuxPaneContent.parameter.TrimTrailingSpaces
[-modescreen]: https://libtmux.org/en/powershell/latest/reference/libtmux-get-tmuxpanecontent/#LibTmux%5CGet-TmuxPaneContent.parameter.ModeScreen
[-pending]: https://libtmux.org/en/powershell/latest/reference/libtmux-get-tmuxpanecontent/#LibTmux%5CGet-TmuxPaneContent.parameter.Pending
[-hyperlinks]: https://libtmux.org/en/powershell/latest/reference/libtmux-get-tmuxpanecontent/#LibTmux%5CGet-TmuxPaneContent.parameter.Hyperlinks
[-linenumbers]: https://libtmux.org/en/powershell/latest/reference/libtmux-get-tmuxpanecontent/#LibTmux%5CGet-TmuxPaneContent.parameter.LineNumbers
[-lineflags]: https://libtmux.org/en/powershell/latest/reference/libtmux-get-tmuxpanecontent/#LibTmux%5CGet-TmuxPaneContent.parameter.LineFlags