libtmux
PowerShell

Choose a port 15

Scripting & web

PythonNo matching page
RubyNo matching page
LuaNo matching page
JuliaNo matching page
TypeScriptNo matching page

Compiled & native

RustNo matching page
GoNo matching page
C++No matching page
SwiftNo matching page

JVM

JavaNo matching page
KotlinNo matching page
ScalaNo matching page

.NET

C#No matching page
F#No matching page
PowerShell

tmux

tmux CLI

Search
Colour scheme
Menu
Reference MCP
Workspace ManagerAPI Reference

Choose documentation 2

PowerShell · latest · en
latest

Current version

latest
English

Prerelease This site documents an alpha of libtmux. Its structure, URLs and APIs are subject to change.

LibTmux.Workspace

Anonymous module
moduleLibTmux.Workspace [source]

Workspace declarations and automation over LibTmux . Alpha.

Discussed in Workspace Manager , LibTmux.Workspace API reference · Workspace guide

Members

ConvertTo-TmuxWorkspace [-Session] <LibTmux.Session> [<CommonParameters>]
cmdletLibTmux.Workspace [source]

Convert a captured session to a native workspace declaration.

Description#

Return one native WorkspaceFile for each captured Session received from the pipeline. The shared library preserves captured window placements and pane order, names, layouts, active window and pane flags, and pane directories. Repeated links to the same window become separate declared windows.

Capture with Get-TmuxSnapshot -Depth Panes before selecting a Session . Conversion never contacts tmux or fills unavailable relations. The captured graph remains convertible after its daemon exits. A missing field or relation is an error; a captured null pane directory remains unspecified rather than using the host's current directory.

Captured directories become unresolved declaration values with literal dollars escaped as $$. DocumentDirectory remains null. Use Resolve-TmuxWorkspace with an explicit BaseDirectory before planning, or convert the declaration to YAML or JSON and resolve it after importing. Do not interpret those escaped values as already resolved filesystem paths.

Conversion preserves session-relative window indices. It emits a warning for each successful input because it omits observed environment, options, terminal text, entity IDs, pane indices and shared-link identity. It cannot reconstruct original commands, arguments or shell intent. Foreground command names do not establish the shell command that started a pane. Original relative paths, expansion variables, comments, host scripts and pre-commands are not reconstructed. Native custom layouts can change which pane occupies a position when applied. This declaration is a starting configuration, not a checkpoint of running programs.

Notes

Tmux.WorkspaceFreezeFailed retains the original native exception and input Session as its target. IncompleteSnapshotException uses the InvalidData error category. ErrorAction Continue permits later sessions to be converted without emitting a declaration for a failed input; ErrorAction Stop terminates. The loss warning uses PowerShell's warning stream and supports WarningAction . The command performs no acquisition, execution or file write and has no WhatIf or Confirm parameters.

Command details#

Command type
cmdlet
Positional binding
Enabled.
Pipeline inputs
LibTmux.Session : A native captured session; serialized copies are not live native objects.
Outputs
LibTmux.Workspace.WorkspaceFile
Related APIs

Examples#

Example 1 Convert a native Session selected from a pane-depth snapshot. This operation uses only the supplied capture and does not own resources requiring cleanup. View source

Terminal window
$capturedSession | LibTmux.Workspace\ConvertTo-TmuxWorkspace
Parameters

  • -Session (LibTmux.Session) #

    The native session whose window, pane and active-pane relations and required fields have already been captured. Binding by an arbitrary object's Session property is not supported.

    Required
    Yes
    Position
    0
    Pipeline input
    By value
    Validation
    ValidateNotNull()
Common parameters 12

PowerShell supplies these parameters. See common parameter behavior for their effects.

Returns

LibTmux.Workspace.WorkspaceFile: One unresolved declaration per successfully converted input session.

ConvertTo-TmuxWorkspaceJson [-Workspace] <LibTmux.Workspace.WorkspaceFile> [<CommonParameters>]
cmdletLibTmux.Workspace [source]

