PowerShell API

cmdlet libtmux-powershell latest

LibTmux.Invoke-TmuxQuery

LibTmux\Invoke-TmuxQuery

Acquire fresh tmux objects using an explicit query.

Source and package

Declared in: LibTmux
Package: LibTmux
Source: src/LibTmux.PowerShell/InvokeTmuxQueryCommand.cs

NativeFilter: Invoke-TmuxQuery [-Server] <LibTmux.Server> -Target <LibTmux.Query.QueryTarget> -NativeFilter <System.String> [<CommonParameters>] Plan: Invoke-TmuxQuery [-Server] <LibTmux.Server> -Plan <System.Object> [-AsResult] [<CommonParameters>] Query (default): Invoke-TmuxQuery [-Server] <LibTmux.Server> -Query <LibTmux.Query.QueryDocument> [-Pushdown <LibTmux.Query.QueryPushdown>] [-AsResult] [<CommonParameters>] cmdlet LibTmux [source] ¶

Description#

Inspect the supplied endpoint, acquire a fresh snapshot and emit matching native objects in captured order. A query document is planned against the observed daemon version. A prepared plan must match that version. Execution never starts an absent daemon.

Use AsResult to retain one native QueryResult , including its complete snapshot when there are no matches. Filtering does not prune parent or child relations. Acquisition spans tmux commands and does not promise an atomic observation. Use Select-TmuxPane , Select-TmuxWindow or Select-TmuxSession for local filtering of objects already acquired.

NativeFilter is a separate raw tmux-format escape hatch. It returns matching rows without a complete structured-query snapshot. It cannot be combined with Query, Plan , Pushdown or AsResult.

Notes

Execution failures write Tmux.QueryExecutionFailed for the affected endpoint. Use ErrorAction Stop to terminate the pipeline. Cancellation stops the pending native operation. No matches are emitted from a failed acquisition.

Command details#

Command type: cmdlet
Default parameter set: Query
Positional binding: Enabled.
Pipeline inputs: LibTmux.Server : An explicit server endpoint.
Outputs: LibTmux.Session , LibTmux.Window , LibTmux.Pane , LibTmux.Query.QueryResult[LibTmux.Session], LibTmux.Query.QueryResult[LibTmux.Window], LibTmux.Query.QueryResult[LibTmux.Pane]

Examples#

Example 1 Acquire panes at least 80 columns wide from an explicit socket. View source

$query = LibTmux\New-TmuxQuery -Target Pane -Criteria @{ Width = @{ Ge = 80 } }
LibTmux\New-TmuxServer -SocketPath $SocketPath |
    LibTmux\Invoke-TmuxQuery -Query $query

Example 2 Keep the query result and its captured graph, including an empty selection. View source

$query = LibTmux\New-TmuxQuery -Target Pane -Criteria @{ Width = @{ Ge = 80 } }
LibTmux\New-TmuxServer -SocketPath $SocketPath |
    LibTmux\Invoke-TmuxQuery -Query $query -AsResult

Parameters

-Server (LibTmux.Server) #

The explicit endpoint to inspect and query.

Required
Yes
Position
0
Pipeline input
By value
Validation
ValidateNotNull()
-Target (LibTmux.Query.QueryTarget) (for NativeFilter) #

The native entity searched by NativeFilter .

Required
Yes
Position
Named
Pipeline input
No
Validation
ValidateSet(["Session","Window","Pane"])
-NativeFilter (System.String) (for NativeFilter) #

Uninterpreted tmux format text. The caller owns its semantics; it is not a structured portable query.

Required
Yes
Position
Named
Pipeline input
No
Validation
ValidateNotNullOrEmpty()
-Plan (System.Object) (for Plan) #

A native QueryPlan < Session >, QueryPlan < Window > or QueryPlan < Pane > prepared by Get-TmuxQueryPlan or the .NET API.

Required
Yes
Position
Named
Pipeline input
No
Validation
ValidateNotNull()
-AsResult (System.Management.Automation.SwitchParameter) (for Plan; Query) #

Emit one native result with matches and its complete captured graph.

Required
No
Position
Named
Pipeline input
No
Switch
Yes
Default
False
-Query (LibTmux.Query.QueryDocument) (for Query) #

A native document planned using the observed daemon version.

Required
Yes
Position
Named
Pipeline input
No
Validation
ValidateNotNull()
-Pushdown (LibTmux.Query.QueryPushdown) (for Query) #

Auto permits exact source evaluation and local residuals; Never evaluates locally; Require rejects residual predicates.

Required
No
Position
Named
Pipeline input
No
Default
Auto
Validation
ValidateSet(["Auto","Never","Require"])

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.Session : Matching sessions. LibTmux.Window : Matching window placements. LibTmux.Pane : Matching panes in their captured placement context. ` LibTmux.Query.QueryResult <T>`: One native result when AsResult is set.

Discussed in Local selection and source queries

Scripting & web

Compiled & native

JVM

.NET

tmux

LibTmux.Invoke-TmuxQuery

Description#

Command details#

Examples#