PowerShell API

cmdlet libtmux-powershell latest

LibTmux.New-TmuxSession

Create a detached session on an explicit server.

Source and package

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

New-TmuxSession [-Server] <LibTmux.Server> [-Name <System.String>] [-WindowName <System.String>] [-StartDirectory <System.String>] [-Command <System.String>] [-Width <System.Nullable[System.Int32]>] [-Height <System.Nullable[System.Int32]>] [-Environment <System.Collections.IDictionary>] [-WhatIf] [-Confirm] [<CommonParameters>] cmdlet LibTmux [source] ¶

Description#

Create a session and its initial window and pane, then return the captured native LibTmux.Session. The Server parameter accepts a native endpoint handle directly or through the pipeline. The core can start the daemon when that endpoint has no server. Existing session names remain errors; the command does not replace or attach to an existing session.

Notes

WhatIf reports the intended endpoint without discovery, daemon startup or dispatch, and returns no created object. Confirmation precedes the core operation. Success does not transfer ownership of the daemon to the module or arrange automatic cleanup. Cancellation can occur after a session was created; it is not rollback and the module does not retry. Per-owner errors use Tmux.SessionCreateFailed and retain the core exception and failed server. ErrorAction Continue allows later owners to run. A WindowName with a colon or a period on exactly tmux 3.7 reports LibTmux.TmuxUnsupportedOnReleaseException as its error before creating the session. A Name with either character is refused on every release with ArgumentException.

Command details#

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

Examples#

Example 1 Create a detached session on the server identified by the absolute $SocketPath. Choose an endpoint you control; the created session remains running until you remove it. View source

$options = @{
    Name = 'help-session'
    WindowName = 'work'
    Command = 'exec /bin/sh'
}
LibTmux\New-TmuxServer -SocketPath $SocketPath |
    LibTmux\New-TmuxSession @options

Parameters

-Server (LibTmux.Server) #

Native server endpoint in which to create the session. This is the only pipeline-bound parameter; binding by an object's Server property is not supported.

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

Session name. Omit it to let tmux choose. An existing name remains an error; tmux's name and format rules apply.

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

Name of the initial window. Omit it to retain tmux's default naming behavior.

Required
No
Position
Named
Pipeline input
No
Validation
ValidateNotNullOrEmpty()
-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()
-Width (System.Nullable[System.Int32]) #

Initial width in terminal cells, at least 1. Omit it to use tmux's default dimensions.

Required
No
Position
Named
Pipeline input
No
Validation
ValidateRange(1, 2147483647)
-Height (System.Nullable[System.Int32]) #

Initial height in terminal cells, at least 1. Omit it to use tmux's default dimensions.

Required
No
Position
Named
Pipeline input
No
Validation
ValidateRange(1, 2147483647)
-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()
-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.Session: Captured native object for the created resource.

tmux command#

The tmux commands behind New-TmuxSession.

new-session

tmux C API#

The C declarations in tmux that implement these commands.

cmd_new_session_entry cmd_new_session_exec

Each path starts at a function a command runs, which is degree 1. The degree counts steps from there along the path, and each step is a call or a reference: degree 2 is reached from that function, degree 3 from the next, and so on.

Create a session and its first pane

Guides#

Pages that discuss New-TmuxSession.

Examples: Create windows and panes
Guides: Compatibility
Create sessions, windows and panes
Getting started

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

LibTmux.New-TmuxSession

Description#

Command details#

Examples#

tmux command#

tmux C API#

Create a session and its first pane

Guides#