# tmux_command

- **Package:** libtmux_erlang
- **Language:** Erlang
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-erlang/blob/d1b6308440cf9eb8f6647e7ae434bce60e849368/apps/libtmux_erlang/src/tmux_command.erl#L1
- **Page:** https://libtmux.org/en/erlang/latest/reference/tmux_command/

Build tmux commands and bounded sequences without performing I/O.

Arguments remain binary values. Rendering protects trailing semicolons from
tmux's command separator parser. This is distinct from shell quoting and from
format expansion. A raw command is trusted application code; external services
must apply their own command allowlist and write policy.

Use `literal_format/1` only for a whole argument that tmux
expands as a format, such as a new name or cwd. It does not encode a value
nested in a format expression. tmux's stored-name escaping and session-name
substitutions still apply. Use `literal_format/2` with mode time
for commands such as [display-message](/en/tmux/latest/manual/display-message/) that also expand strftime percent
directives. This protects one format-expansion pass, not later visual style
rendering or recursive/nested expansion. No renderer reverses stored-name
semantics.

`launch/1` distinguishes executable argv from an explicitly
requested shell command. A singleton argv uses the installed helper's
exec-only mode because tmux otherwise passes one argument to its default
shell. Empty argv is invalid; default_shell explicitly requests tmux's
configured default command/shell. The internal helper uses an absolute path so
a child's cwd does not change helper resolution. Relative executable arguments
retain their native meaning.

Empty shell commands have command-specific lifetime. [split-window](/en/tmux/latest/manual/split-window/) creates a
process-free pane. [new-session](/en/tmux/latest/manual/new-session/) executes an empty shell command and can remove
the new object immediately. [new-window](/en/tmux/latest/manual/new-window/) does likewise before tmux 3.8; tmux 3.8
creates a process-free pane. Use a persistent job for parent sessions/windows
that must remain available across supported versions.

Submit commands through `tmux_server:command/3` or `tmux_operation:start/3`.
`sequence/1` combines flat command values for one-shot execution with combined
output and a possible completed prefix on error.
The [job guide](jobs.md) shows submission, completion and cancellation.
`tmux_session:rename_command/2` and `tmux_pane:resize_command/2` build values
bound to their row's captured origin. Execution through another endpoint
returns different_owner before native work. Construction does not validate
endpoint liveness or authorize an automatic mutation retry.

`wait_for/2` builds native channel signals, waits and advisory locks.
`source_file/2` builds configuration loading from stdin or a literal absolute
path. Both return command values without opening an endpoint or doing I/O.
`to_config/1` renders a command or bounded command list for native
configuration input, preserving argument bytes through tmux's lexer.

## Examples

```erlang
1> {ok, C} = tmux_command:raw(<<"list-panes">>, [<<"-a">>]), ok.
ok
2> tmux_command:argv(C).
[<<"list-panes">>,<<"-a">>]
3> tmux_command:literal_format(<<"api-#{pane_id}">>).
{ok,<<"api-##{pane_id}">>}
4> tmux_command:launch(#{argv => [<<"/bin/printf">>, <<"hello">>]}).
{ok,[<<"/bin/printf">>,<<"hello">>]}
```

## Members

### Common operations

