Miscellaneous Commands

Utility and control flow commands for tmux

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]

Execute a command conditionally based on the success or failure of a shell command.

-b · flag

Run shell-command in the background.

-F · flag

Do not execute shell-command. Instead, consider it successful if it is neither empty nor zero after formats are expanded.

-t · string

The target pane for format expansion context.

shell-command · string · required

Shell command to execute (or format to evaluate with -F).

command · string · required

Command to execute if shell-command succeeds (exits with 0). The second optional command is executed if it fails.

Format Expansion

Before being executed, 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]

Execute a shell command or tmux command in the background without creating a window.

-b · flag

Run the command in the background. By default, the command blocks.

-C · flag

Execute as a tmux command instead of a shell command.

-E · flag

Redirect the command’s stderr to stdout instead of ignoring it.

-c · string

Set the current working directory to start-directory.

-d · number

Wait for delay seconds before starting the command.

-t · string

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 · string

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

Block or signal a channel for synchronization between commands.

-L · flag

Lock the channel. Any clients that try to lock the same channel are made to wait until it is unlocked with -U.

-S · flag

Signal the channel. Wake any clients waiting on this channel.

-U · flag

Unlock the channel (use with -L).

channel · string · required

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

Execute commands from one or more files.

-F · flag

Expand formats in the file.

-n · flag

Do not execute commands, just parse them and report errors.

-q · flag

Suppress errors about non-existent files.

-v · flag

Verbose output showing each command as it is executed.

path · string · required

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]

Display a large clock in the target pane.

-t · string

The target pane.

Press any key to exit clock mode.

Related Options

• clock-mode-colour: Color of the clock
• clock-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-server

Lock each client individually by running the command specified by the lock-command option.

Related Options

• 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

Ask for confirmation before executing a command.

-b · flag

Show the prompt in the background (allow other commands to run).

-p · string

Custom prompt message. Default is “command (y/n)”.

-t · string

The target client for displaying the prompt.

command · string · required

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]

Open a command prompt in the status line.

-1 · flag

Accept only one key press as input.

-F · flag

Expand formats in the template.

-i · flag

Execute the template immediately without waiting for user input.

-k · flag

Accept a key name instead of a command.

-N · flag

Accept only numeric input.

-T · flag

Accept only a target (session, window, or pane).

-W · flag

Accept only a window name.

-I · string

Comma-separated list of initial input values.

-p · string

Comma-separated list of prompt strings.

-t · string

The target client.

template · string

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]

List the syntax of commands supported by tmux.

-F · string

Format for each line. Available format variables:

• #{command_list_name}: Command name
• #{command_list_alias}: Command alias
• #{command_list_usage}: Command usage

command · string

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-server

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 '%%'"