PowerShell API

cmdlet libtmux-powershell latest

LibTmux.Invoke-TmuxQuery

Acquire fresh tmux objects using an explicit query.

Source and package

Qualified name: LibTmux\Invoke-TmuxQuery
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.

Guides#

Pages that discuss Invoke-TmuxQuery.

Local selection and source queries

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

LibTmux.Invoke-TmuxQuery

Description#

Command details#

Examples#

Guides#