Multiplexer Commands#

nash mux manages the multiplexer server and the sessions it holds. It always targets a unix domain from your configuration, and it handles the Nash-specific work: installing the server binary, reporting protocol drift, and driving sessions.

nash mux is separate from the lower-level nash cli commands. nash cli can address the GUI or the server, depending on its environment and options. nash mux talks to the server of a domain you name.

For the idea and the [mux] setting, start with Multiplexer Sessions.

Commands#

Command	What it does
`nash mux status`	Show the server state, protocol versions, and binaries.
`nash mux list`	List sessions with their window, tab, and pane counts.
`nash mux start`	Start the server when it is not running.
`nash mux stop`	Stop the server. This closes every pane it owns.
`nash mux restart`	Stop and start. This closes every pane it owns.
`nash mux new <session>`	Create a session without showing it.
`nash mux connect <session>`	Show a session. It creates the session when it is missing.
`nash mux rename <old> <new>`	Rename a session.
`nash mux kill <session>`	Close every pane in a session.
`nash mux update`	Install the server binary by hand. Nash normally does this.

$ nash mux list
SESSION WINDOWS TABS PANES
default       1    2     3
work          2    4     6

Options#

Option	Applies to	What it does
`--domain <name>`	All commands	Choose the unix domain. The default is the first unix domain.
`--json`	`list`	Print JSON instead of a table.
`--cwd <dir>`, `-- PROG ...`	`new`	Set the working directory and the program of the first pane.
`--yes`, `-y`	`stop`, `restart`, `kill`	Answer the confirmation, for scripts.
`--force`	`stop`, `restart`	Send `SIGKILL` when the server does not exit within 10 seconds.
`--class <name>`	`connect`	Switch a Nash that you started with `--class`.
`--new-gui`	`connect`	Always open a separate window.
`--dry-run`, `--from <path>`	`update`	Report without writing, or install a binary from another path.

stop, restart, and kill ask for confirmation. Without a terminal they stop and tell you to pass --yes.

new and connect start the server when it is not running. status, list, rename, and kill do not. They tell you to run nash mux start first.

nash mux new fails if a session of that name exists. Use nash mux connect to show an existing session.

Connect to a session#

nash mux connect work behaves like tmux new -A -s work:

It creates the session when no session of that name exists.
It asks a running Nash to switch to that session.
It opens a separate window when no Nash is running, or when you pass --new-gui.

Without a name, nash mux connect uses your default_session.

A window that this command opens is not a child of the pane where you typed the command. Nash ends the process tree of a pane when the pane closes, so a window that was a child of that pane would close with it.

If the running Nash is older than your nash command, it cannot switch sessions. The command says so and opens a window instead. Update the application.

Check the server#

Run nash mux status. Your paths and versions differ from this example.

$ nash mux status
Domain:          mux
Socket:          ~/.local/share/nash/sock
Server:          running (pid 4242)
Server version:  0.11.9 (protocol 51)
Sessions:        2 (1 attached client(s))
This build:      0.11.9 (protocol 51)
Server binary:   ~/Library/Application Support/nash/bin/nash-mux-server [installed] (0.11.9)
Bundled copy:    /Applications/Nash.app/Contents/MacOS/nash-mux-server (0.11.9)

The Server binary line ends with [installed], [bundled], or [env]. The label tells you which copy the next server start uses.

Where the server binary lives#

Nash looks for nash-mux-server in this order:

The path in $NASH_MUX_SERVER, when it is set. This pins the path and skips the other steps.
nash-mux-server in the bin directory of the Nash data directory, but only while it reports the same version as the running Nash.
The copy next to the running executable, inside the application bundle.

The Nash data directory is ~/Library/Application Support/nash on macOS and $XDG_DATA_HOME/nash on Linux (~/.local/share/nash by default).

The server never runs from inside the application bundle. An application update replaces the bundle and removes the old one, which would delete the file that a server runs from. So when step 3 wins, Nash first copies the bundled binary into the bin directory of the data directory and starts that copy.

This arrangement started in Nash 0.7.0, when the server left the bundle. A server start installs the bundled copy when the installed copy is missing or reports another version. On macOS, nash update refreshes the installed copy too, as part of installing a new application.

nash mux update does the same copy by hand:

$ nash mux update
Source:          /Applications/Nash.app/Contents/MacOS/nash-mux-server (0.9.1)
Destination:     ~/Library/Application Support/nash/bin/nash-mux-server (0.9.0)
Installed ~/Library/Application Support/nash/bin/nash-mux-server (0.9.1)
The running server (0.9.0) still serves this build.  It keeps its own binary
until it stops.

Use --dry-run to see the versions without writing anything. Use --from <path> to install a binary from elsewhere.

A unix domain that sets its own serve_command skips this resolution and runs that command as written. A server binary inside a Cargo target/debug or target/release directory starts in place, so a source build runs what you just built.

Two platform notes:

