tmuxp load

Edit this page on GitHub

workspace consumer 0.1.0-alpha.10 · Source

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

The local C++ tmux-workspace load supports foreground attachment, detached loading and explicit append. Native before_script runs direct argv before settings and windows; all inputs are validated first. Script failure removes a newly owned session and preserves a borrowed append session. NDJSON streams bounded script output.

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.

Native C++ loadingLink to section

Human load requires a foreground controlling terminal before mutation. Outside tmux it attaches to the final input’s session, including a reused session. Inside tmux it switches the unique terminal client viewing the invoking pane; zero or multiple matching clients require -d. Machine load requires -d or --append; -d takes precedence when both are supplied.

The CLI cannot identify independent active-pane focus. If a terminal client uses it on the invoking physical window, including a linked window, use -d or --append. Clients on other physical windows do not block switching. The check repeats before handoff; enabling the flag during a script preserves loaded changes and prevents switching.

Load publishes and flushes both streams before handing over the terminal. Handoff failure preserves loaded changes and reports the completed summary when possible. The client is checked again before switching; tmux’s subsequent name-targeted operation still has a race. If all three standard streams are redirected, use -d: attachment needs a stream identifying the concrete controlling tty. See output for publication failures. --log-file PATH appends JSON diagnostics; see native logging for levels and file failure behavior.

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.

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.