Convert a native workspace declaration to JSON text.

Description#

Return one string for each native WorkspaceFile received from the pipeline. The text uses the snake_case keys accepted by Import-TmuxWorkspace and the native parser. Conversion preserves pane and command order, empty strings, nullable fields, global and local options, post-construction options, environment and commands at every declaration level. It does not expand command text or inherit local defaults into children.

Resolved directories and option values contain literal text. Conversion escapes their dollar signs as $$ so export, import and a later explicit Resolve-TmuxWorkspace keep the same values. Unresolved variable expressions remain unchanged. DocumentDirectory is resolution provenance and is omitted from the text; provide an explicit base when resolving the imported declaration.

The native parser checks emitted text, including its character limit. This is not application validation: incomplete declarations can still be converted. No tmux observation, command execution, file writing or plan serialization occurs. Formatting and comments from an imported source document are not part of the native declaration and are not reproduced.

Notes

Serialization errors terminate with Tmux.WorkspaceJsonFailed and retain the original exception. Null host commands are omitted because the native parser rejects an explicit null before_script. Nullable name and directory values remain distinct from empty strings. The native model does not retain a distinction between omitted and empty collections or omitted and false focus.

Command details#

Command type
cmdlet
Positional binding
Enabled.
Pipeline inputs
LibTmux.Workspace.WorkspaceFile: A parsed or explicitly resolved declaration.
Outputs
System.String
Related APIs

Examples#

Example 1 Convert a two-pane declaration for storage or inspection. View source

Terminal window
LibTmux.Workspace\Import-TmuxWorkspace -Yaml @'
session_name: development
windows:
  - window_name: work
    panes: [nvim, ""]
'@ | LibTmux.Workspace\ConvertTo-TmuxWorkspaceJson
Parameters

  • -Workspace (LibTmux.Workspace.WorkspaceFile) #

    The native declaration to serialize without applying it.

    Required
    Yes
    Position
    0
    Pipeline input
    By value
    Validation
    ValidateNotNull()
Common parameters 12

PowerShell supplies these parameters. See common parameter behavior for their effects.

Returns

System.String : One JSON document per input declaration.

Discussed in Workspace guide

ConvertTo-TmuxWorkspaceYaml [-Workspace] <LibTmux.Workspace.WorkspaceFile> [<CommonParameters>]
cmdletLibTmux.Workspace [source]

Convert a native workspace declaration to YAML text.

Description#

Return one string for each native WorkspaceFile received from the pipeline. The text uses the snake_case keys accepted by Import-TmuxWorkspace and the native parser. Conversion preserves pane and command order, empty strings, nullable fields, global and local options, post-construction options, environment and commands at every declaration level. It does not expand command text or inherit local defaults into children.

Resolved directories and option values contain literal text. Conversion escapes their dollar signs as $$ so export, import and a later explicit Resolve-TmuxWorkspace keep the same values. Unresolved variable expressions remain unchanged. DocumentDirectory is resolution provenance and is omitted from the text; provide an explicit base when resolving the imported declaration.

The native parser checks emitted text, including its character limit. This is not application validation: incomplete declarations can still be converted. No tmux observation, command execution, file writing or plan serialization occurs. Formatting and comments from an imported source document are not part of the native declaration and are not reproduced.

Notes

Serialization errors terminate with Tmux.WorkspaceYamlFailed and retain the original exception. Null host commands are omitted because the native parser rejects an explicit null before_script. Nullable name and directory values remain distinct from empty strings. The native model does not retain a distinction between omitted and empty collections or omitted and false focus.

Command details#

Command type
cmdlet
Positional binding
Enabled.
Pipeline inputs
LibTmux.Workspace.WorkspaceFile: A parsed or explicitly resolved declaration.
Outputs
System.String
Related APIs

Examples#

Example 1 Convert a two-pane declaration for storage or inspection. View source

