libtmux-workspace 0.0.1-alpha.12-SNAPSHOT · 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.
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
| Argument or flags | Arity / default | Choices or meaning |
|---|---|---|
"workspace_files" | one or more | filepath to session or filename of session in tmuxp workspace directory |
-L | value; None | passthru to tmux(1) -L |
-S | value; None | passthru to tmux(1) -S |
-f | value; None | passthru to tmux(1) -f |
-s | value; None | start new session with new session name |
--yes, -y | flag; False | always answer yes |
-d | flag; False | load the session without attaching it |
-a, --append | flag; False | load workspace, appending windows to the current session |
-2 | flag; None | force tmux to assume the terminal supports 256 colours. |
-8 | flag; None | legacy 88-colour flag; unsupported by tmux 3.2a+ |
--log-file | value; None | file to log errors/output to |
--progress-format | value; None | Spinner line format: preset name (default, minimal, window, pane, verbose) or a format string with tokens {session}, {window}, {progress}, {window_progress}, {pane_progress}, etc. Env: TMUXP_PROGRESS_FORMAT |
--progress-lines | value; None | Number of script-output lines shown in the spinner panel (default: 3). 0 hides the panel entirely (script output goes to stdout). -1 shows unlimited lines (capped to terminal height). Env: TMUXP_PROGRESS_LINES |
--no-progress | flag; False | Disable the animated progress spinner. Env: TMUXP_PROGRESS=0 |
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.