PowerShell API

cmdlet libtmux-powershell latest

LibTmux.Wait-TmuxPaneText

Wait for rendered text in a native tmux pane.

Source and package

Qualified name: LibTmux\Wait-TmuxPaneText
Declared in: LibTmux
Package: LibTmux
Source: src/LibTmux.PowerShell/WaitTmuxPaneTextCommand.cs

Wait-TmuxPaneText [-Pane] <LibTmux.Pane> [[-Pattern] <System.String[]>] [-StopPattern <System.String[]>] [-CaseSensitive] [-SimpleMatch] [-Timeout <System.Double>] [-AllowPollingFallback] [-TailLines <System.Int32>] [-MaxOutputBytes <System.Int32>] [-WhatIf] [-Confirm] [<CommonParameters>] cmdlet LibTmux [source] ¶

Description#

Watch the selected pane until one pattern matches rendered text. A match already visible when observation begins returns PresentAtEntry. With no pattern, the command waits for any new rendered output and returns AnyOutput. Stop patterns return Stopped; the deadline and a pane exit return TimedOut and PaneExited. These are native LibTmux.PaneWaitResult outcomes, not cmdlet errors. Inspect Outcome before treating a wait as readiness.

On tmux 3.7 and newer, the observer attaches a temporary control client before its first capture. Control events wake a grid-aware reader; matching uses captured rendered rows, not individual output fragments. Results include a bounded final screen tail, elapsed and effective timeout, dropped-event count, polling fallback, and missed-line or lost-anchor indicators. The default view shows Missed and omits the tail; inspect Tail explicitly if you need its text. A lost event or anchor means the observer may have missed transient output.

On tmux 3.7 and newer, control observation is required by default and -AllowPollingFallback permits bounded polling if it fails. Older releases attach no control client, so the wait always polls. On either path a pattern matches a line that wraps across rows as one line. A wait whose server is killed ends as PaneExited with the output read so far in Tail, without an error, as it does when the pane exits. The result discloses whether polling ran. The wait borrows the pane and server; it disposes only its own observer and client on completion or Ctrl+C. -WhatIf attaches no client and captures no text. Confirmation identifies the endpoint and pane without displaying patterns or pane content.

This command recognizes text; it does not authenticate command completion or an exit status. Use Invoke-TmuxPaneCommand for a shell command you start or Wait-TmuxChannel for a cooperative application signal. Visible text can include input echoed by a shell or application. Get-TmuxPaneContent -History reads retained rendered scrollback, while -Raw joins rendered rows; neither is a byte-exact process stream.

Notes

Tmux.PaneTextWaitFailed retains the native pane as its error target for transport and capture failures. Tmux.InvalidTimeout and Tmux.InvalidPaneTextRequest fail before attaching a client. -ErrorAction Continue can advance to the next pane after an operation error; -ErrorAction Stop stops the pipeline.

Command details#

Command type: cmdlet
Confirmation: Supports -WhatIf and -Confirm; confirm impact: Medium.
Positional binding: Enabled.
Pipeline inputs: LibTmux.Pane: The pane selected from an explicit endpoint.
Outputs: LibTmux.PaneWaitResult

Examples#

Example 1 Given a native $pane running a program that reads one line, prints READY, then stays alive, send a trigger that cannot match the ready pattern. Output may arrive before the wait begins; both PresentAtEntry and Matched mean the line was observed: View source

& {
    $pane | LibTmux\Send-TmuxText -Text go -Enter -Confirm:$false
    $pane |
        LibTmux\Wait-TmuxPaneText -Pattern '^READY$' -Timeout 5 -Confirm:$false
}

Parameters

-Pane (LibTmux.Pane) #

The native pane to observe. An arbitrary object with an Id property is not a pane owner.

Required
Yes
Position
0
Pipeline input
By value
Validation
ValidateNotNull()
-Pattern (System.String[]) #

Regular expressions to wait for. Omit or pass an empty array to wait for any new rendered output. Empty entries are rejected. The shared observer bounds regex matching work and time over rendered rows. It uses .NET's nonbacktracking regex mode; unsupported constructs such as lookarounds and backreferences are rejected before attaching a client.

Required
No
Position
1
Pipeline input
No
-StopPattern (System.String[]) #

Regular expressions that end the wait with Outcome = Stopped. Stop patterns take precedence over wanted patterns, including text visible at entry. Across both pattern lists, at most 32 entries, 999 UTF-8 bytes per entry and 16384 bytes in total are accepted.