Terminal window
LibTmux.Workspace\Import-TmuxWorkspace -Yaml @'
session_name: development
windows:
  - window_name: work
    panes: [nvim, ""]
'@ | LibTmux.Workspace\ConvertTo-TmuxWorkspaceYaml
Parameters

  • -Workspace (LibTmux.Workspace.WorkspaceFile) #

    The native declaration to serialize without applying it.

    Required
    Yes
    Position
    0
    Pipeline input
    By value
    Validation
    ValidateNotNull()
Common parameters 12

PowerShell supplies these parameters. See common parameter behavior for their effects.

Returns

System.String : One YAML document per input declaration.

Directory: Get-TmuxWorkspace -Directory <System.String> [<CommonParameters>] Discover (default): Get-TmuxWorkspace [-ConfigurationDirectory <System.String>] [-AllLocations] [<CommonParameters>] LiteralPath: Get-TmuxWorkspace -LiteralPath <System.String> [<CommonParameters>] Name: Get-TmuxWorkspace [-Name] <System.String> [-ConfigurationDirectory <System.String>] [-AllLocations] [<CommonParameters>] Search: Get-TmuxWorkspace [-ConfigurationDirectory <System.String>] [-AllLocations] -Search <System.String> [-SearchIn <System.String[]>] [-CaseSensitive] [<CommonParameters>]
cmdletLibTmux.Workspace [source]

Find workspace declaration files without loading sessions.

Description#

Return native FileInfo objects for readable, seekable declaration files. Discovery does not contact tmux, run scripts, resolve declaration variables or create configuration directories. Pipe a selected file to Import-TmuxWorkspace for parsing, or Resolve-TmuxWorkspace for explicit file-relative resolution.

With no arguments, list .tmuxp.yaml, .tmuxp.yml and .tmuxp.json in the current filesystem directory, then each ancestor through HOME when it is an ancestor, otherwise through the filesystem root. Each directory uses that extension order. Append files from the first existing global configuration directory: ConfigurationDirectory, TMUXP_CONFIGDIR, XDG_CONFIG_HOME/tmuxp (or HOME/.config/tmuxp), then HOME/.tmuxp. HOME falls back to the platform user profile directory when unset. Missing default locations are skipped; an explicit missing ConfigurationDirectory is an error. AllLocations includes all existing global candidates in that order, preserving shadowed files. Global filenames sort ordinally within each location. Repeated full paths are emitted once.

Directory checks only the three local .tmuxp filenames in that exact directory. LiteralPath selects one exact filesystem file and bypasses discovery; it has no extension restriction. File symlinks retain their literal paths when the shared opener accepts the target. Directory entries are not files and are never recursively descended, including directory symlinks.

Name searches only the selected global locations. It is a literal basename, with an optional .yaml, .yml or .json suffix. Without a supported suffix, those three suffixes are tried in order. Multiple matches in one location are an ambiguity error naming the candidates; use LiteralPath to choose. A missing name emits no objects. Path separators are rejected; wildcard characters are literal. Filename suffixes are lowercase and literal; path/name identity follows the filesystem, independently of search case behavior.

Search uses literal ordinal-ignore-case substring matching on filenames by default. CaseSensitive selects ordinal matching. SearchIn selects FileName, Path, Session , Window , Command or Directory fields. Path searches the full selected path without reading file content. Any content field parses every candidate with the shared strict UTF-8 reader, accepting a UTF-8 BOM and at most 1048576 characters. Command includes before_script and all pane commands and shell_command_before entries; none are executed. Directory searches declared strings without expansion. Multiple fields combine by OR. Malformed candidate data fails content search even if its filename matches.

Traversal stops with an error after 1024 examined entries: existing local marker probes and global directory entries count, including unselected suffixes and directories. Ancestor traversal also has a 1024-directory ceiling. Narrow the request with Directory, Name or LiteralPath. Results are published only after successful discovery/search, so failures do not emit truncated lists. Filesystem contents can change between discovery and later import; FileInfo output is not a locked or atomic filesystem snapshot.

