# LibTmux.Server

- **Module:** LibTmux
- **Package:** libtmux
- **Language:** Elixir
- **Kind:** struct
- **Source:** https://github.com/libtmux/libtmux-elixir/blob/66b9b1c3f3f3186428abdfda2c76f5cf87446710/lib/libtmux/server.ex#L1
- **Page:** https://libtmux.org/en/elixir/latest/reference/libtmux-server/

Describes a local tmux server for capturing state and running commands.

`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](managed-control.html)
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](one-shot-actions.html) and [recovery guide](recovery.html).

**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.

## Members

### Collections and queries

- [`snapshot/2`](/en/elixir/latest/reference/libtmux-server-snapshot-2/) (function): Captures a new graph explicitly, with bounded work and read retries.

### Common operations

- [`run/3`](/en/elixir/latest/reference/libtmux-server-run-3/) (function): Runs one trusted command without attaching; returns bounded output and exit evidence.
- [`new/1`](/en/elixir/latest/reference/libtmux-server-new-1/) (function): Constructs a descriptor for an existing server without connecting or creating it.
- [`snapshot!/2`](/en/elixir/latest/reference/libtmux-server-snapshot-bang-2/) (function): Captures a graph or raises the same structured capture error.

### Other members

- [`cwd`](/en/elixir/latest/reference/libtmux-server-cwd/) (property): Required: building the struct without this key is an error.
- [`env`](/en/elixir/latest/reference/libtmux-server-env/) (property): Required: building the struct without this key is an error.
- [`executable`](/en/elixir/latest/reference/libtmux-server-executable/) (property): Required: building the struct without this key is an error.
- [`option/0`](/en/elixir/latest/reference/libtmux-server-option-0/) (typealias): Descriptor inputs; executable, socket and cwd are absolute NUL-free paths.
- [`socket`](/en/elixir/latest/reference/libtmux-server-socket/) (property): Required: building the struct without this key is an error.
- [`t/0`](/en/elixir/latest/reference/libtmux-server-t-0/) (typealias): An explicit local server descriptor; constructing it neither connects nor reserves server identity.

## In other ports

### A tmux server

- PowerShell: [`LibTmux\New-TmuxServer`](/en/powershell/latest/reference/libtmux-new-tmuxserver/) (cmdlet). This cmdlet constructs a shared .NET `LibTmux.Server` handle without contacting tmux.
- Julia: [`LibTmux.Server`](/en/julia/latest/reference/libtmux-server/) (struct). `Server` describes an endpoint without contacting tmux. Read its hierarchy with `snapshot`.
- Python: [`libtmux.Server`](/en/py/latest/reference/libtmux-server/) (class)
- Ruby: [`LibTmux::Server`](/en/ruby/latest/reference/libtmux-server/) (class)
- Lua: [`libtmux.Server`](/en/lua/latest/reference/libtmux-server/) (class)
- TypeScript: [`server.Server`](/en/ts/latest/reference/server-server/) (class)
- Rust: [`server.Server`](/en/rs/latest/reference/server-server/) (struct)
- Go: [`tmux.Server`](/en/go/latest/reference/tmux-server/) (struct)
- Java: [`io.github.libtmux.Server.Server`](/en/java/latest/reference/io-github-libtmux-server-server/) (class)
- C#: [`LibTmux.Server`](/en/csharp/latest/reference/libtmux-server/) (class)
- C++: [`libtmux::Server`](/en/cxx/latest/reference/libtmux-server/) (class)
- Swift: [`Server`](/en/swift/latest/reference/server/) (struct)
- Kotlin: [`io.github.libtmux.kotlin.Server`](/en/kotlin/latest/reference/io-github-libtmux-kotlin-server/) (class)
- Scala: [`io.github.libtmux.scaladsl.Server`](/en/scala/latest/reference/io-github-libtmux-scaladsl-server/) (typealias)
- F#: [`LibTmux.FSharp.Server`](/en/fsharp/latest/reference/libtmux-fsharp-server/) (module). This F# module provides functions over the shared .NET `LibTmux.Server` type.