Server

Description#

new/1 takes an absolute :executable path and an absolute :socket path, which selects tmux's socket file with -S. Use System.find_executable/1 to resolve a name such as "tmux" through PATH before construction. The optional :cwd and :env default to the caller's working directory and environment. Construction validates the path forms without checking that the executable or socket exists. A Server is an immutable value with nothing to close; constructing one neither connects to tmux nor starts it. Commands use -N, so a missing daemon is never started implicitly.

What is on here

Server describes the endpoint. In Elixir, observation, selection and action functions live in their own modules. Start with these groups:

Connecting. new/1 describes the server for one-shot commands, which do not attach a client. LibTmux.Control.with_connection/2 attaches a control client to an existing session for a callback and closes it afterwards. LibTmux.Control.start_link/1 and LibTmux.Control.child_spec/1 support application supervision. See the managed control guide for connection setup and the host's hook and command-alias requirements.

Finding one thing. Capture with snapshot/2 , then use LibTmux.Selection.one/2 to require one match or LibTmux.Selection.one_or_nil/2 to allow no match. Both reject multiple matches. LibTmux.Ref.from_observation/1 turns the chosen observation into a reference tied to the daemon that supplied it, ready for an action.

Listing everything. snapshot/2 captures a LibTmux.Snapshot containing sessions, physical windows, window links, panes and attached clients. LibTmux.Snapshot.sessions/1 , LibTmux.Snapshot.windows/1 , LibTmux.Snapshot.window_links/1 , LibTmux.Snapshot.panes/1 and LibTmux.Snapshot.clients/1 return selections from that captured graph without contacting tmux again. Capture failures return an error, not an empty server. Capture covers an interval rather than an atomic transaction; take another snapshot when fresh state is needed.

Querying things and getting around. LibTmux.Selection.where/2 accepts criteria such as active: true; LibTmux.Selection.filter/2 accepts an Elixir function. Selections work with Enum and Stream . Navigate the captured graph with LibTmux.Session.windows/2 , LibTmux.Session.panes/2 , LibTmux.Session.active_window/2 and LibTmux.Window.panes/2 , or use LibTmux.Snapshot.related/4 for other relationships. These functions use the supplied snapshot. Plural relationship helpers return lists; a LibTmux.WindowLink preserves a window's membership in one session.

Changing things. LibTmux.Pane.split/3 creates a pane and returns its ID and bound reference in the completed result. LibTmux.Session.rename/4 and LibTmux.Window.rename/4 change names. LibTmux.Pane.send_text/4 sends literal bytes, while LibTmux.Pane.send_keys/4 sends named keys such as "Enter". These functions take a Server or Control connection followed by a reference. Domain bang variants return completed values or raise; nonbang variants return outcomes to inspect. See the action guide and recovery guide.

Reading screens, options and formats. LibTmux.Pane.capture/3 reads pane screen bytes through one-shot execution, including when given a Control connection. On a control connection, LibTmux.Control.execute/3 runs LibTmux.Control.Request.field/2 reads and LibTmux.Control.Request.set_user_option/2 server user-option writes. Use LibTmux.Control.submit/3 and LibTmux.Operation when the result needs to remain available for independent inspection.

Other tmux commands are available through LibTmux.Command.new/2 and run/3 , which runs one command with literal arguments and returns bounded output and exit evidence. Configured server hooks can still run. One-shot actions check the observed server identity before writing, leaving a race if the daemon is replaced between that check and the command. Use a qualified Control connection for mutations bound to one daemon instance.