Notes

Failures write Tmux.WorkspaceDiscoveryFailed with the request as TargetObject. File read/parse errors retain the original exception and identify the failing path in Exception.Data['WorkspacePath']. Use ErrorAction Stop to terminate. Cancellation is checked between traversal, read and search operations and before publication. Stopping discovery does not delete files or stop a daemon.

Command details#

Command type
cmdlet
Default parameter set
Discover
Positional binding
Enabled.
Pipeline inputs
None: No pipeline input.
Outputs
System.IO.FileInfo
Related APIs

Examples#

Example 1 Select the existing declaration named by $WorkspacePath , retaining a native FileInfo that can feed Import-TmuxWorkspace or Resolve-TmuxWorkspace . View source

Terminal window
LibTmux.Workspace\Get-TmuxWorkspace -LiteralPath $WorkspacePath
Parameters
Common parameters 12

PowerShell supplies these parameters. See common parameter behavior for their effects.

Returns

System.IO.FileInfo : Declaration files in documented precedence order.

Discussed in Workspace guide

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>]
cmdletLibTmux.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 .

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
Related APIs

Examples#

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

Terminal window
$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.

Returns

LibTmux.Workspace.WorkspacePlan: The native immutable plan with its endpoint and ordered actions.

Discussed in Workspace guide

File: Import-TmuxWorkspace -File <System.IO.FileInfo> [<CommonParameters>] Path (default): Import-TmuxWorkspace [-LiteralPath] <System.String> [<CommonParameters>] Yaml: Import-TmuxWorkspace -Yaml <System.String> [<CommonParameters>]
cmdletLibTmux.Workspace [source]

Parse a workspace declaration without executing it.

Description#

Read a literal filesystem path, a FileInfo pipeline or supplied YAML/JSON text into a native WorkspaceFile. Inputs must be seekable UTF-8 files; a UTF-8 BOM is accepted. Named pipes are rejected without waiting for a writer. Admission stops at 1048576 characters, before retaining an oversized document. Malformed YAML/JSON and invalid UTF-8 preserve their exceptions as InvalidData errors.

Parsing does not start tmux, execute host scripts or expand paths and variables. Resolve-TmuxWorkspace supplies an explicit document base and allowed variables. Test-TmuxWorkspace checks declaration completeness and execution policy.

A window can set window_index to a nonnegative session-relative index. Omit it for tmux's next free index. Duplicate requested indexes fail validation; an index already occupied in the session fails during application.

Notes

File errors retain Tmux.InvalidWorkspace and allow later pipeline files with ErrorAction Continue. ErrorAction Stop terminates. No form applies a workspace.

Command details#

Command type
cmdlet
Default parameter set
Path
Positional binding
Enabled.
Pipeline inputs
System.IO.FileInfo : A file to read and parse.
Outputs
LibTmux.Workspace.WorkspaceFile
Related APIs

Examples#

Example 1 Inspect a declaration with a window at index 5 without starting tmux. View source

Terminal window
LibTmux.Workspace\Import-TmuxWorkspace -Yaml @'
session_name: development
windows:
  - window_name: editor
    window_index: 5
    panes: [null]
'@
Parameters
Common parameters 12

PowerShell supplies these parameters. See common parameter behavior for their effects.

Returns

LibTmux.Workspace.WorkspaceFile: Native pipeline type for this command.

Invoke-TmuxWorkspace [-Plan] <LibTmux.Workspace.WorkspacePlan> [-WhatIf] [-Confirm] [<CommonParameters>]
cmdletLibTmux.Workspace [source]

Apply the exact workspace plan after one confirmation.

Description#

Apply the supplied native WorkspacePlan using its own endpoint, observed identities and frozen actions. No declaration, file, endpoint or policy can be substituted at invocation. Stale preconditions fail; invocation never replans or retries mutations automatically.