Required
No
Position
Named
Pipeline input
No
-CaseSensitive (System.Management.Automation.SwitchParameter) #

Match letter case. Patterns are case-insensitive by default.

Required
No
Position
Named
Pipeline input
No
Switch
Yes
-SimpleMatch (System.Management.Automation.SwitchParameter) #

Treat each pattern and stop pattern as literal text instead of a regular expression. -CaseSensitive still controls case matching.

Required
No
Position
Named
Pipeline input
No
Switch
Yes
-Timeout (System.Double) #

Wait budget in seconds. Fractions are accepted. The default is 10; the valid range is 0.0000001 through 86400. A timed-out wait does not prove the program stopped or the desired text was never printed.

Required
No
Position
Named
Pipeline input
No
Default
10
-AllowPollingFallback (System.Management.Automation.SwitchParameter) #

Allow bounded capture polling if the control client cannot observe the pane on tmux 3.7 and newer; older releases always poll. The default is to report the control failure. PollingFallback discloses use.

Required
No
Position
Named
Pipeline input
No
Switch
Yes
-TailLines (System.Int32) #

Maximum rendered screen lines retained in the result tail. The default is 20; the valid range is 1 through 1000. Truncation is reported separately.

Required
No
Position
Named
Pipeline input
No
Default
20
Validation
ValidateRange(1, 1000)
-MaxOutputBytes (System.Int32) #

Maximum UTF-8 bytes retained in the result tail. The default is 65536; the valid range is 1 through 1048576. This bounds returned text, not the producer.

Required
No
Position
Named
Pipeline input
No
Default
65536
Validation
ValidateRange(1, 1048576)
-WhatIf (System.Management.Automation.SwitchParameter) #

Describe the intended observer without attaching a client or capturing text.

Required
No
Position
Named
Pipeline input
No
Switch
Yes
Aliases
wi
-Confirm (System.Management.Automation.SwitchParameter) #

Prompt before attaching an observer. The prompt omits pattern and pane text.

Required
No
Position
Named
Pipeline input
No
Switch
Yes
Aliases
cf

Common parameters 12

PowerShell supplies these parameters. See common parameter behavior for their effects.

-Verbose (System.Management.Automation.SwitchParameter) #

Display verbose messages produced by this command.

Aliases: vb Microsoft Learn reference
-Debug (System.Management.Automation.SwitchParameter) #

Display debug messages produced by this command.

Aliases: db Microsoft Learn reference
-ErrorAction (System.Management.Automation.ActionPreference) #

Choose how this command responds to non-terminating errors.

Aliases: ea Microsoft Learn reference
-WarningAction (System.Management.Automation.ActionPreference) #

Choose how this command responds to warning messages.

Aliases: wa Microsoft Learn reference
-InformationAction (System.Management.Automation.ActionPreference) #

Choose how this command handles information messages.

Aliases: infa Microsoft Learn reference
-ProgressAction (System.Management.Automation.ActionPreference) #

Choose how this command handles progress updates.

Aliases: proga Microsoft Learn reference
-ErrorVariable (System.String) #

Store the command's error records in the named variable.

Aliases: ev Microsoft Learn reference
-WarningVariable (System.String) #

Store the command's warning records in the named variable.

Aliases: wv Microsoft Learn reference
-InformationVariable (System.String) #

Store the command's information records in the named variable.

Aliases: iv Microsoft Learn reference
-OutVariable (System.String) #

Save output in the named variable while passing it down the pipeline.

Aliases: ov Microsoft Learn reference
-OutBuffer (System.Int32) #

Buffer output before passing it to the next pipeline command.

Aliases: ob Microsoft Learn reference
-PipelineVariable (System.String) #

Make the most recent output object available through a named variable within the pipeline.

Aliases: pv Microsoft Learn reference

Returns

LibTmux.PaneWaitResult: One result per pane with outcome, matched pattern, bounded rendered tail and observation metadata. No result is emitted for -WhatIf or an empty pipeline.

Guides#

Pages that discuss Wait-TmuxPaneText.

Examples: Wait for a service
Guides: Compatibility
Getting started
Topics: Dispatch, completion, and failure
Watching output and state

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

LibTmux.Wait-TmuxPaneText

Description#

Command details#

Examples#

Guides#