Overview
Miscellaneous commands provide control flow, conditional execution, and utility functions in tmux.
if-shell
Alias: if
if-shell [-bF] [-t target-pane] shell-command command [command]
Run shell-command in the background.
Do not execute shell-command. Instead, consider it successful if it is neither empty nor zero after formats are expanded.
The target pane for format expansion context.
Shell command to execute (or format to evaluate with -F).
Command to execute if shell-command succeeds (exits with 0). The second optional command is executed if it fails.
shell-command is expanded using format rules.
Examples
# Execute command if shell command succeeds
if-shell "test -f ~/.tmux.local.conf" "source ~/.tmux.local.conf"
# With else clause
if-shell "test -n $SSH_CONNECTION" \
"set status-bg red" \
"set status-bg green"
# Using formats without executing shell
if-shell -F "#{==:#{host},myhost}" \
"set status-bg blue"
# Background execution
if-shell -b "sleep 5 && echo done" "display 'Command finished'"
# Check session existence
if-shell -F "#{session_attached}" \
"display 'Session is attached'" \
"display 'Session is detached'"
run-shell
Alias: run
run-shell [-bCE] [-c start-directory] [-d delay] [-t target-pane] [shell-command]
Run the command in the background. By default, the command blocks.
Execute as a tmux command instead of a shell command.
Redirect the command’s stderr to stdout instead of ignoring it.
Set the current working directory to start-directory.
Wait for delay seconds before starting the command.
The target pane. Any output to stdout is displayed in view mode in this pane after the command finishes (unless -b is given or the command is a tmux command with -C).
Shell command to execute. Before execution, expanded using format rules.
Output Display
Without -C or -b, output to stdout is displayed in view mode in the target pane (or current pane) after the command finishes. The exit status is also displayed if the command fails.
Examples
# Run command and show output
run-shell "uptime"
# Run in background
run-shell -b "sleep 10 && tmux display 'Done'"
# Run tmux command
run-shell -C "new-window"
# With delay
run-shell -d 5 "echo 'After 5 seconds'"
# With working directory
run-shell -c /tmp "pwd"
# Capture stderr
run-shell -E "command-that-errors 2>&1"
# Complex example with formats
run-shell "echo 'Current window: #{window_name}' > /tmp/tmux.log"
wait-for
Alias: wait
wait-for [-L | -S | -U] channel
Lock the channel. Any clients that try to lock the same channel are made to wait until it is unlocked with -U.
Signal the channel. Wake any clients waiting on this channel.
Unlock the channel (use with -L).
The name of the channel to wait on, signal, lock, or unlock.
Behavior
Without options, prevents the client from exiting until woken using wait-for -S with the same channel.
Examples
# Simple wait and signal
# Terminal 1:
run-shell "sleep 5 && tmux wait-for -S mychannel"
# Terminal 2 (will wait for signal):
wait-for mychannel ; display "Signal received"
# Lock pattern
run-shell -b '
tmux wait-for -L mylock
# ... critical section ...
sleep 2
tmux wait-for -U mylock
'
# Multiple commands waiting
run-shell -b "tmux wait-for mychan ; tmux display 'Job 1 done'"
run-shell -b "tmux wait-for mychan ; tmux display 'Job 2 done'"
run-shell "sleep 3 && tmux wait-for -S mychan"
# Coordination between sessions
if-shell '[ -f /tmp/setup-done ]' '' '
wait-for -L setup
if-shell "[ ! -f /tmp/setup-done ]" "
run-shell setup-script.sh
run-shell touch /tmp/setup-done
"
wait-for -U setup
'
source-file
Alias: source
source-file [-Fnqv] path ...
Expand formats in the file.
Do not execute commands, just parse them and report errors.
Suppress errors about non-existent files.
Verbose output showing each command as it is executed.
Path to configuration file(s) to source. Can specify multiple files.
Examples
# Source a configuration file
source-file ~/.tmux.conf
# Source multiple files
source-file ~/.tmux.conf ~/.tmux.local.conf
# Source with error suppression
source-file -q ~/.tmux.optional.conf
# Validate configuration without executing
source-file -n ~/.tmux.conf
# Verbose execution
source-file -v ~/.tmux.conf
# Source with format expansion
source-file -F ~/.tmux.#{host}.conf
clock-mode
clock-mode [-t target-pane]
clock-mode-colour: Color of the clockclock-mode-style: Clock format (12 or 24)
Examples
# Display clock in current pane
clock-mode
# Display clock in specific pane
clock-mode -t 0
# Set clock options and display
set-option -w clock-mode-colour blue
set-option -w clock-mode-style 12
clock-mode
lock-server
Alias: lock
Lock each client individually by running the command specified by the lock-command option.
lock-command: Command to run when locking (default: lock -np)lock-after-time: Lock session after seconds of inactivity (default 0, disabled)
Examples
# Lock all clients
lock-server
# Set custom lock command
set-option -g lock-command "vlock"
# Enable auto-lock after 5 minutes
set-option -g lock-after-time 300
confirm-before
Alias: confirm
confirm-before [-b] [-p prompt] [-t target-client] command
Show the prompt in the background (allow other commands to run).
Custom prompt message. Default is “command (y/n)”.
The target client for displaying the prompt.
The command to execute if confirmed.
Examples
# Confirm before killing pane
confirm-before kill-pane
# Custom prompt
confirm-before -p "Kill session? (y/n)" kill-session
# Bind to key
bind-key X confirm-before -p "Kill window #{window_name}? (y/n)" kill-window
command-prompt
command-prompt [-1FikNTW] [-I inputs] [-p prompts] [-t target-client] [template]
Accept only one key press as input.
Expand formats in the template.
Execute the template immediately without waiting for user input.
Accept a key name instead of a command.
Accept only numeric input.
Accept only a target (session, window, or pane).
Accept only a window name.
Comma-separated list of initial input values.
Comma-separated list of prompt strings.
Command template. %% is replaced by the user’s input, or %1, %2, etc. for multiple prompts.
Examples
# Simple command prompt
command-prompt
# Rename window prompt
command-prompt -I "#{window_name}" -p "New window name:" "rename-window '%%'"
# Multiple prompts
command-prompt -p "Width:","Height:" "resize-window -x %1 -y %2"
# Numeric only
command-prompt -N -p "Window index:" "select-window -t:%1"
# Target selection
command-prompt -T -p "Target pane:" "swap-pane -t '%%'"
# Single key press
command-prompt -1 -p "Key:" "send-keys '%%'"
list-commands
Alias: lscm
list-commands [-F format] [command]
Format for each line. Available format variables:
#{command_list_name}: Command name#{command_list_alias}: Command alias#{command_list_usage}: Command usage
List only this command. If omitted, all commands are listed.
Examples
# List all commands
list-commands
# List specific command
list-commands new-window
# Custom format
list-commands -F "#{command_list_name} (#{command_list_alias})"
start-server
Alias: start
Start the tmux server if not already running. Normally not needed as the server is started automatically.
Practical Examples
Conditional Configuration
# Load different configs based on hostname
if-shell -F "#{==:#{host},work-laptop}" \
"source ~/.tmux.work.conf" \
"source ~/.tmux.home.conf"
# Load optional local config
if-shell "test -f ~/.tmux.local.conf" \
"source ~/.tmux.local.conf"
Background Jobs
# Monitor and notify
run-shell -b '
while true; do
if some-check; then
tmux display "Check passed"
break
fi
sleep 60
done
'
Synchronized Setup
# Ensure one-time setup
if-shell "test ! -f ~/.tmux-setup-done" "
run-shell setup-script.sh
run-shell touch ~/.tmux-setup-done
"
Interactive Prompts
# Quick window creation with prompt
bind-key C-n command-prompt -p "Window name:" "new-window -n '%%'"
# Rename with current name as default
bind-key , command-prompt -I "#{window_name}" \
"rename-window '%%'"
# Jump to window
bind-key j command-prompt -p "Jump to window:" \
"select-window -t '%%'"