Session Commands

Commands for creating, managing, and controlling tmux sessions

Overview

The tmux server manages clients, sessions, windows, and panes. Clients are attached to sessions to interact with them. Each session has one or more windows linked into it.

attach-session

Alias: attach

attach-session [-dErx] [-c working-directory] [-f flags] [-t target-session]

Attach to an existing session. If run from outside tmux, attach to target-session in the current terminal. If used from inside tmux, switch the currently attached session.

-d · flag

Detach any other clients attached to the session.

-E · flag

Do not apply the update-environment option.

-r · flag

Alias for -f read-only,ignore-size. Makes the client read-only.

-x · flag

Send SIGHUP to the parent process of the client as well as detaching, typically causing it to exit.

-c · string

Set the session working directory (used for new windows) to working-directory.

-f · string

Comma-separated list of client flags:

• active-pane - client has an independent active pane
• ignore-size - client does not affect the size of other clients
• no-detach-on-destroy - do not detach when session is destroyed if other sessions exist
• no-output - client does not receive pane output in control mode
• pause-after=seconds - output is paused once pane is seconds behind in control mode
• read-only - client is read-only
• wait-exit - wait for empty line input before exiting in control mode

Prefix with ! to turn a flag off if client is already attached.

-t · string

The target session. Must already exist.

Target Session Selection

When tmux needs to select the most recently used session, it prefers the most recently used unattached session.

new-session

Alias: new

new-session [-AdDEPX] [-c start-directory] [-e environment] [-f flags] 
            [-F format] [-n window-name] [-s session-name] [-t group-name] 
            [-x width] [-y height] [shell-command [argument ...]]

Create a new session with name session-name.

-A · flag

If session-name already exists, behave like attach-session. When combined with -D, behaves like -d to attach-session, and with -X, behaves like -x to attach-session.

-d · flag

Do not attach the new session to the current terminal (create in detached mode).

-D · flag

With -A, detach other clients when attaching (like -d to attach-session).

-E · flag

Do not apply the update-environment option.

-P · flag

Print information about the new session after it has been created. Default format is #{session_name}: but can be changed with -F.

-X · flag

With -A, send SIGHUP to parent process when attaching (like -x to attach-session).

-c · string

Specify the working directory for the new session.

-e · string

Set an environment variable for the newly created session in the form VARIABLE=value. May be specified multiple times.

-f · string

Comma-separated list of client flags (see attach-session).

-F · string

Format for output when -P is used.

-n · string

Name for the initial window.

-s · string

Name for the new session.

-t · string

Specify a session group. Sessions in the same group share the same set of windows. The argument may be:

• Name of an existing group
• Name of an existing session (new session joins same group)
• Name for a new group containing only the new session

Cannot be used with -n or shell-command.

-x · number

Width for the session. Use - for the size of the current client.

-y · number

Height for the session. Use - for the size of the current client.

shell-command · string

Shell command to execute in the initial window.

Initial Size

With -d, the initial size comes from the default-size option. Use -x and -y to specify a different size. If -x or -y is given, the default-size option is set for the session.

detach-client

Alias: detach

detach-client [-aP] [-E shell-command] [-s target-session] [-t target-client]

Detach the current client if bound to a key, the client specified with -t, or all clients currently attached to the session specified by -s.

-a · flag

Kill all clients except the client given with -t.

-P · flag

Send SIGHUP to the parent process of the client, typically causing it to exit.

-E · string

Run shell-command to replace the client.

-s · string

Detach all clients attached to target-session.

-t · string

The target client to detach.

has-session

Alias: has

has-session [-t target-session]

Report an error and exit with 1 if the specified session does not exist. If it does exist, exit with 0.

-t · string

The target session to check.

kill-session

kill-session [-aC] [-t target-session]

Destroy the given session, closing any windows linked to it and no other sessions, and detaching all clients attached to it.

-a · flag

Kill all sessions except the specified one.

-C · flag

Clear alerts (bell, activity, or silence) in all windows linked to the session.

-t · string

The target session to destroy.

list-sessions

Alias: ls

list-sessions [-r] [-F format] [-f filter] [-O sort-order]

List all sessions managed by the server.

-r · flag

Reverse the sort order.

-F · string

Specify the format of each line. See the FORMATS section.

-f · string

Only show sessions for which the filter is true.

-O · string

Specify sort order: index, name, creation (time), or activity (time).

rename-session

Alias: rename

rename-session [-t target-session] new-name

Rename the session to new-name.

-t · string

The target session to rename.

new-name · string · required

The new name for the session.

lock-session

Alias: locks

lock-session [-t target-session]

Lock all clients attached to target-session.

-t · string

The target session to lock.

kill-server

kill-server

Kill the tmux server and clients and destroy all sessions.

switch-client

Alias: switchc

switch-client [-ElnprZ] [-c target-client] [-t target-session] [-T key-table]

Switch the current client to another session or manipulate its key table.

-E · flag

Do not apply the update-environment option.

-l · flag

Move to the last session.

-n · flag

Move to the next session.

-p · flag

Move to the previous session.

-r · flag

Toggle the client read-only flag.

-Z · flag

Keep the window zoomed if it was zoomed.

-c · string

Specify the target client.

-t · string

The target session.

-T · string

Set the client’s key table to key-table. The next key will be looked up in this table. Useful for creating custom key bindings.