One PowerShell ShouldProcess decision covers the whole plan. Its target names the executable, socket and literal session name. Its action describes conflict, startup, readiness and compensation policy, global option effects, then lists every action and conditional cleanup step in order by kind and symbolic target. Option actions disclose scope and whether they change global defaults; request values are omitted. Inspect the original plan for full request and host-command values. WhatIf and declined confirmation perform no application I/O or cleanup and emit no WorkspaceResult.

Successful invocation returns one native WorkspaceResult containing the session, created windows, unsupported layouts and action journals. WorkspaceBuildException remains ErrorRecord.Exception under Tmux.WorkspaceApplyFailed, with the original plan as TargetObject. Inspect its Dispatch , InnerException, PartialResult, Journal and CompensationJournal; partial results are never emitted as success.

Stopping the pipeline cancels owned work. Cleanup follows the plan's frozen budget. A stopped pipeline can suppress subsequent error output, so receiving a cancellation journal after pipeline shutdown is not guaranteed. Application is detached; it does not attach a terminal or transfer ownership of the daemon. To enter the applied session, pass the successful WorkspaceResult.Session to Enter-TmuxSession in a foreground terminal outside tmux. Attachment has its own confirmation and cancellation behavior; it does not repeat application.

Notes

Replace is an explicit planning policy. Compensation can remove only creations whose ownership is established by the native journal; shell and host-script effects cannot be undone. Reuse returns the existing session without running workspace mutation or host actions.

Command details#

Command type
cmdlet
Confirmation
Supports -WhatIf and -Confirm ; confirm impact: High.
Positional binding
Enabled.
Pipeline inputs
LibTmux.Workspace.WorkspacePlan: A native plan prepared by Get-TmuxWorkspacePlan or the shared .NET API.
Outputs
LibTmux.Workspace.WorkspaceResult
Related APIs

Examples#

Example 1 Preview an existing plan created by Get-TmuxWorkspacePlan without applying it. View source

Terminal window
$Plan | LibTmux.Workspace\Invoke-TmuxWorkspace -WhatIf

Example 2 Apply that reviewed plan with the normal confirmation explicitly disabled. View source

Terminal window
$Plan | LibTmux.Workspace\Invoke-TmuxWorkspace -Confirm:$false
Parameters

  • -Plan (LibTmux.Workspace.WorkspacePlan) #

    The exact native plan to apply. Its endpoint, actions, creation identity checks and cleanup policies are preserved.

    Required
    Yes
    Position
    0
    Pipeline input
    By value
    Validation
    ValidateNotNull()

  • -WhatIf (System.Management.Automation.SwitchParameter) #

    Describe the whole plan without tmux inspection, host execution, mutation or cleanup. No success object is returned.

    Required
    No
    Position
    Named
    Pipeline input
    No
    Switch
    Yes
    Aliases
    wi
    Default
    False

  • -Confirm (System.Management.Automation.SwitchParameter) #

    Request normal PowerShell confirmation for the whole reviewed plan. The command has High confirmation impact.

    Required
    No
    Position
    Named
    Pipeline input
    No
    Switch
    Yes
    Aliases
    cf
    Default
    False
Common parameters 12

PowerShell supplies these parameters. See common parameter behavior for their effects.

Returns

LibTmux.Workspace.WorkspaceResult: One completed native result. Preview and declined confirmation emit nothing.

Discussed in Workspace guide

In other ports Build a session from a workspace description
File: Resolve-TmuxWorkspace -File <System.IO.FileInfo> [-Variables <System.Collections.IDictionary>] [<CommonParameters>] Path: Resolve-TmuxWorkspace -LiteralPath <System.String> [-Variables <System.Collections.IDictionary>] [<CommonParameters>] Workspace (default): Resolve-TmuxWorkspace [-Workspace] <LibTmux.Workspace.WorkspaceFile> -BaseDirectory <System.String> [-Variables <System.Collections.IDictionary>] [<CommonParameters>]
cmdletLibTmux.Workspace [source]

Resolve inherited workspace paths against an explicit document base.

Description#

