tmuxp load

Edit this page on GitHub

LibTmux.Workspace 0.0.0-alpha.14 · 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 native .NET CLI’s --append authenticates the inherited daemon and retains one session across all inputs. It uses the current pane’s session as resolved by tmux; moving the pane later does not change that destination. Later commands reject a replacement daemon, including global options after a startup script. Append with Python plugins or custom builders fails before building any input or starting Python. Use -d to load those extensions into a separate session.

Native load creates panes in configuration order, including windows with three or more panes. pane-base-index changes the first index, and explicit focus selects the configured pane without reordering it. See pane configuration.

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 .NET command rejects -8 and --88-colors before reading workspace files or running tmux or Python. On Linux x64, load --log-file PATH appends structured logs. Select --log-level info for lifecycle records or debug to include script output. The output reference describes destination validation and failure handling.

Native .NET attachmentLink to section

Human load requires a foreground controlling terminal on Linux x64 for attachment. Inside tmux, choose y to switch a client, n to load detached, or a to append. -y refuses an ambiguous client choice. A client using independent active-pane focus on the invoking window prevents handoff; detached and append modes remain available.

The CLI authenticates the invoking pane and daemon before building, flushes output, and checks the selected client again before handoff. Late failures print recorded load results on stderr. SIGINT and SIGTERM report cancellation; a completed load can remain present after interruption during attachment. A client name can still be reused after the final client observation.

Attached Python extension handoff remains unavailable. Use -d or choose n to run those extensions detached. See the native handoff source.

Progress and script outputLink to section

Native .NET load implements the presets and named tokens below on a stderr terminal with verified geometry on Linux x64. Templates treat bare names as tokens and {{/}} as literal braces; unknown fields, conversions and format specifiers remain literal. Explicit format and line-count flags override their environment defaults. Disabled drawing does not validate unused progress environment values.

--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 tmuxp 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.

The native panel also defaults to three lines, but --progress-lines 0 preserves each decoded script stream’s original destination. Native pane counters advance after command delivery and configured delays; they do not measure shell command completion. Python extensions show a generic activity label. --no-progress, TMUXP_PROGRESS=0, TERM=dumb, machine output and redirected stderr disable drawing. NO_COLOR removes styling while keeping updates. On resize, drawing stops, the old frame remains and raw output resumes.

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.