# LibTmux\Watch-TmuxEvent - **Package:** LibTmux - **Language:** PowerShell - **Kind:** function - **Source:** https://github.com/libtmux/libtmux-powershell/blob/b06c64f844f3173de66b187eaeaf3915814318c6/src/LibTmux.PowerShell/WatchTmuxEventCommand.cs#L8 - **Page:** https://libtmux.org/en/powershell/latest/reference/libtmux-watch-tmuxevent/ ``` Connection (default): Watch-TmuxEvent [-Connection] [-MaxEventBytes ] [-MaxEvents ] [-MaxOutputBytes ] [-WhatIf] [-Confirm] [] Server: Watch-TmuxEvent [-Server] [-Target] [-MaxEventBytes ] [-MaxEvents ] [-MaxOutputBytes ] [-WhatIf] [-Confirm] [] ``` Stream native tmux events with bounded delivery and explicit ownership. Emit native [`TmuxEvent`](/en/csharp/latest/reference/libtmux-tmuxevent/) values in stream order. A supplied Connection is borrowed and remains usable after cancellation or early pipeline exit. With [`Server`](/en/csharp/latest/reference/libtmux-server/) and Target, the command owns a new control client and closes it before returning. Both forms borrow the daemon and its sessions. [`Output`](/en/csharp/latest/reference/libtmux-panerunresult-output/) count and byte budgets reset for each input connection or server; piping N owners can emit N times MaxEvents. There is one acknowledged handoff slot. The reader does not fetch the next event until downstream processing returns. PowerShell output runs only on the active pipeline callback; native command replies continue independently, so downstream code may send through the same connection. Only one [`Watch-TmuxEvent`](/en/powershell/latest/reference/libtmux-watch-tmuxevent/) consumer may read a connection at a time. Direct native [`Events`](/en/csharp/latest/reference/libtmux-icontrolmodesession-events/) readers remain the caller's responsibility: the stream is not broadcast. Event output is decoded text fragments, not rendered pane contents, lines, byte-exact output or a durable log. Loss and exit events are forwarded. ### Notes [`Tmux.WatchFailed`](https://github.com/libtmux/libtmux-powershell/blob/b06c64f844f3173de66b187eaeaf3915814318c6/docs/reference/LibTmux/Watch-TmuxEvent.md#notes) preserves the native exception and supplied owner. Buffered events precede a terminal stream error. A byte-budget failure preserves earlier output and reports that the consumed oversized event was not emitted. Byte accounting includes decoded UTF-8 text in pane IDs, output data, notification names and arguments, and exit reasons. [`Numeric`](/en/csharp/latest/reference/libtmux-commandpromptrequest-numeric/) loss counts add no text bytes. This bounds text payload, not object overhead or serialized PowerShell Job data. Set BOTH MaxEvents and MaxOutputBytes for unattended jobs. The native upstream queue separately defaults to 512 events and 4 MiB of decoded UTF-8 payload. Configure its positive [`ControlModeEventBufferCapacity`](/en/csharp/latest/reference/libtmux-serverconnectionoptions-controlmodeeventbuffercapacity/) and [`ControlModeEventBufferMaxBytes`](/en/csharp/latest/reference/libtmux-serverconnectionoptions-controlmodeeventbuffermaxbytes/) through [`ServerConnectionOptions`](/en/csharp/latest/reference/libtmux-serverconnectionoptions/) before connecting. Queue bytes include output data, notification names and arguments, and exit reasons, excluding pane IDs and object overhead. Oldest events are discarded until both queue limits hold. An oversized event is dropped; an oversized exit reason is omitted while the exit event remains. Loss is reported by [`TmuxEventsDroppedEvent`](/en/csharp/latest/reference/libtmux-tmuxeventsdroppedevent/) without blocking command replies. Ctrl+C, pipeline early exit and module removal stop the reader and await its disposal. Module removal cancels active watches only in the importing runspace; it does not dispose supplied clients. Cancellation may consume an event that has not reached the pipeline. Resnapshot after loss when current state matters. The foreground pipeline remains occupied while watching; use a bounded ThreadJob to make the prompt available. ## Command details - **Command type:** [`cmdlet`](/en/powershell/latest/reference/glossary/#cmdlet) - **Default parameter set:** Connection - **Confirmation:** Supports `-WhatIf` and `-Confirm`; confirm impact: Medium. - **Positional binding:** Enabled. - **Pipeline inputs:** `LibTmux.IControlModeSession`: A borrowed native control client.; `LibTmux.Server`: An endpoint on which to create an owned control client. - **Outputs:** `LibTmux.TmuxEvent` Related APIs: - [Watch events and use runspaces](https://github.com/libtmux/libtmux-powershell/blob/b06c64f844f3173de66b187eaeaf3915814318c6/docs/watch.md) - [Commands and control clients](https://github.com/libtmux/libtmux-powershell/blob/b06c64f844f3173de66b187eaeaf3915814318c6/docs/commands.md) ## Examples Example 1 Observe the first notification on fixture using a previously selected $server. The command closes its new control client when the count limit is reached. [Source example](https://github.com/libtmux/libtmux-powershell/blob/b06c64f844f3173de66b187eaeaf3915814318c6/docs/reference/LibTmux/Watch-TmuxEvent.md). ```powershell $server | LibTmux\Watch-TmuxEvent -Target 'fixture' -MaxEvents 1 -MaxOutputBytes 1MB ``` ## Parameters - `Connection` (`LibTmux.IControlModeSession`): The borrowed native client. No other consumer may read its Events stream while this watch is active. (for `Connection`) Required. Position 0. Accepts pipeline input by value. [`ValidateNotNull()`](https://learn.microsoft.com/dotnet/api/system.management.automation.validatenotnullattribute?view=powershellsdk-7.4.0). - `MaxEventBytes` (`System.Int32`): Positive maximum UTF-8 text bytes in the one-event handoff. Default: 1048576. An oversized event fails before output. Optional. Named parameter. Does not accept pipeline input. Documented default: `1048576`. [`ValidateRange(1, 2147483647)`](https://learn.microsoft.com/dotnet/api/system.management.automation.validaterangeattribute?view=powershellsdk-7.4.0). - `MaxEvents` (`System.Int64`): Positive maximum emitted event count. Default: Int64.MaxValue. Reaching the limit ends the watch normally. Optional. Named parameter. Does not accept pipeline input. Documented default: `9223372036854775807`. [`ValidateRange(1, 9223372036854776000)`](https://learn.microsoft.com/dotnet/api/system.management.automation.validaterangeattribute?view=powershellsdk-7.4.0). - `MaxOutputBytes` (`System.Int64`): Positive maximum cumulative emitted UTF-8 text bytes. Default: Int64.MaxValue. Reaching it exactly ends normally; an event too large for the remaining budget emits an error before that event. Optional. Named parameter. Does not accept pipeline input. Documented default: `9223372036854775807`. [`ValidateRange(1, 9223372036854776000)`](https://learn.microsoft.com/dotnet/api/system.management.automation.validaterangeattribute?view=powershellsdk-7.4.0). - `Verbose` (`System.Management.Automation.SwitchParameter`): Display verbose messages produced by this command. Optional. Named parameter. Switch parameter. Common parameter. Does not accept pipeline input. Aliases: `vb`. - `Debug` (`System.Management.Automation.SwitchParameter`): Display debug messages produced by this command. Optional. Named parameter. Switch parameter. Common parameter. Does not accept pipeline input. Aliases: `db`. - `ErrorAction` (`System.Management.Automation.ActionPreference`): Choose how this command responds to non-terminating errors. Optional. Named parameter. Common parameter. Does not accept pipeline input. Aliases: `ea`. - `WarningAction` (`System.Management.Automation.ActionPreference`): Choose how this command responds to warning messages. Optional. Named parameter. Common parameter. Does not accept pipeline input. Aliases: `wa`. - `InformationAction` (`System.Management.Automation.ActionPreference`): Choose how this command handles information messages. Optional. Named parameter. Common parameter. Does not accept pipeline input. Aliases: `infa`. - `ProgressAction` (`System.Management.Automation.ActionPreference`): Choose how this command handles progress updates. Optional. Named parameter. Common parameter. Does not accept pipeline input. Aliases: `proga`. - `ErrorVariable` (`System.String`): Store the command's error records in the named variable. Optional. Named parameter. Common parameter. Does not accept pipeline input. Aliases: `ev`. - `WarningVariable` (`System.String`): Store the command's warning records in the named variable. Optional. Named parameter. Common parameter. Does not accept pipeline input. Aliases: `wv`. - `InformationVariable` (`System.String`): Store the command's information records in the named variable. Optional. Named parameter. Common parameter. Does not accept pipeline input. Aliases: `iv`. - `OutVariable` (`System.String`): Save output in the named variable while passing it down the pipeline. Optional. Named parameter. Common parameter. Does not accept pipeline input. Aliases: `ov`. - `OutBuffer` (`System.Int32`): Buffer output before passing it to the next pipeline command. Optional. Named parameter. Common parameter. Does not accept pipeline input. Aliases: `ob`. - `PipelineVariable` (`System.String`): Make the most recent output object available through a named variable within the pipeline. Optional. Named parameter. Common parameter. Does not accept pipeline input. Aliases: `pv`. - `WhatIf` (`System.Management.Automation.SwitchParameter`): Show the operation without attaching a client or consuming events. Optional. Named parameter. Switch parameter. Does not accept pipeline input. Aliases: `wi`. - `Confirm` (`System.Management.Automation.SwitchParameter`): Ask before attaching or consuming the event stream. Optional. Named parameter. Switch parameter. Does not accept pipeline input. Aliases: `cf`. - `Server` (`LibTmux.Server`): The borrowed endpoint on which this command creates and owns one control client. (for `Server`) Required. Position 0. Accepts pipeline input by value. [`ValidateNotNull()`](https://learn.microsoft.com/dotnet/api/system.management.automation.validatenotnullattribute?view=powershellsdk-7.4.0). - `Target` (`System.String`): The explicit raw tmux target to attach to. It has no captured session identity guard. (for `Server`) Required. Position 1. Does not accept pipeline input. [`ValidateNotNullOrEmpty()`](https://learn.microsoft.com/dotnet/api/system.management.automation.validatenotnulloremptyattribute?view=powershellsdk-7.4.0). [`ValidatePattern("\\A[^\\x00]*[^\\s\\x00][^\\x00]*\\z")`](https://learn.microsoft.com/dotnet/api/system.management.automation.validatepatternattribute?view=powershellsdk-7.4.0). ## Returns `LibTmux.TmuxEvent`: Native output, notification, loss, pane-gone or exit events.