# LibTmux::Server - **Module:** LibTmux - **Package:** LibTmux - **Language:** Perl - **Kind:** class - **Source:** https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/packages/core/lib/LibTmux/Server.pm#L1 - **Page:** https://libtmux.org/en/perl/latest/reference/libtmux-server/ ``` package LibTmux::Server; ``` Explicit tmux acquisition and commands ## SYNOPSIS ```perl use v5.44; use LibTmux::Server; my $server = LibTmux::Server->new(socket_name => 'application'); my $snapshot = $server->snapshot; my $pane = $snapshot->panes->first; say $server->capture_pane(pane => $pane) if defined $pane; ``` ## CONTRACT Construction and planning perform no I/O. Acquisition and mutation are explicit, bounded operations. Captured [`LibTmux::Snapshot`](/en/perl/latest/reference/libtmux-snapshot/) entities retain their observed graph; mutations do not refresh them. Acquire another snapshot to observe changes. Connection settings remain owned by the server wrapper; destroying it never kills a tmux daemon. See the [orchestration guide](https://github.com/libtmux/libtmux-perl/blob/master/docs/orchestration.md). Physical entity targets accept stable ID strings or generation-checked handles. Session-relative window operations require [`LibTmux::WindowLink`](/en/perl/latest/reference/libtmux-windowlink/). Checks across subprocesses are optimistic rather than transactional. Single-quote session IDs such as `'$1'` to avoid interpolating a Perl capture variable. ## ERRORS Invalid arguments throw [`"InvalidArgument" in LibTmux::X`](/en/perl/latest/reference/libtmux-x-invalidargument/) before dispatch. Acquisition and checked commands propagate typed [`LibTmux::X`](/en/perl/latest/reference/libtmux-x/) failures, including missing executables, absent daemons, vanished targets, stale handles, codec errors, timeouts, and output limits. Failures never become empty selections. Cancellation or a timeout after dispatch does not prove nonexecution or roll back effects. ## VERIFICATION REPORT [`"query_panes"`](/en/perl/latest/reference/libtmux-server-query_panes/) supplies a fresh, detached hashref to `on_verification`. It contains no entity handles. Every ID array retains stable order; editing the report cannot mutate captured data or the query result. `policy`, `status`, `comparison`Policy is auto, never, require, or native for the expert escape hatch. Status is disabled (never), local (no safe lowering), agreed, disagreed, or native. Comparison is none, exact_ids, candidate_superset, or captured_membership. Partial lowering checks inclusion of local matches; expert queries check only membership in the captured graph. Neither establishes full filter equivalence.`native_checked`, `translation_exact`, `native_filter`, `reasons`native_checked is Boolean. translation_exact is Boolean, or undef for never and expert queries. native_filter is the executed expression, or undef when no native check ran. reasons is a fresh arrayref of lowering limitations. Exact translation and agreement between two observations are separate facts.`server_id`, `generation`, `daemon_version`, `capture_start`, `capture_end`Identity strings and the captured interval in wall-clock seconds since the epoch, from [`"metadata" in LibTmux::Snapshot`](/en/perl/latest/reference/libtmux-snapshot-metadata/). This is not an atomic observation.`captured_ids`, `local_ids`, `native_ids`captured_ids and local_ids follow physical capture order; local_ids is undef for expert queries. native_ids holds unique IDs in native first-occurrence order, or undef when no check ran. An empty array is an observed empty set.`missing_ids`, `unexpected_ids`, `uncaptured_ids`missing_ids lists local matches absent natively, in local order. For exact lowering, unexpected_ids lists native matches absent locally. uncaptured_ids lists native IDs absent from the graph. The latter two follow native order; inapplicable lists are empty. Any applicable mismatch produces disagreed. [`"QueryMismatch" in LibTmux::X`](/en/perl/latest/reference/libtmux-x-querymismatch/) carries this report for require or expert failures; the observer is not called for a failed query. A discrepancy has no inferred cause: concurrent changes, compiler defects and backend differences all need investigation. ## Examples Complete installed-package program with an owned tmux fixture and result/cleanup assertions. [Source example](https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/examples/quickstart.pl). ```perl use v5.44; use Config; use FindBin; use lib "$FindBin::Bin/../scripts/lib"; use LibTmuxFixture; # This complete demo owns a Linux child-reaping scope, including tmux panes. BEGIN { die 'Requires Linux x86_64 LP64' unless $^O eq 'linux' && $Config::Config{archname} =~ /x86_64/ && $Config::Config{ptrsize} == 8 && $Config::Config{ivsize} == 8; syscall(157, 36, 1, 0, 0, 0) == 0 or die "subreaper: $!"; } try { LibTmuxFixture->run( sub ($server, $root) { my $session = $server->new_session( name => 'demo', command => ['/bin/cat'] ); my $failure; try { my $editor = $session->window_links->one->window; $server->rename_window(window => $editor, name => 'editor'); my $right = $server->split_pane( pane => $editor->panes->one, horizontal => true, command => ['/bin/cat'] ); my $logs = $server->new_window( session => $session, name => 'logs', command => ['/bin/cat'] ); $server->select_pane(pane => $right); my $snapshot = $server->snapshot; my $link = $snapshot->window_links->one( { window => {-is => {id => $logs->id}} } ); $server->select_window(link => $link); $snapshot = $server->snapshot; for my $entry ($snapshot->sessions->@*) { say 'session ', $entry->name; for my $link ($entry->window_links->@*) { my $window = $link->window; my $ids = join ' ', map { $_->id } $window->panes->@*; my $label = $link->index . ':' . $window->name; say ' window ', $label, ': ', $ids; } } my $panes = $snapshot->windows->one({name => 'editor'}) ->panes->where({width => {-gte => 1}}) ->grep(sub ($pane) { $pane->height >= 1 }); my $selected = $panes->one({active => true}); die 'unexpected pane membership' unless $panes->count == 2; my $name = $selected->window->name; say $selected->id, ' is in window ', $name; } catch ($error) { $failure = $error } $server->kill_session(session => $session); die $failure if defined $failure; } ); } catch ($error) { warn "tmux quickstart failed: $error\n"; die $error; } ``` ## Members ### Collections and queries - [`clients`](/en/perl/latest/reference/libtmux-server-clients/) (method): `clients()`. - [`snapshot`](/en/perl/latest/reference/libtmux-server-snapshot/) (method): `snapshot()`. - [`query_panes`](/en/perl/latest/reference/libtmux-server-query_panes/) (method): `query_panes(where => criteria|Filter?, pushdown => auto|never|require?, native_filter => string?, on_verification => coderef?)`. ### Common operations - [`capture_pane`](/en/perl/latest/reference/libtmux-server-capture_pane/) (method): `capture_pane(pane => Pane|pane_id, start => integer?, end => integer?)`. - [`send_keys`](/en/perl/latest/reference/libtmux-server-send_keys/) (method): `send_keys(pane => Pane|pane_id, keys => arrayref)`. - [`new_session`](/en/perl/latest/reference/libtmux-server-new_session/) (method): `new_session(name => string, command => arrayref?, shell_command => string?, width => integer?, height => integer?, cwd => bytes?, environment => hashref?)`. - [`new_window`](/en/perl/latest/reference/libtmux-server-new_window/) (method): `new_window(session => Session|session_id, name => string?, command => arrayref?, shell_command => string?, cwd => bytes?, environment => hashref?)`. - [`split_pane`](/en/perl/latest/reference/libtmux-server-split_pane/) (method): `split_pane(pane => Pane|pane_id, horizontal => boolean?, command => arrayref?, cwd => bytes?, environment => hashref?)`. - [`kill_server`](/en/perl/latest/reference/libtmux-server-kill_server/) (method): `kill_server()`. - [`select_layout`](/en/perl/latest/reference/libtmux-server-select_layout/) (method): `select_layout(window => Window|window_id, layout => string)`. - [`kill_session`](/en/perl/latest/reference/libtmux-server-kill_session/) (method): `kill_session(session => Session|session_id)`. - [`kill_window`](/en/perl/latest/reference/libtmux-server-kill_window/) (method): `kill_window(window => Window|window_id)`. - [`kill_pane`](/en/perl/latest/reference/libtmux-server-kill_pane/) (method): `kill_pane(pane => Pane|pane_id)`. - [`rename_session`](/en/perl/latest/reference/libtmux-server-rename_session/) (method): `rename_session(session => Session|session_id, name => string)`. - [`rename_window`](/en/perl/latest/reference/libtmux-server-rename_window/) (method): `rename_window(window => Window|window_id, name => string)`. - [`link_window`](/en/perl/latest/reference/libtmux-server-link_window/) (method): `link_window(window => Window|window_id, session => Session|session_id, index => integer?)`. - [`unlink_window`](/en/perl/latest/reference/libtmux-server-unlink_window/) (method): `unlink_window(link => WindowLink|session_id:index)`. - [`select_window`](/en/perl/latest/reference/libtmux-server-select_window/) (method): `select_window(link => WindowLink|session_id:index)`. - [`select_pane`](/en/perl/latest/reference/libtmux-server-select_pane/) (method): `select_pane(pane => Pane|pane_id)`. - [`resize_pane`](/en/perl/latest/reference/libtmux-server-resize_pane/) (method): `resize_pane(pane => Pane|pane_id, width => positive_integer?, height => positive_integer?)`. - [`show_hooks`](/en/perl/latest/reference/libtmux-server-show_hooks/) (method): `show_hooks(target => session_id?, global => boolean?)`. - [`move_window`](/en/perl/latest/reference/libtmux-server-move_window/) (method): `move_window(link => WindowLink|session_id:index, session => Session|session_id, index => integer?)`. - [`set_title`](/en/perl/latest/reference/libtmux-server-set_title/) (method): `set_title(pane => Pane|pane_id, title => string)`. - [`show_buffer`](/en/perl/latest/reference/libtmux-server-show_buffer/) (method): `show_buffer(name => string)`. - [`set_buffer`](/en/perl/latest/reference/libtmux-server-set_buffer/) (method): `set_buffer(name => string, data => bytes)`. - [`delete_buffer`](/en/perl/latest/reference/libtmux-server-delete_buffer/) (method): `delete_buffer(name => string)`. - [`cmd`](/en/perl/latest/reference/libtmux-server-cmd/) (method): `cmd(@literal_arguments)`. - [`set_option`](/en/perl/latest/reference/libtmux-server-set_option/) (method): `set_option(name => string, value => string|integer, scope => session|window|pane|server, target => id?, global => boolean?)`. - [`unset_option`](/en/perl/latest/reference/libtmux-server-unset_option/) (method): `unset_option(name => string, scope => scope, target => id?, global => boolean?)`. - [`set_hook`](/en/perl/latest/reference/libtmux-server-set_hook/) (method): `set_hook(name => hook_or_hook[index], command => explicit_tmux_command_string, target => session_id?, global => boolean?)`. - [`set_environment`](/en/perl/latest/reference/libtmux-server-set_environment/) (method): `set_environment(name => env_name, value => bytes, session => session_target?)`. - [`unset_environment`](/en/perl/latest/reference/libtmux-server-unset_environment/) (method): `unset_environment(name => env_name, session => session_target?)`. - [`get_option`](/en/perl/latest/reference/libtmux-server-get_option/) (method): `get_option(name => string, scope => scope, target => id?, global => boolean?, inherited => boolean?)`. - [`detach_client`](/en/perl/latest/reference/libtmux-server-detach_client/) (method): `detach_client(client => Client|client_name)`. - [`get_environment`](/en/perl/latest/reference/libtmux-server-get_environment/) (method): `get_environment(name => env_name, session => session_target?)`. ### Other members - [`attach_argv`](/en/perl/latest/reference/libtmux-server-attach_argv/) (method): `attach_argv(session => session_id)`. - [`batch`](/en/perl/latest/reference/libtmux-server-batch/) (method): `batch(arrayref_of_argv)`. - [`execute`](/en/perl/latest/reference/libtmux-server-execute/) (method): `execute(argv => arrayref, stdin => bytes?, timeout => seconds?, cancel_fh => handle?)`. - [`explain_panes`](/en/perl/latest/reference/libtmux-server-explain_panes/) (method): `explain_panes(where => criteria|Filter, pushdown => policy?)`. - [`listings`](/en/perl/latest/reference/libtmux-server-listings/) (method): `listings(kind)`. - [`new`](/en/perl/latest/reference/libtmux-server-new/) (method): `new(executable => tmux, socket_name|socket_path => string, timeout => seconds, max_output => bytes, config_file => path, env => hashref)`. - [`operation`](/en/perl/latest/reference/libtmux-server-operation/) (method): `operation($name, %arguments)` validates and copies arguments, returning one [`LibTmux::Operation`](/en/perl/latest/reference/libtmux-operation/) without I/O. The optional Future facade shares this preparation and parsing boundary. Use the named methods above for synchronous execution. Invalid arguments or criteria throw [`"InvalidArgument" in LibTmux::X`](/en/perl/latest/reference/libtmux-x-invalidargument/) or [`"InvalidFilter" in LibTmux::X`](/en/perl/latest/reference/libtmux-x-invalidfilter/) before submission. - [`send_text`](/en/perl/latest/reference/libtmux-server-send_text/) (method): `send_text(pane => Pane|pane_id, text => string|bytes, enter => boolean?)`. ## Guides Pages that discuss `Server`. - [Create sessions, windows, and panes](/en/perl/latest/examples/orchestration/) ## In other ports A tmux server | Language | Equivalent | | --- | --- | | 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) | | 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`. | | Erlang | [`tmux_server`](/en/erlang/latest/reference/tmux_server/) (module). `open/1` observes an existing daemon and starts an endpoint owner. Domain rows remain immutable values. | | Elixir | [`LibTmux.Server`](/en/elixir/latest/reference/libtmux-server/) (struct). `Server` describes an existing server by executable and socket. It neither connects nor reserves the server’s identity. | | Haskell | No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing. | | 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`](/en/java/latest/reference/io-github-libtmux-server-server/) (class) | | Clojure | [`libtmux.core/open!`](/en/clojure/latest/reference/libtmux-core-open/) (function). Opens a closeable Java server client for an explicit endpoint. Acquisitions return persistent maps with explicit Java references for effects. | | 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) | | C# | [`LibTmux.Server`](/en/csharp/latest/reference/libtmux-server/) (class) | | F# | [`LibTmux.FSharp.Server`](/en/fsharp/latest/reference/libtmux-fsharp-server/) (module). This F# module provides functions over the shared .NET `LibTmux.Server` type. | | C++ | [`libtmux::Server`](/en/cxx/latest/reference/libtmux-server/) (class) | | Swift | [`Server`](/en/swift/latest/reference/server/) (struct) | | OCaml | [`Libtmux_unix.Client.t`](/en/ocaml/latest/reference/libtmux_unix-client-t/) (typealias). A client is a live, generation-bound server connection. Endpoint describes a socket without connecting; closing a client releases its resources. | No equivalent is recorded in Common Lisp.