PowerShell API

cmdlet libtmux-powershell latest

LibTmux.New-TmuxWindow

Create a window in an explicit session.

Source and package

Qualified name: LibTmux\New-TmuxWindow
Declared in: LibTmux
Package: LibTmux
Source: src/LibTmux.PowerShell/NewTmuxWindowCommand.cs

New-TmuxWindow [-Session] <LibTmux.Session> [-Name <System.String>] [-Index <System.Nullable[System.Int32]>] [-StartDirectory <System.String>] [-Command <System.String>] [-Environment <System.Collections.IDictionary>] [-Activate] [-WhatIf] [-Confirm] [<CommonParameters>] cmdlet LibTmux [source] ¶

Description#

Create a window and its initial pane, then return the captured native LibTmux.Window. Supply a native Session directly or through the pipeline. The new window remains unselected unless Activate is present. The existing session object is not refreshed in place.

Notes

WhatIf performs no core discovery or dispatch and returns no created object. Confirmation precedes the core operation. The caller remains responsible for created resources. Cancellation does not prove that creation was rolled back; no mutation is retried. Per-owner errors use Tmux.WindowCreateFailed and retain the core exception and failed session. ErrorAction Continue allows later owners to run. A name with a colon or a period on exactly tmux 3.7 reports LibTmux.TmuxUnsupportedOnReleaseException as its error before creating the window.

Command details#

Command type: cmdlet
Confirmation: Supports -WhatIf and -Confirm; confirm impact: Medium.
Positional binding: Enabled.
Pipeline inputs: LibTmux.Session: Native pipeline type for this command.
Outputs: LibTmux.Window

Examples#

Example 1 Create a named window at an unused index in the first session on the server identified by $SocketPath. This example requires /bin/sh and leaves the new window running for later work. View source

LibTmux\New-TmuxServer -SocketPath $SocketPath |
    LibTmux\Get-TmuxSession | Select-Object -First 1 |
    LibTmux\New-TmuxWindow -Name 'help-window' -Index 5 -Command 'exec /bin/sh'

Parameters

-Session (LibTmux.Session) #

Native session that owns the new window. This is the only pipeline-bound parameter; binding by an object's Session property is not supported.

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

Window name. Omit it to retain tmux's default naming behavior. tmux's format expansion rules apply.

Required
No
Position
Named
Pipeline input
No
Validation
ValidateNotNullOrEmpty()
-Index (System.Nullable[System.Int32]) #

Unused session-relative window index, at least 0. Omit it to let tmux choose an available index. An occupied index remains an error.

Required
No
Position
Named
Pipeline input
No
Validation
ValidateRange(0, 2147483647)
-StartDirectory (System.String) #

Working directory for the new pane. Use an absolute filesystem path for predictable behavior. The core expands ~ and ~/; this cmdlet does not resolve PowerShell provider paths or change the host's current directory.

Required
No
Position
Named
Pipeline input
No
Validation
ValidateNotNullOrEmpty()
-Command (System.String) #

One shell-command string for the new pane. tmux interprets shell syntax in this string; it is not an argument array. Omit it to use the configured default command or shell.

Required
No
Position
Named
Pipeline input
No
Validation
ValidateNotNullOrEmpty()
-Environment (System.Collections.IDictionary) #

A dictionary with string names and string values. Names must be nonempty and contain neither '=' nor NUL (U+0000). Values may be empty but must not contain NUL. Null or non-string entries are rejected before confirmation or dispatch. Entries are copied for this invocation and do not change the PowerShell host environment.

Required
No
Position
Named
Pipeline input
No
Validation
ValidateNotNull()
-Activate (System.Management.Automation.SwitchParameter) #

Select the new window in its session. By default the current selection is preserved. This switch does not attach the PowerShell process to a tmux terminal.

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

Runs the command in a mode that only reports what would happen without performing the actions.

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

Prompts you for confirmation before running the cmdlet.

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.Window: Captured native object for the created resource.

tmux command#

The tmux commands behind New-TmuxWindow.

new-window

tmux C API#

The C declarations in tmux that implement these commands.

cmd_new_window_entry cmd_new_window_exec

Guides#

Pages that discuss New-TmuxWindow.

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

LibTmux.New-TmuxWindow

Description#

Command details#

Examples#

tmux command#

tmux C API#

Guides#