(cli-load)=
(tmuxp-load)=
(tmuxp-load-reference)=
Load tmux sessions from workspace configuration files. This is the primary command for starting sessions from YAML or JSON configurations.
.. argparse::
:module: tmuxp.cli
:func: create_parser
:prog: tmuxp
:path: load
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/.tmuxpfolder - The direct path of the tmuxp file you want to load
Path to folder with .tmuxp.yaml, .tmuxp.yml, .tmuxp.json:
Projects with a file named `.tmuxp.yaml` or `.tmuxp.json` can be loaded:
```console
// current directory
$ tmuxp load .
```
```console
$ tmuxp load ../
```
```console
$ tmuxp load path/to/folder/
```
```console
$ tmuxp load /path/to/folder/
```
Name of the config, assume `$HOME/.tmuxp/myconfig.yaml`:
```console
$ tmuxp load myconfig
```
Direct path to json/yaml file:
```console
$ tmuxp load ./myfile.yaml
```
```console
$ tmuxp load /abs/path/to/myfile.yaml
```
```console
$ tmuxp load ~/myfile.yaml
```
Absolute and relative directory paths are supported.
```console
$ tmuxp load [filename]
```
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]:
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
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] ...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] ...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]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.
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 myprojectOr via environment variable:
$ TMUXP_PROGRESS_FORMAT=verbose tmuxp load myprojectUse 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}%" myprojectThe 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 myprojectShow unlimited lines (capped to terminal height):
$ tmuxp load --progress-lines -1 myprojectSet a custom height (default is 3):
$ tmuxp load --progress-lines 5 myprojectDisable the animated spinner entirely:
$ tmuxp load --no-progress myprojectOr via environment variable:
$ TMUXP_PROGRESS=0 tmuxp load myprojectWhen progress is disabled, logging flows normally to the terminal and no spinner is rendered.
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.