tmuxp load

Edit this page on GitHub

github.com/libtmux/libtmux-go/workspace · Source

tmuxp compatibility reference. Examples using tmuxp run the Python reference. Local CLI status describes this port’s implemented coverage.

Load a workspace file, saved workspace name, or project directory. Multiple inputs build in order; without -d, the final session is attached or selected through the current-client flow.

The local Go CLI’s load --append authenticates the inherited server and retains one destination session for all inputs. Moving the invoking pane during a script does not change that destination. Python extension append uses the same retained target and rejects documents with a before_script key. See compatibility status for the execution limits.

Loading and attachmentLink to section

Create workspace.yaml using the installation walkthrough, then load it on that walkthrough’s dedicated socket:

$ tmuxp load \
    -S "$WORKSPACE_TMP/tmux.sock" \
    -d \
    "$WORKSPACE_TMP/workspace.yaml"

-d avoids attachment. Inside an existing tmux client, the normal interactive flow can switch to the new session, append windows, or stay detached. --append explicitly selects the append flow and needs a current target session. An existing session is handled through tmuxp’s load policy; loading is not a declarative reconciliation operation that removes surplus windows.

Put flags before the complete group of filenames. The reference accepts flags before or after that group, but a flag between two filenames can cause an argument error. -s overrides the final input’s session name when several files are loaded. tmuxp parses -2 and -8 as mutually exclusive flags, separate from the CLI text’s --color setting. Legacy -8 is unsupported; tmux removed 88-color support.

The native Go CLI supports --log-level and structured --log-file output on Unix. It checks the log destination before Python or tmux starts. A later logging failure preserves the workspace outcome; script-output records use debug. See the logging contract.

Progress and script outputLink to section

--progress-format accepts default, minimal, "window", "pane", verbose, or a custom format. Available tokens include {session}, {window}, {window_index}, {window_total}, {window_progress}, {window_progress_rel}, {windows_done}, {windows_remaining}, {pane_index}, {pane_total}, {pane_progress}, {progress}, {session_pane_progress}, {overall_percent}, {bar}, {pane_bar}, {window_bar}, and {status_icon}.

The output panel defaults to three lines. --progress-lines 0 hides the panel and sends script output to stdout; -1 permits all available lines up to terminal height. --no-progress disables animation. See environment settings for environment bindings and command ordering for what is executed.

Arguments and flagsLink to section

All commands accept -h / --help. Root options precede the command; see the CLI overview. The output reference distinguishes current Python flags from native all-command JSON and NDJSON.

Parser and implementation source.

tmuxp reference source.