`LibTmux.Workspace\Get-TmuxWorkspacePlan`

Get-TmuxWorkspacePlan [-Workspace] <LibTmux.Workspace.WorkspaceFile> -Server <LibTmux.Server> [-ExistingSession <LibTmux.Workspace.WorkspaceExistingSession>] [-ServerStartup <LibTmux.Workspace.WorkspaceServerStartup>] [-Readiness <LibTmux.Workspace.WorkspaceReadiness>] [-ReadinessTimeout <System.Double>] [-CompensateOnFailure] [-AllowHostScripts] [-HostScriptTimeout <System.Double>] [-MaxHostOutputBytes <System.Int32>] [-CleanupTimeout <System.Double>] [<CommonParameters>] cmdlet LibTmux.Workspace [source] ¶

Observe an explicit endpoint and prepare a workspace plan.

Description#

Validate the native declaration and policies, then inspect the supplied tmux endpoint. Return one native WorkspacePlan containing ordered actions, native requests and observed identity preconditions. Planning does not start a daemon, create panes, send commands or execute the declaration's host script.

Resolve file-relative paths explicitly before planning. Host scripts require a resolved document directory and AllowHostScripts when they will execute. The plan freezes the chosen policies, host limits and command arguments. Review its Actions and CompensationActions, then pass that same plan to Invoke-TmuxWorkspace. Changing a source file does not change an existing plan.

Error refuses a conflicting session. Reuse plans only reuse when that session exists, skipping declaration effects and host execution. Append creates declared windows while preserving local session settings and applying declared global defaults. Global options can affect other sessions that inherit them and are not restored by compensation. Replace selects the exact observed session for replacement. A stale plan fails at application; it is not automatically regenerated.

Observation spans tmux operations and is not a transaction. Native options, layouts, hooks and configuration can still cause application failures.

Notes

All numeric timeout parameters use seconds. Policy validation occurs before endpoint observation. Planning errors preserve the native exception with the Tmux.WorkspacePlanFailed identifier; invalid policy values use Tmux.InvalidWorkspacePolicy.

A JSON window layout needs tmux 3.8. On an earlier daemon planning fails with LibTmux.Workspace.WorkspaceFormatException, whose inner exception is the LibTmux.TmuxUnsupportedOnReleaseException refusal for layout-json, and nothing is created.

Command details#

Command type: cmdlet
Positional binding: Enabled.
Pipeline inputs: LibTmux.Workspace.WorkspaceFile: A parsed declaration, optionally resolved against an explicit document directory.
Outputs: LibTmux.Workspace.WorkspacePlan

Examples#

Example 1 Plan a workspace at an explicit socket without creating its session. View source

$endpoint = LibTmux\New-TmuxServer -SocketPath $SocketPath
LibTmux.Workspace\Import-TmuxWorkspace -Yaml @'
session_name: development
windows:
  - window_name: editor
'@ | LibTmux.Workspace\Get-TmuxWorkspacePlan -Server $endpoint

Parameters

-Workspace (LibTmux.Workspace.WorkspaceFile) #

The immutable parsed declaration. Resolve paths explicitly before planning when they depend on a document directory.

Required
Yes
Position
0
Pipeline input
By value
Validation
ValidateNotNull()
-Server (LibTmux.Server) #

The explicit endpoint to inspect. Planning borrows its lifetime and never initializes an absent daemon.

Required
Yes
Position
Named
Pipeline input
No
Validation
ValidateNotNull()
-ExistingSession (LibTmux.Workspace.WorkspaceExistingSession) #

Choose Error, Reuse, Append or Replace for a session with the same literal name. Replace is frozen into the plan; invocation uses normal PowerShell confirmation.

Required
No
Position
Named
Pipeline input
No
Default
Error
Validation
ValidateSet(["Error","Reuse","Append","Replace"])
-ServerStartup (LibTmux.Workspace.WorkspaceServerStartup) #

CreateOrJoin allows later application to start or join an initially absent daemon. RequireExisting fails planning when no daemon is present. Neither choice grants daemon ownership.

Required
No
Position
Named
Pipeline input
No
Default
CreateOrJoin
Validation
ValidateSet(["CreateOrJoin","RequireExisting"])
-Readiness (LibTmux.Workspace.WorkspaceReadiness) #

Immediate sends input without claiming shell readiness or command completion. Cooperative requires pane startup to signal the channel named by LIBTMUX_WORKSPACE_READY.

Required
No
Position
Named
Pipeline input
No
Default
Immediate
Validation
ValidateSet(["Immediate","Cooperative"])
-ReadinessTimeout (System.Double) #

Each cooperative signal budget in seconds. Accepts finite values from 0.0000001 through 86400.

Required
No
Position
Named
Pipeline input
No
Default
10
-CompensateOnFailure (System.Management.Automation.SwitchParameter) #

Attempt cleanup of journal-proven creations after failure. Shell input and host-script effects are irreversible. Owned readiness channels and replacement keepalives have mandatory cleanup regardless of this switch.

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

Allow a declared before_script to become a native RunHostScript action. Planning does not execute it. Reuse skips it when the existing session can be reused.

Required
No
Position
Named
Pipeline input
No
Switch
Yes
Default
False
-HostScriptTimeout (System.Double) #

The host script deadline, including output collection, in seconds. Accepts finite values from 0.0000001 through 86400.

Required
No
Position
Named
Pipeline input
No
Default
30
-MaxHostOutputBytes (System.Int32) #

The positive combined stdout and stderr capture limit in UTF-8 bytes. Additional output is drained and its dropped byte count remains visible in the native host result.

Required
No
Position
Named
Pipeline input
No
Default
1048576
-CleanupTimeout (System.Double) #

The total failure-cleanup budget in seconds. Accepts finite values from 0.0000001 through 86400. Incomplete or uncertain cleanup remains visible in the native journal.

Required
No
Position
Named
Pipeline input
No
Default
1

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.Workspace.WorkspacePlan: The native immutable plan with its endpoint and ordered actions.

Guides#

Pages that discuss Get-TmuxWorkspacePlan.

Guides: Compatibility
Getting started
Workspace: Workspace guide

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

`LibTmux.Workspace\Get-TmuxWorkspacePlan`

Description#

Command details#

Examples#

Guides#