- [`source_file/2`](/en/erlang/latest/reference/tmux_command-source_file-2/) (function): Build configuration loading from stdin or one literal absolute path, without I/O. `stdin` renders `source-file -`; supply configuration bytes in the `stdin` option of `tmux_server:command/3` or `tmux_operation:start/3`. Those APIs bound input to 256 KiB including their argument reservation.
- [`wait_for/2`](/en/erlang/latest/reference/tmux_command-wait_for-2/) (function): Build a native `wait-for` command without I/O. Channels are nonempty NUL-free binary names, subject to the command reservation in `raw/2`; neither shell nor format expansion occurs. Submit through `tmux_operation:start/3` for a wait that leaves the caller free, or through `tmux_server:command/3` to await it.
- [`to_config/1`](/en/erlang/latest/reference/tmux_command-to_config-1/) (function): Render validated commands as native configuration text, without I/O. Accepts one command, a `sequence/1` value, or a nonempty flat list of at most 256 commands. Returns an ASCII binary of at most 32 KiB, without a final newline. Validation uses `validate/1`; escaping growth, command count and aggregate size can return `command_limit`. Lists use native command separators between independently quoted commands. Rendering does not execute them or provide atomic execution or rollback. The text carries no origin token; executing serialized configuration requires the caller to choose and validate its destination explicitly.
- [`raw/2`](/en/erlang/latest/reference/tmux_command-raw-2/) (function): Validate one trusted command name and binary argv, without I/O. The renderer protects tmux separators; it does not provide shell or nested-format quoting. External services still need their own allowlists and write policy. Names are at most 128 bytes. NUL bytes are rejected, and at most 2,040 arguments fit within a 32 KiB command reservation including framing overhead.
- [`literal_format/2`](/en/erlang/latest/reference/tmux_command-literal_format-2/) (function): Quote a complete literal format argument. Mode tmux protects hash expansion; mode time also protects strftime percent directives. Stored-name semantics remain tmux's own. This handles one expansion pass, not a nested operand, recursive expansion or later visual style rendering. Performs no I/O.

### Other members

- [`argv/1`](/en/erlang/latest/reference/tmux_command-argv-1/) (function): Render a validated command into executable argv, protecting trailing tmux separators. Performs no I/O and raises for an invalid command value.
- [`launch_spec/0`](/en/erlang/latest/reference/t-tmux_command-launch_spec-0/) (typealias): Explicit executable argv, an explicitly requested shell command, or tmux's configured default shell.
- [`launch/1`](/en/erlang/latest/reference/tmux_command-launch-1/) (function): Render explicit executable argv, an explicitly requested shell command, or default_shell. Singleton argv uses the installed helper's exec-only mode to avoid tmux interpreting it as shell syntax. Performs no I/O.
- [`literal_format/1`](/en/erlang/latest/reference/tmux_command-literal_format-1/) (function): Quote a complete literal argument for tmux format expansion. This does not encode operands nested inside another format expression. Performs no I/O.
- [`respawn_spec/0`](/en/erlang/latest/reference/t-tmux_command-respawn_spec-0/) (typealias): Reuse tmux's saved command/shell, or replace it with argv or a shell command. Used by `tmux_pane:respawn/2` and `tmux_window:respawn/2`.
- [`sequence/1`](/en/erlang/latest/reference/tmux_command-sequence-1/) (function): Build one bounded native command sequence without I/O. Members must be a nonempty flat list of at most 256 command values. Their combined executable argv is limited to 2041 words and 32 KiB including separator overhead. Arguments keep the literal separator protection of `raw/2`; only boundaries between members become native command separators in `argv/1`.
- [`source_options/0`](/en/erlang/latest/reference/t-tmux_command-source_options-0/) (typealias): Native parse-only and quiet-missing-file flags; both default to false.
- [`source/0`](/en/erlang/latest/reference/t-tmux_command-source-0/) (typealias): Standard input, or one literal absolute POSIX byte path with no NUL.
- [`t/0`](/en/erlang/latest/reference/t-tmux_command-t-0/) (typealias): A validated command or flat sequence. Rendering and execution remain separate. Domain builders retain a captured endpoint origin; raw values are unbound.
- [`validate/1`](/en/erlang/latest/reference/tmux_command-validate-1/) (function): Revalidate a command value at a submission boundary. Returns a compact validated command or a tagged shape/argument/resource error, without I/O.
- [`wait_action/0`](/en/erlang/latest/reference/t-tmux_command-wait_action-0/) (typealias): Native wait channel action. lock/unlock are explicit advisory operations, not owned leases.

## Guides

Pages that discuss `tmux_command`.

- [Native API documentation](/en/erlang/latest/guides/api-documentation/)
- [Register a hook and await its effect](/en/erlang/latest/guides/hooks/)