Linux (AppImage). The bundled copy lives inside the AppImage mount, and the mount disappears with the Nash process that owns it. The installed copy lets a server outlive the AppImage that started it.
Windows. Windows refuses to replace an executable that a running process uses. If the install fails for that reason, Nash logs a warning and starts the bundled copy instead. A server start is never blocked.

Why updates never restart the server#

Every pane is a child process of the running server. No upgrade can move those panes into a new process. So nash mux update installs the binary and leaves the running server alone, as tmux does. nash update and the automatic installs follow the same rule. The new binary serves the next server start.

nash mux restart is the explicit step that closes the panes and starts a server from the new binary. Run it when you are ready to lose them.

See Update Nash from the command line for how nash update treats a running server.

Protocol versions#

The Nash window and the server must speak the same protocol version. They do not need the same release version. A server from an earlier release keeps serving a newer Nash as long as the protocol did not change between them.

Releases	Protocol
0.7.0 to 0.7.6	47
0.8.1 to 0.10.3	48
0.11.1 to 0.11.4	49
0.11.5	50
0.11.9	51

Nash 0.11.5 adds server-reported keyboard state with protocol 50. 0.11.9 uses protocol 51 for shared tab state and the new pane queries and actions. All GUI and CLI clients and the server must speak the same protocol; there is no older-protocol compatibility mode.

Upgrade instructions when a mux restart is required#

These steps apply to any release that changes the mux protocol, including 0.11.5 and 0.11.9.

After updating the binaries, restart a running server only when its protocol differs. Installing a binary alone does not upgrade the running process. nash mux restart closes every pane owned by that server, not just the current session. Finish or save your work first. For a remote mux, update the remote server as well as the local clients before restarting it. stop and restart are Unix-only; on Windows, stop nash-mux-server manually, then start the matching server.

When the versions differ, nash mux status tells you:

$ nash mux status
Domain:          mux
Socket:          ~/.local/share/nash/sock
Server:          running (pid 4242)
Server version:  0.11.5 (protocol 50)
This build:      0.11.9 (protocol 51)
Server binary:   ~/Library/Application Support/nash/bin/nash-mux-server [installed] (0.11.9)
Bundled copy:    /Applications/Nash.app/Contents/MacOS/nash-mux-server (0.11.9)

The running server speaks protocol 50 and this build speaks 51.
Run `nash mux restart` when you can close its panes; the restart installs and
runs the matching server.

The Nash window shows the same advice when it cannot attach for this reason.

Tab commands in 0.11.9#

Nash 0.11.9 adds nash cli move-tab, set-tab-color, and set-tab-zen. They change server-owned tab state when directed at the mux server.

NASH_UNIX_SOCKET takes precedence over --prefer-mux. A local GUI pane inherits its GUI's socket, so clear that override to select the first Unix mux domain. Also clear NASH_PANE: pane and tab IDs belong to one instance and can refer to different objects on another. This helper uses the same target for listing IDs and changing state; --no-auto-start avoids starting a server:

mux_cli() {
  env -u NASH_UNIX_SOCKET -u NASH_PANE nash cli --prefer-mux --no-auto-start "$@"
}
mux_cli list --format json
# Replace 7 with a tab ID from that list.
mux_cli move-tab --tab-id 7 --index 0
mux_cli set-tab-color --tab-id 7 '#123456'
mux_cli set-tab-color --tab-id 7 --reset
mux_cli set-tab-zen --tab-id 7 true
mux_cli set-tab-zen --tab-id 7 false

Each command takes --tab-id or --pane-id, not both. Without either, it uses NASH_PANE, then the most recently active client's focused pane. With the helper's cleared environment, that means the latter.

move-tab --index is a non-negative, zero-based index in the tab's server window. An absent tab or out-of-range index is an error.
set-tab-color uses the Lua tab color parser. Quote colors containing # or spaces, and use --reset to clear a color.
set-tab-zen requires true or false; it never changes global Zen Mode.

list --format json emits one row per pane in server tab order. The tab fields color (a normalized string or null), zen_mode, and is_active_tab repeat for each pane of a split tab. is_active still means the active pane within its tab, not the selected tab. The compact table is unchanged.

Limits#

One server per machine by default. A unix domain that does not set socket_path uses the same socket as every other one, and the daemon locks one pid file. So --domain selects configuration, not a second server. Give a domain its own socket_path and daemon_options to run two servers.

A cold server creates its own session. When nash-mux-server starts, it opens one window in its default session. So nash mux new work against a server that was not running leaves you with default and work.

GUI saves are not server checkpoints. Since 0.11.9, saved layouts omit fully detachable mux windows and retain only restorable local content from mixed layouts. Reach a running session with nash mux connect; restoring a GUI layout does not restart a server or resurrect its processes.

nash mux stop and nash mux restart need a Unix system. Every other subcommand works on all platforms. On Windows, end the nash-mux-server process instead.