tmuxp load¶

Load tmux sessions from workspace configuration files. This is the primary command for starting sessions from YAML or JSON configurations.

Command¶

Load tmuxp workspace file(s) and create or attach to a tmux session.

Usage¶

usage: tmuxp load [-h] [-L socket_name] [-S socket_path] [-f tmux_config_file]
                  [-s new_session_name] [--yes] [-d] [-a] [-2 | -8]
                  [--log-file file_path] [--progress-format FORMAT]
                  [--progress-lines N] [--no-progress]
                  workspace-file [workspace-file ...]

Examples¶

$ tmuxp load myproject

$ tmuxp load ./workspace.yaml

$ tmuxp load -d myproject

$ tmuxp load -y dev staging

$ tmuxp load -L other-socket myproject

$ tmuxp load -a myproject

Positional Arguments¶

workspace_files workspace-file¶

filepath to session or filename of session in tmuxp workspace directory

Default: None
Required

Options¶

-L socket_name¶

passthru to tmux(1) -L

Default: None

-S socket_path¶

passthru to tmux(1) -S

Default: None

-f tmux_config_file¶

passthru to tmux(1) -f

Default: None

-s new_session_name¶

start new session with new session name

Default: None

--yes, -y¶

always answer yes

Default: False

-d¶

load the session without attaching it

Default: False

-a, --append¶

load workspace, appending windows to the current session

Default: False

--log-file file_path¶

file to log errors/output to

Default: None

--progress-format FORMAT¶

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

Default: None

--progress-lines N¶

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

Default: None
Type: int

--no-progress¶

Disable the animated progress spinner. Env: TMUXP_PROGRESS=0

Default: False

-2¶

force tmux to assume the terminal supports 256 colours.

Default: None

-8¶

like -2, but indicates that the terminal supports 88 colours.

Default: None

Basic usage¶

You can load your tmuxp file and attach the tmux session via a few shorthands:

The directory with a .tmuxp.{yaml,yml,json} file in it
The name of the project file in your $HOME/.tmuxp folder
The direct path of the tmuxp file you want to load

Path to folder with .tmuxp.yaml, .tmuxp.yml, .tmuxp.json:

Project based

Projects with a file named .tmuxp.yaml or .tmuxp.json can be loaded:

// current directory
$ tmuxp load .

$ tmuxp load ../

$ tmuxp load path/to/folder/

$ tmuxp load /path/to/folder/

User based

Name of the config, assume $HOME/.tmuxp/myconfig.yaml:

$ tmuxp load myconfig

Direct path to json/yaml file:

$ tmuxp load ./myfile.yaml

$ tmuxp load /abs/path/to/myfile.yaml

$ tmuxp load ~/myfile.yaml

Direct

Absolute and relative directory paths are supported.

$ tmuxp load [filename]

Inside sessions¶

If you try to load a workspace file from within a tmux session, it will ask you if you want to load and attach to the new session, or just load detached. You can also load a workspace file and append the windows to the current active session.

Already inside TMUX, switch to session? yes/no
Or (a)ppend windows in the current active session?
[y/n/a]:

Options¶

All of these options can be preselected to skip the prompt:

Attach / open the client after load:
```
$ tmuxp load -y config
```
Detached / open in background:
```
$ tmuxp load -d config
```
Append windows to existing session
```
$ tmuxp load -a config
```

Loading multiple sessions¶

Multiple sessions can be loaded at once. The first ones will be created without being attached. The last one will be attached if there is no -d flag on the command line.

$ tmuxp load [filename1] [filename2] ...

Custom session name¶

A session name can be provided at the terminal. If multiple sessions are created, the last session is named from the terminal.

$ tmuxp load -s [new_session_name] [filename1] ...

Logging¶

The output of the load command can be logged to a file for debugging purposes. the log level can be controlled with the global --log-level option (defaults to INFO).

$ tmuxp load [filename] --log-file [log_filename]

$ tmuxp --log-level [LEVEL] load [filename] --log-file [log_filename]

Progress display¶

When loading a workspace, tmuxp shows an animated spinner with build progress. The spinner updates as windows and panes are created, giving real-time feedback during session builds.

Presets¶

Five built-in presets control the spinner format:

Preset	Format
`default`	`Loading workspace: {session} {bar} {progress} {window}`
`minimal`	`Loading workspace: {session} [{window_progress}]`
`window`	`Loading workspace: {session} {window_bar} {window_progress_rel}`
`pane`	`Loading workspace: {session} {pane_bar} {session_pane_progress}`
`verbose`	`Loading workspace: {session} [window {window_index} of {window_total} · pane {pane_index} of {pane_total}] {window}`

Select a preset with --progress-format:

$ tmuxp load --progress-format minimal myproject

Or via environment variable:

$ TMUXP_PROGRESS_FORMAT=verbose tmuxp load myproject

Custom format tokens¶

Use a custom format string with any of the available tokens:

Token	Description
`{session}`	Session name
`{window}`	Current window name
`{window_index}`	Current window number (1-based)
`{window_total}`	Total number of windows
`{window_progress}`	Window fraction (e.g. `1/3`)
`{window_progress_rel}`	Completed windows fraction (e.g. `1/3`)
`{windows_done}`	Number of completed windows
`{windows_remaining}`	Number of remaining windows
`{pane_index}`	Current pane number in the window
`{pane_total}`	Total panes in the current window
`{pane_progress}`	Pane fraction (e.g. `2/4`)
`{progress}`	Combined progress (e.g. `1/3 win · 2/4 pane`)
`{session_pane_progress}`	Panes completed across the session (e.g. `5/10`)
`{overall_percent}`	Pane-based completion percentage (0–100)
`{bar}`	Composite progress bar
`{pane_bar}`	Pane-based progress bar
`{window_bar}`	Window-based progress bar
`{status_icon}`	Status icon (⏸ during before_script)

Example:

$ tmuxp load --progress-format "{session} {bar} {overall_percent}%" myproject

Panel lines¶

The spinner shows script output in a panel below the spinner line. Control the panel height with --progress-lines:

Hide the panel entirely (script output goes to stdout):

$ tmuxp load --progress-lines 0 myproject

Show unlimited lines (capped to terminal height):

$ tmuxp load --progress-lines -1 myproject

Set a custom height (default is 3):

$ tmuxp load --progress-lines 5 myproject

Disabling progress¶

Disable the animated spinner entirely:

$ tmuxp load --no-progress myproject

Or via environment variable:

$ TMUXP_PROGRESS=0 tmuxp load myproject

When progress is disabled, logging flows normally to the terminal and no spinner is rendered.

Before-script behavior¶

During before_script execution, the progress bar shows a marching animation and a ⏸ status icon, indicating that tmuxp is waiting for the script to finish before continuing with pane creation.