Scripting

You can fold panes from a shell script or from Lua. This is useful for a layout script, a build wrapper, or a key that folds every pane but one.

nash cli fold-pane

nash cli fold-pane [--pane-id <ID>] [--fold | --unfold | --toggle]

The nash cli command talks to a running Nash window or multiplexer. See the command line overview.

Option	Effect
--fold	Folds the pane if it is not folded. This is the default.
--unfold	Unfolds the pane if it is folded.
--toggle	Folds the pane if it is not folded, and unfolds it if it is.
--pane-id	The pane to change. The default is the pane that runs the command.

Use only one of --fold, --unfold, and --toggle.

Which pane

If you omit --pane-id, the command uses the NASH_PANE environment variable. Nash sets it in every pane, so nash cli fold-pane folds the pane you run it in. Outside a pane, the command uses the focused pane of the client that was active most recently.

List panes and their ids with nash cli list. Add --format json to read the output from a script. Each entry has window_id, tab_id, pane_id, title, and cwd, among other fields.

Which Nash

The command connects to a running Nash window. With several instances, you can pick one: --class selects a window class, --prefer-mux uses the first unix domain from your configuration, and the NASH_UNIX_SOCKET variable names a socket.

Exit status

Folding a pane that is already folded, or unfolding a pane that is not folded, is not an error. If Nash refuses the change, the command prints the error and exits with status 1. Nash refuses when:

• the tab has only this pane (cannot fold the only pane in a tab),
• every other pane is already folded (cannot fold the last visible pane in a tab),
• the pane does not exist.

See How Folding Rearranges Your Panes.

Examples

Fold a pane that is not the one you are in. Look up its id first:

nash cli list
nash cli fold-pane --pane-id 3
nash cli fold-pane --pane-id 3 --unfold

Toggle the pane that runs the command, from a key binding or a script:

nash cli fold-pane --toggle

Fold every other pane in the current tab. This script needs jq:

tab=$(nash cli list --format json |
  jq ".[] | select(.pane_id == $NASH_PANE) | .tab_id")

nash cli list --format json |
  jq -r ".[] | select(.tab_id == $tab and .pane_id != $NASH_PANE) | .pane_id" |
  while read -r id; do nash cli fold-pane --pane-id "$id"; done

The pane you run the script in stays unfolded, so Nash never refuses the last fold.

Lua

The Lua API for a tab object has three methods. A tab object comes from window:active_tab(), for example.

Method	Effect
tab:fold_pane(pane)	Folds the pane. It raises an error if the pane is not in the tab, or if the fold would leave no unfolded pane.
tab:unfold_pane(pane)	Unfolds the pane. It does nothing if the pane is not folded.
tab:set_folded(bool)	Folds or unfolds the active pane. It returns the earlier state. A refused fold is logged.

tab:panes_with_info() reports is_folded for each pane, next to is_active and is_zoomed. The PaneInformation objects that Nash passes to event callbacks, such as format-tab-title, have an is_folded field as well.

Folding the active pane moves focus to its closest unfolded neighbor, as in the interface. Folding any other pane leaves focus where it is.

An event handler in ~/.config/nash/custom.lua can unfold everything in the active tab:

local nash = require 'nash'

nash.on('unfold-all', function(window, pane)
  local tab = window:active_tab()
  for _, info in ipairs(tab:panes_with_info()) do
    if info.is_folded then
      tab:unfold_pane(info.pane)
    end
  end
end)

Bind the event to a key in ~/.config/nash/keys.lua:

local nash = require 'nash'

return {
  { key = 'u', mods = 'CTRL|ALT|SHIFT', action = nash.action.EmitEvent 'unfold-all' },
}

For the actions you can bind to keys, see Keys and Commands.