Return a replacement native declaration with resolved inherited directories and option values. A parsed WorkspaceFile requires an explicit BaseDirectory. LiteralPath and File read a bounded, seekable UTF-8 YAML/JSON file and use its absolute parent as the base. Paths use the FileSystem provider without wildcard expansion. Malformed declarations and invalid UTF-8 retain their native exceptions as InvalidData errors.

Expansion uses only the supplied case-sensitive string map. Supply HOME for home-directory expansion in paths; no process environment is copied implicitly. Dollar pairs represent a literal dollar sign in declaration paths and option values. Session , window and pane option values expand supplied variables; unknown variables in option values remain literal. Unresolved path variables are errors. Option names, command text, the host script, session and window names, and environment values remain literal. Resolution does not execute scripts, inspect tmux or require the resulting directories to exist. The input declaration remains unchanged.

Notes

Invalid variable maps terminate with Tmux.InvalidWorkspaceVariables before processing input. File and resolution failures retain their native exception under Tmux.WorkspaceResolutionFailed ; ErrorAction Continue permits later input.

Command details#

Command type
cmdlet
Default parameter set
Workspace
Positional binding
Enabled.
Pipeline inputs
LibTmux.Workspace.WorkspaceFile: A declaration used with BaseDirectory.; System.IO.FileInfo : A declaration file to read and resolve.
Outputs
LibTmux.Workspace.WorkspaceFile
Related APIs

Examples#

Example 1 Resolve a parsed declaration against the current filesystem directory. Pass a different explicit BaseDirectory when the declaration came from elsewhere. View source

Terminal window
$resolve = @{
    BaseDirectory = (Get-Location).Path
    Variables = @{ PROJECT = 'src' }
}
LibTmux.Workspace\Import-TmuxWorkspace -Yaml @'
session_name: development
start_directory: "${PROJECT}"
windows:
  - panes: [null]
'@ | LibTmux.Workspace\Resolve-TmuxWorkspace @resolve
Parameters
Common parameters 12

PowerShell supplies these parameters. See common parameter behavior for their effects.

Returns

LibTmux.Workspace.WorkspaceFile: The replacement declaration with document-directory provenance.

Test-TmuxWorkspace [-Workspace] <LibTmux.Workspace.WorkspaceFile> [-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>]
cmdletLibTmux.Workspace [source]

Validate a workspace declaration and its intended policies locally.

Description#

Apply the shared .NET declaration and policy checks to a native WorkspaceFile. Validation reads no tmux state and executes no commands or scripts. Importing a workspace checks syntax; this command additionally rejects incomplete or invalid declarations under the supplied policy.

Validation returns True on success. An invalid declaration writes its native error and returns False; ErrorAction Stop terminates instead. Invalid policy parameters terminate before processing input.

Local validation does not check endpoint conflicts, paths on disk, shell syntax or tmux option support. Reuse defers host-script admission until planning knows whether creation is needed. Use Get-TmuxWorkspacePlan for endpoint observation and a reviewable plan; the validation result is not permission to apply it.

Notes

Tmux.WorkspaceValidationFailed retains the native exception and declaration. Tmux.InvalidWorkspacePolicy identifies invalid policy parameters.

Command details#

Command type
cmdlet
Positional binding
Enabled.
Pipeline inputs
LibTmux.Workspace.WorkspaceFile: A parsed or programmatically constructed declaration.
Outputs
System.Boolean
Related APIs

Examples#

Example 1 Check a one-window declaration without opening a tmux connection. View source

Terminal window
LibTmux.Workspace\Import-TmuxWorkspace -Yaml @'
session_name: development
windows:
  - panes: [null]
'@ | LibTmux.Workspace\Test-TmuxWorkspace
Parameters
Common parameters 12

PowerShell supplies these parameters. See common parameter behavior for their effects.

Returns

System.Boolean : True for a valid declaration; False after a nonterminating validation error.

Discussed in Workspace guide

Esc

Type to search.

 Reference preview Open reference