Introduction

This is the documentation for the Zellij terminal workspace.

• For installing Zellij, see: Installation
• For running Zellij in its own window, see: Zellij Terminal
• For configuring Zellij, see: Configuration and the Settings Screen
• For the CLI interface, see: Controlling Zellij through the CLI
• For setting up layouts: Layouts
• For keeping track of what needs you across sessions: Inbox & Attention
• For developing plugins: Plugins

You can also check out some Screencasts & Tutorials about using Zellij.

Installation

The easiest way to install Zellij is to run the launch script, which downloads the latest release and starts it:

The scripts can be read before running them: launch (Linux / macOS) and launch.ps1 (Windows).

The first time Zellij runs, the setup screen offers to install it: copy it to a permanent folder, add it to the app menu, the Dock or the Start menu, and (on Linux) make it the default terminal. Without these steps, the downloaded copy stays in a temporary folder, so the script can also be used to try Zellij without installing it.

The same can be done by hand: download the executable for your system and run it (see Binary Download for the details of each platform).

Zellij can also be installed through your OS's package manager, with cargo binstall, or compiled and installed with Cargo.

Once installed, Zellij can be run inside any terminal with zellij, or in its own window with zellij terminal.

Rust - Cargo

For instructions on how to install Cargo see here.

Once installed run:

cargo install --locked zellij

If experiencing errors, if installed through rustup, please try running:

rustup update

This also installs a small zellij-terminal launcher next to zellij, which opens the Zellij terminal. The Zellij terminal is part of the default terminal Cargo feature. To build without it, leave the terminal feature out, eg.:

cargo install --locked zellij --no-default-features --features plugins_from_target,vendored_curl,web_server_capability

Cargo - binstall

For smaller machines like laptops, you might want to just install the binary instead of compiling everything.

The easiest way if cargo is present, is to install with the binstall cargo extension:

cargo binstall zellij

Binary Download

Pre-built binaries are available each release for Linux, macOS, and Windows on the release page.

Linux / macOS

Once downloaded, untar the file:

tar -xvf zellij*.tar.gz

check for the execution bit:

chmod +x zellij

and then execute Zellij:

./zellij

Include the directory Zellij is in, in your PATH Variable if you wish to be able to execute it anywhere.

'Or'

move Zellij to a directory already included in your [$PATH] Variable.

The Linux and macOS archives hold only the zellij binary. Each release also has a zellij-desktop-files.tar.gz, holding the desktop entry, icons and software-centre listing, meant for packagers. To add Zellij to the app menu yourself, use Desktop Setup instead.

Windows

Two downloads are available for Windows on the release page:

• The installer (zellij-x86_64-pc-windows-msvc-installer.msi) installs Zellij and can add it to the PATH. It can also add a Start menu shortcut (a checkbox on its first screen, on by default) and an "Open Zellij here" item to Explorer's folder menu. Silent installs can leave the shortcut out with REMOVE=StartMenuShortcut.
• The zip (zellij-x86_64-pc-windows-msvc.zip) holds zellij.exe and zellij-terminal.exe. Extract it, then run zellij.exe from a terminal (e.g., PowerShell or Windows Terminal), or double-click zellij-terminal.exe to open Zellij in its own window. Keep both files in the same folder.

The setup screen can copy Zellij from the zip to a permanent folder and put it on the PATH, see Desktop Setup.

Compiling Zellij From Source

Instructions on how to compile Zellij from source can be found here.

Third party repositories

Zellij is packaged in some third part repositories. Please keep in mind that they are not directly affiliated with zellij maintainers:

More information about third party installation can be found here.

Integration

Zellij provides some environment variables, that make Integration with existing tools possible.

echo $ZELLIJ
echo $ZELLIJ_SESSION_NAME

The ZELLIJ_SESSION_NAME has the session name as its value, and ZELLIJ gets set to 0 inside a zellij session. Arbitrary key value pairs can be set through configuration, or layouts. Note that ZELLIJ_SESSION_NAME will not be updated for existing terminal panes when renaming a session (but will for new panes).

Reporting status to the inbox

Programs and scripts can tell Zellij whether they are working, waiting for the user, finished or failed, and Zellij shows this in its inbox. Many programs already do this. See Inbox Integrations for the list, and for a shell function that reports the status of a script.

A command can also be run in a watched pane, so that Zellij reports when it finishes:

zellij run --notify -- cargo build

Opening Zellij from other apps

The Zellij terminal can be opened from scripts, desktop shortcuts and other apps:

zellij terminal
zellij terminal --working-directory ~/code
zellij terminal -e htop
zellij terminal --inbox
zellij terminal --sessions

On Linux, Zellij can also become the default terminal, so that apps that open a terminal open Zellij instead. See Desktop Setup.

Environment variables read by Zellij

Here are some limited examples to help get you started:

Autostart on shell creation

Autostart a new zellij shell, if not already inside one. Shell dependent, fish:

if set -q ZELLIJ
else
  zellij
end

other ways, zellij provides a pre-defined auto start scripts.

bash

echo 'eval "$(zellij setup --generate-auto-start bash)"' >> ~/.bashrc

zsh

echo 'eval "$(zellij setup --generate-auto-start zsh)"' >> ~/.zshrc

fish

⚠️ Depending on the version of the fish shell, the setting may not work. In that case, check out this issue.

Add

if status is-interactive
    ...
    eval (zellij setup --generate-auto-start fish | string collect)
end

to $HOME/.config/fish/config.fish file.

The following environment variables can also be used in the provided script.

List current sessions

List current sessions, attach to a running session, or create a new one. Depends on sk & bash

#!/usr/bin/env bash
ZJ_SESSIONS=$(zellij list-sessions)
NO_SESSIONS=$(echo "${ZJ_SESSIONS}" | wc -l)

if [ "${NO_SESSIONS}" -ge 2 ]; then
    zellij attach \
    "$(echo "${ZJ_SESSIONS}" | sk)"
else
   zellij attach -c
fi

List layout files and create a layout

List layout files saved in the default layout directory, opens the selected layout file. Depends on: tr, fd, sed, sk, grep & bash

#!/usr/bin/env bash
set -euo pipefail
ZJ_LAYOUT_DIR=$(zellij setup --check \
    | grep "LAYOUT DIR" - \
    | grep -o '".*"' - | tr -d '"')

if [[ -d "${ZJ_LAYOUT_DIR}" ]];then
        ZJ_LAYOUT="$(fd --type file . "${ZJ_LAYOUT_DIR}" \
        | sed 's|.*/||' \
        | sk \
        || exit)"
    zellij --layout "${ZJ_LAYOUT}"
fi

FAQ

Zellij overrides certain key combinations that I use for other apps, what can I do?

The best and easiest way is to choose the "Unlock-First (non-colliding)" keybinding preset. If that is not sufficient for your use case, you can also choose different modifiers.

The UI takes up too much space, what can I do about it?

You can load the compact layout with zellij --layout compact.

The bars (eg. the tab bar and the status bar) can also be hidden:

• While Zellij runs: with Shift z in pane mode (the ToggleBars action), with "Hide all bars" in the right-click menu of a bar, or with zellij action hide-bars. They come back the same way, or with ShowBars.
• From the start: with the bars_hidden_on_start option, eg. bars_hidden_on_start "all".

While the bar with the keys of the current mode is hidden, those keys are shown in a corner of the screen when entering a mode (see mode_hints_when_bars_hidden).

Things don't work right in my terminal emulator, what can I do?

Some problems come from the terminal emulator Zellij runs in rather than from Zellij: copy / paste not working, keys (eg. Alt on macOS) not reaching Zellij, missing or broken characters, missing colors or images.

The easiest solution is the Zellij terminal (zellij terminal), Zellij's own window, where these work without any setup.

The entries below explain how to fix these in other terminals.

I see broken characters in the default UI, how can I fix this?

This means your default terminal font doesn't include some special characters used by Zellij. A safe bet would be to install and use a font from nerdfonts.

If you don't want to install a new font, you can also load the simplified UI that doesn't use these characters, with:

zellij options --simplified-ui true

The Zellij terminal includes the Nerd Font symbols, so these characters are shown there without installing a font.

I am a macOS user, how can I use the Alt key?

In the Zellij terminal, the left Option key acts as Alt by default. This can be changed with the macos_option_as_alt setting of the terminal block ("left", "right", "both" or "none"):

terminal {
    macos_option_as_alt "both"
}

For other terminal emulators, this depends on which one you're using. Here are some links that might be useful:

1. iTerm2
2. Terminal.app
3. Alacritty

Copy / Paste isn't working, how can I fix this?

Some terminals don't support the OSC 52 signal, which is the method Zellij uses by default to copy text to the clipboard. To get around this, you can switch to a supported terminal (eg. the Zellij terminal, Alacritty or xterm) or configure Zellij to use an external utility when copy pasting (eg. xclip, wl-copy or pbcopy).

To do the latter, add one of the following to your Zellij Config:

copy_command "xclip -selection clipboard" // x11
copy_command "wl-copy"                    // wayland
copy_command "pbcopy"                     // osx

Note that the only method that works when connecting to a remote Zellij session (eg. through SSH) is OSC 52. If you require this functionality, please consider using a terminal that supports it.

How can I use floating panes?

You can toggle showing/hiding floating panes with Ctrl + <p> + <w> (if no floating panes are open, one will be opened when they are shown).

In this mode you can create additional windows as you would normally create panes (eg. with Alt + <n>). Move them with the mouse or the keyboard, and resize them as you would normally resize or move Zellij panes.

You can also embed a floating pane with Ctrl + <p> + <e>, and float an embedded pane in the same way.

How can I switch between sessions or launch a new session from within Zellij?

You can use the built-in session-manager. By default, launch it with Ctrl o + w.

session mode (Ctrl o) also has keys to move between sessions directly:

Other running sessions are also suggested in the session-manager and on the session card; see session suggestions.

Does Zellij run on Windows?

Yes. Zellij runs natively on Windows. The following differences apply compared to Linux/macOS:

• IPC: Named pipes (\\.\pipe\...) are used instead of Unix domain sockets. The maximum socket path length is 256 characters (vs 104 on macOS and 108 on Linux).
• PTY: Windows pseudo-terminals (ConPTY) are used instead of Unix PTYs.
• Web Server: The built-in web server is fully functional on Windows, including the --daemonize flag which uses a --server-startup-timeout option (default: 10 seconds) for background server startup.
• Session names: a session name cannot contain \. Renamed sessions can be attached to again on Windows.
• Desktop app: Zellij can run in its own window, the Zellij terminal, started with zellij-terminal.exe (installed next to zellij.exe) or zellij terminal. It has an icon in the notification area (tray) and shows notifications as Windows notifications. The setup screen can add a Start menu shortcut and an "Open Zellij here" item to the Explorer right-click menu of folders and drives (see desktop setup).

Can I upgrade Zellij without losing my running sessions?

Yes. Sessions persist across Zellij version upgrades. The IPC contract uses protocol buffers and the socket directory uses a versioned path (contract_version_1) rather than per-Zellij-version directories. Sessions created by one Zellij version can be attached to by another version, as long as the contract version remains the same.

The socket directory is located at:

• Linux/macOS: $XDG_RUNTIME_DIR/zellij/contract_version_1/ (or equivalent)
• Windows: Named pipes under the contract_version_1 namespace

Note for script authors: If existing scripts reference the old per-version socket paths, they should be updated to use the new contract_version_1 path structure.

Each session's socket (or named pipe) is named after a short id of 12 hexadecimal characters rather than after the session's name, so renaming a session renames nothing on disk. Scripts should not build socket paths from session names; use zellij list-sessions and zellij --session <name> action ... instead. If the socket directory itself is too long for the system's limit, Zellij says so when it starts and suggests a shorter one through the ZELLIJ_SOCKET_DIR environment variable.

Editing the pane scrollbuffer with ctrl + <s> + <e> doesn't work, what's wrong?

By default, Zellij looks for an editor defined in the EDITOR or VISUAL environment variables (in this order). Make sure one is set (eg. export EDITOR=/usr/bin/vim) before Zellij starts. Alternatively, you can set one in the Zellij config using scrollback_editor.

Programs in my panes cannot read the clipboard, why?

Since 0.45.0, Zellij replies with an empty clipboard to programs that attempt to read the clipboard through OSC 52. Copying (OSC 52 write) is unaffected.

Clipboard reading can be enabled with the dangerously_enable_paste_buffer_read option, but note that once enabled, any program in any pane (including one connected over SSH) can read the system clipboard without prompting.

Zellij Terminal

Zellij can run in its own window, without another terminal emulator. This is the Zellij terminal, started with zellij terminal.

The Zellij terminal is a full terminal for Zellij sessions. On top of what Zellij does inside any terminal, it adds:

• A desktop app that keeps sessions running after their window is closed
• A tray (or menu bar) icon showing what needs you, with the inbox and the session list one click away
• Desktop notifications when a command finishes, fails or needs you
• A desktop entry, so Zellij opens from the app menu, the Dock or the Start menu like any other app (see Desktop Setup)

The look and behavior of the window (font, padding, cursor, opacity, keys, etc.) are set in the terminal block of the configuration file, described in Terminal Options. They can also be changed in the "Zellij terminal" category of the settings screen.

Platforms

The Zellij terminal runs on Linux (X11 and Wayland), macOS and Windows.

It needs a desktop. On Linux, a desktop is one where DISPLAY or WAYLAND_DISPLAY is set. Over SSH (SSH_CONNECTION, SSH_CLIENT or SSH_TTY set), inside a container or in WSL, the desktop features described in Desktop Setup are not offered. A window started from such a place opens on the computer running Zellij, not on the one the user is sitting at.

The Zellij terminal is part of the default build. Zellij built with --no-default-features and without the terminal feature does not include it.

Starting the Zellij terminal

Any of these opens a Zellij terminal window:

• Running zellij terminal from a terminal or a desktop shortcut
• Opening Zellij from the app menu, the Dock, Spotlight or the Start menu, once the desktop entry is installed
• On Linux (with a desktop) and macOS: double-clicking the zellij binary in a file manager. When zellij is started without arguments and without a terminal, it opens a window instead
• On Windows: running zellij-terminal.exe. This small launcher ships next to zellij.exe in the zip and in the MSI installer. It opens the window without a console and runs zellij.exe terminal with the same arguments

Without arguments, zellij terminal starts a new session with a generated name. Given a session name, it attaches to that session, the same way zellij attach does.

Flags

zellij terminal accepts everything zellij attach accepts, plus the flags below.

Examples:

$ zellij terminal
$ zellij terminal -c my-project
$ zellij terminal --working-directory ~/code -- htop
$ zellij terminal -e make test
$ zellij terminal --inbox
$ zellij terminal https://my-server:8082/my-session

The desktop app

Windows opened with zellij terminal are run by one desktop app in the background. The first zellij terminal starts it, and later ones hand their window over to it.

• Closing a window keeps its session running. It can be opened again from the session list. This follows the on_force_close option: with on_force_close "quit", closing a window quits its session instead.
• One window per session. With reuse_session_windows on (the default), switching a window to a session that another window already shows brings that other window forward instead. See reuse_session_windows.
• Windows opened with --standalone, --watch, a remote URL, --index, an options subcommand, or with the ZELLIJ_TERMINAL_STANDALONE environment variable set run on their own, outside the desktop app.

The tray icon

The desktop app shows a tray icon (a menu bar icon on macOS, a notification-area icon on Windows). It shows when something needs you, with a badge counting the items in the inbox. Clicking it opens the inbox and the session list.

Its menu has:

• Show inbox, Show sessions, New window
• Detach all: close all windows, or detach every client from every session
• Clear all notifications, Pause notifications (for 1 hour or until tomorrow), and a Notifications sub-menu choosing what is notified and counted
• Hide icon: until the next launch, or permanently (this saves tray_icon false in the attention block)
• Quit Zellij and stop all sessions

The icon can also be toggled with zellij action toggle-tray-icon until the app restarts. Sessions and notifications keep working while it is hidden.

The launcher's right-click menu (in the app menu, the Dock or the taskbar) has Show Inbox and Show Sessions as well. zellij terminal --inbox and zellij terminal --sessions do the same, and can be bound to a desktop keyboard shortcut.

Desktop notifications

The desktop app turns inbox items into desktop notifications: when something needs you, when a command fails and when a long command finishes. Which ones are shown, and whether they include the command text, is set in the desktop_notifications and notification_details settings of the attention block, or in Settings → Notifications.

Platform notes

Linux

• The tray icon needs a tray host (a StatusNotifierItem host). On GNOME this is the AppIndicator extension. Tiling window managers need a bar with a tray, such as waybar or i3bar.
• Desktop notifications need a notification service, such as mako or dunst on tiling window managers.
• When one of these is missing, the welcome card shown in a new window explains what to install.
• Setting Zellij as the default terminal lets other apps (eg. a file manager's "Open terminal here") open it. See Desktop Setup.
• The middle mouse button pastes the primary selection.
• Touchpad scroll momentum is only available on Wayland.

macOS

• Zellij.app can be installed from the setup screen, see Desktop Setup. It opens from Finder, Spotlight or the Dock, gets the environment of the login shell, and opens a window again when clicked after its last window was closed.
• Desktop notifications only work from the Zellij inside Zellij.app. If a zellij terminal started from a terminal is already running when Zellij.app is opened, the app hands over to it, and notifications do not work until that one is quit.
• The window has the standard macOS menu. Quitting from the Dock saves the state of every window.
• Which Option key acts as Alt is set with macos_option_as_alt.
• The Cmd versions of the copy, paste and zoom keys work in addition to the Ctrl ones.

Windows

• zellij-terminal.exe opens the window without a console. With no console to print to, errors are shown in a message box.
• Desktop notifications are Windows toasts. Clicking one brings its window forward. If Windows has notifications turned off for Zellij, the welcome card says so.
• The tray icon is in the notification area. It comes back after Explorer restarts.
• Ctrl+C or closing the console the app was started from quits the desktop app cleanly. Sessions keep running.
• A Start menu shortcut and an "Open Zellij here" item in Explorer can be added from the MSI installer or the setup screen, see Desktop Setup.

Desktop Setup

Zellij can add itself to the desktop: a copy of Zellij in a permanent folder, a desktop entry (an app menu launcher, Zellij.app on macOS, or a Start menu shortcut on Windows), and Zellij as the default terminal. These open the Zellij terminal.

The setup screen

The setup screen is shown when a new session starts for the first time (when Zellij had to create its configuration file). Until it is approved or dismissed with "Don't Show Again", it is offered again in new sessions while one of its items is still missing.

It can be opened at any time:

• From the settings screen, with Ctrl w
• From the About screen (Ctrl o + a), with s ("Setup Zellij")

The screen lists what can be set up on this computer. Items that are already set up are grayed out:

• Copy Zellij to a Permanent Folder - so zellij can be run from anywhere, and so the desktop entry and the default terminal run that copy instead of the file that was started (eg. one in the Downloads folder)
• Install Desktop Entry - an app menu launcher on Linux, Zellij.app on macOS, a Start menu entry and an "Open Zellij here" Explorer item on Windows
• Make Zellij your Default Terminal - Linux only
• Keybindings - choose a keybinding preset that avoids collisions with editors and other programs

"Approve and Finish" applies the checked items and shows what was written or removed.

Desktop items are not offered when there is no desktop: over SSH, inside a container (Distrobox, Toolbox, Flatpak, Podman, Docker), in WSL, or on Linux without DISPLAY or WAYLAND_DISPLAY. Setting the environment variable ZELLIJ_DESKTOP_INTEGRATION=on treats the environment as a desktop anyway, and ZELLIJ_DESKTOP_INTEGRATION=off never offers desktop items.

From the command line

Everything the setup screen does is also available through zellij setup. These flags use the same checks as the setup screen and can be combined:

$ zellij setup --install-desktop-entry
$ zellij setup --make-default-terminal
$ zellij setup --keybinding-preset unlock-first

When the desktop entry or the default terminal is installed from a Zellij that is not in a permanent place, Zellij copies itself to the permanent folder first and points the entry at that copy.

Linux

• Permanent folder: ~/.local/bin/zellij. No copy is offered when Zellij is already in a permanent place: a package manager's path (eg. Nix, Homebrew, cargo install), /usr, /usr/local or /opt.
• Desktop entry: ~/.local/share/applications/dev.zellij.Zellij.desktop, with icons in ~/.local/share/icons/hicolor/. It runs zellij terminal and has Show Inbox, Show Sessions and New Window actions. If a package manager already installed the launcher (in $XDG_DATA_DIRS/applications), Zellij shows it as installed by the package manager and does not write its own. An old zellij.desktop written by an earlier Zellij is removed.
• If the desktop entry later points at a Zellij that no longer exists, a new session offers to repair it.

Default terminal

Zellij can become the default terminal on KDE Plasma, Cinnamon and MATE, and on desktops that use xdg-terminal-exec. It needs the desktop entry. Zellij never changes the default terminal back by itself.

Elsewhere, the setup screen explains how to do it by hand:

• On tiling window managers, bind zellij terminal to the key used to open a terminal
• On Debian and Ubuntu, sudo update-alternatives --config x-terminal-emulator chooses the default terminal
• Installing xdg-terminal-exec lets Zellij set it

Other apps then run zellij terminal -e <command> or zellij terminal --working-directory=<dir>. Where such a command opens is set with terminal_requests.

Packaging

Each release has a zellij-desktop-files.tar.gz holding the desktop entry, icons and software-centre listing for packagers. See PACKAGING_DESKTOP.md.

macOS

• Desktop entry: ~/Applications/Zellij.app. The app contains a signed copy of Zellij (signed with /usr/bin/codesign), so that its menu bar icon and desktop notifications work. It needs macOS 11.0 or later. To update Zellij.app after upgrading Zellij, install it again (eg. with zellij setup --install-desktop-entry from a terminal).
• Permanent folder: ~/.local/bin/zellij. Zellij.app has its own copy, but running zellij from a terminal still needs one on the PATH.
• Making Zellij the default terminal is not available on macOS.

Windows

• Permanent folder: %LOCALAPPDATA%\Zellij\zellij.exe. Zellij adds that folder to the end of the user's PATH, and removes it again only when it removes the copy. No copy is offered when Zellij was installed by the MSI installer, Scoop, winget, Chocolatey or cargo, or is in Program Files.
• Start menu entry: a Zellij shortcut in the Start menu.
• "Open Zellij here": an Explorer item when right-clicking a folder, the background of a folder, or a drive.
• Making Zellij the default terminal is not offered. "Open Zellij here" is the closest equivalent.

The MSI installer can add the Start menu shortcut (a checkbox on its welcome screen, on by default) and the "Open Zellij here" item itself.

Terminal Options

Zellij can open sessions in its own window, the Zellij terminal (zellij terminal), without another terminal emulator. That window is configured in the terminal block of the configuration file.

Every key is optional. With the whole block absent, the window uses the defaults listed below. Unless noted otherwise, changes apply to open windows right away. The keys marked "requires restart" only apply to windows opened after the change.

These settings can also be changed from the settings screen.

terminal {
    font "Iosevka Term"
    font_size 13
    line_height 1.1
    padding 8
    opacity 0.95
    blur true
    cursor_style "bar"
    theme {
        background "#101010"
    }
}

• Fonts: font, font_bold, font_italic, font_bold_italic, font_size, font_weight, system_fonts, ligatures, font_features
• Cells and padding: line_height, cell_width, baseline_offset, underline_offset and underline_thickness, padding, padding_balance, padding_color, minimum_contrast
• Cursor: cursor_style, cursor_blink, cursor_unfocused_hollow
• Keys: paste_keys, copy_keys, fullscreen_keys, zoom_in_keys, zoom_out_keys and zoom_reset_keys, macos_option_as_alt
• Mouse and scrolling: middle_click_paste, open_links, open_links_with_shift, shift_drag_selects, hide_pointer_while_typing, smooth_scrolling, scroll_animation_duration, scroll_momentum, scroll_momentum_friction
• Window: opacity, opacity_mode, blur, startup_mode, initial_columns and initial_rows, reuse_session_windows, terminal_requests, bell
• Clipboard: allow_remote_clipboard_read
• Colors: theme

Fonts

font

The font family to draw text with, found through the system's font configuration. A family that cannot be found falls back to the font built into Zellij.

Default: the built-in font

font "Iosevka Term"

font_bold, font_italic, font_bold_italic

Font families for bold, italic and bold italic text, each used in place of the font family's own face for that style. A style without one of these, or whose family cannot be found, keeps the font family's face.

Default: not set

font_bold "Iosevka Term"
font_italic "Iosevka Term"
font_bold_italic "Iosevka Term"

font_size

The font size in points, as other terminals measure it. Any number above 0.

Default: 12

font_size 13.5

font_weight

The weight of regular text: a number from 100 to 900, or one of these names: "thin" (100), "extralight" (200), "light" (300), "regular" (400), "medium" (500), "semibold" (600), "bold" (700), "extrabold" (800), "black" (900). Bold text uses a face 300 heavier, up to 900. Variable fonts are set to the exact weight.

Default: "regular" (400)

font_weight "medium"

system_fonts

Whether to use the system's fonts for characters the main font does not have.

Default: true

system_fonts false

ligatures

Whether the font's ligatures are formed, so that sequences like -> or != are drawn as one shape.

Default: true

ligatures false

font_features

OpenType features to turn on, or to turn off with a leading -, as four-character tags. Listing any feature shapes text even with ligatures false. In that case, liga, calt and dlig stay off unless they are listed here.

Default: none

font_features "ss01" "zero" "-calt"

Cells and padding

line_height

The height of a cell as a multiple of the font's own line height, from 0.5 to 3.0. The extra space is shared evenly above and below the text.

Default: 1.0

line_height 1.2

cell_width

The width of a cell as a multiple of the font's own character width, from 0.5 to 3.0. Characters keep their shape and are centered in the cell.

Default: 1.0

cell_width 1.1

baseline_offset

Pixels to move the text down inside its cell (or up, when negative), from -64 to 64.

Default: 0

baseline_offset 1

underline_offset and underline_thickness

Pixels to move the underline down (or up, when negative), and pixels to add to (or remove from) its thickness, each from -64 to 64. The underline always stays inside the cell.

Default: 0

underline_offset 1
underline_thickness 1

padding

Empty space around the text, in pixels, from 0 to 1000. It is scaled with the display, but not with zoom. padding sets every side, and padding_top, padding_right, padding_bottom and padding_left override one side each.

Default: 0

padding 8
padding_top 4

padding_balance

Whether the pixels left over when the window is not a whole number of cells are shared evenly on all sides, instead of all going to the right and bottom edges.

Default: false

padding_balance true

padding_color

How the padding is painted:

• "background" (default) - with the theme background and the window opacity
• "extend" - continuing the background of the nearest cell at the edge of the grid

padding_color "extend"

minimum_contrast

The lowest allowed contrast ratio between text and its background, from 1.0 (off) to 21.0. Text colors below it are adjusted.

Default: 1.0

minimum_contrast 4.5

Cursor

cursor_style

The cursor shape to draw where the program in the pane has not asked for one: "block", "bar" or "underline". A program that asks for a shape (with CSI <n> q) still gets the shape it asked for.

Default: not set

cursor_style "bar"

cursor_blink

Whether the cursor blinks. Unlike cursor_style, this wins over the program: set it to force a blinking or a steady cursor whatever the pane asks for. When it is not set, the cursor blinks exactly when the program asks for a blinking cursor.

Default: not set

cursor_blink false

cursor_unfocused_hollow

Whether the cursor is drawn as an outlined block while the window is not focused.

Default: true

cursor_unfocused_hollow false

Keys

Keys are written as in keybindings, eg. "Ctrl Shift v". Each of these keys takes a list of keys. The window keeps the keys it lists for itself; any other key goes to the session. Listing no keys leaves them all to the session. On macOS, Super is the Command key.

paste_keys

The keys that paste from the clipboard.

Default: "Ctrl Shift v" and "Shift Insert", plus "Super v" on macOS

paste_keys "Ctrl Shift v" "Shift Insert"

copy_keys

The keys that copy the text marked with shift and drag (see shift_drag_selects).

Default: "Ctrl Shift c", plus "Super c" on macOS

copy_keys "Ctrl Shift c"

fullscreen_keys

The keys that switch the window between fullscreen and the size it had before.

Default: "F11"

fullscreen_keys "F11"

zoom_in_keys, zoom_out_keys and zoom_reset_keys

The keys that make text larger, make it smaller, and return it to the configured font_size.

Defaults:

• zoom_in_keys: "Ctrl =", "Ctrl +" and "Ctrl Shift +", plus "Super =", "Super +" and "Super Shift +" on macOS
• zoom_out_keys: "Ctrl -" and "Ctrl Shift _", plus "Super -" on macOS
• zoom_reset_keys: "Ctrl 0", plus "Super 0" on macOS

zoom_in_keys "Ctrl ="
zoom_out_keys "Ctrl -"
zoom_reset_keys "Ctrl 0"

macos_option_as_alt

Which Option key acts as Alt on macOS. The other one keeps typing characters such as å. Ignored on other platforms.

Options:

• "left" (default)
• "right"
• "both"
• "none"

macos_option_as_alt "both"

Mouse and scrolling

middle_click_paste

Whether the middle mouse button pastes the primary selection (on Linux, the text last selected anywhere). A pane whose program asks for mouse reporting gets the click instead.

Default: true

middle_click_paste false

open_links

Whether clicking an OSC 8 hyperlink opens it with the system's default handler. A plain left click opens it; over a pane whose program asks for mouse reporting, shift must be held instead. Dragging is a selection and never opens anything, and the click still reaches the pane either way. Only http, https, ftp, ftps, mailto and file links are opened.

Default: true

open_links false

open_links_with_shift

Whether shift and click opens a link in every pane, not only in panes whose program asks for mouse reporting. Has no effect when open_links is false.

Default: true

open_links_with_shift false

shift_drag_selects

Whether dragging with shift held marks text anywhere in the window, including the tab bar, the status bar, pane frames and across pane borders. The marked text is copied with copy_keys.

Default: true

shift_drag_selects false

hide_pointer_while_typing

Whether the mouse pointer is hidden while typing, until it moves again.

Default: false

hide_pointer_while_typing true

smooth_scrolling

Whether scrolling through a pane's scrollback slides the text to its new position instead of jumping. This applies to the mouse wheel, the touchpad and the scroll keys alike.

Default: true

smooth_scrolling false

scroll_animation_duration

How long one scroll slide takes, in milliseconds, from 1 to 1000. Ignored when smooth_scrolling is false.

Default: 100

scroll_animation_duration 150

scroll_momentum

Whether a fast two-finger touchpad swipe through a pane's scrollback keeps scrolling for a moment after the fingers lift, slowing down until it stops. Touching the touchpad again, clicking, typing or moving the pointer to another pane stops it at once. This works independently of smooth_scrolling. It currently only has an effect on Wayland; on X11, Windows and macOS it is ignored (macOS already provides its own touchpad momentum).

Default: true

scroll_momentum false

scroll_momentum_friction

How quickly that continued scrolling slows down, from 0.5 to 10.0. Higher values stop sooner. Currently only has an effect on Wayland.

Default: 2.0

scroll_momentum_friction 4.0

Window

opacity

How opaque the window is, from 0.0 (invisible) to 1.0 (solid). This needs a compositor; without one, the window stays solid.

Default: 1.0

opacity 0.9

opacity_mode

What the opacity applies to:

• "background" (default) - only the default background shows through; text, colored cells, the cursor and images stay solid
• "everything" - the whole window fades evenly

opacity_mode "everything"

blur

Whether to ask the compositor to blur what is behind the window. It is only visible with an opacity below 1.0. It is supported on macOS, KDE Plasma and Windows 11 22H2 or later, and ignored elsewhere. On Windows it is the system's Acrylic material, which only shows while the window is focused.

Default: false

blur true

startup_mode

How a new window opens. Requires restart. The --startup-mode flag of zellij terminal overrides it.

Options:

• "remember" (default) - at the size (counted in rows and columns) and in the state the last window was closed in; with nothing remembered yet, it opens windowed at 120x40
• "windowed"
• "maximized"
• "fullscreen"

startup_mode "maximized"

initial_columns and initial_rows

The size, in columns and rows, of a window that has no remembered size to open at, each from 2 to 1000. A size remembered by startup_mode "remember" wins over these. A maximized or fullscreen window returns to this size when it is restored. Requires restart.

Default: 120 columns and 40 rows

initial_columns 160
initial_rows 48

reuse_session_windows

Whether a session is shown in at most one window of the desktop app. When on, switching a window to a session that another window already shows brings that other window forward and closes the switching one; the session it left keeps running. When off, the window always switches in place. Windows opened with zellij terminal --standalone always switch in place.

Default: true

reuse_session_windows false

terminal_requests

Where a command opens when another program uses Zellij as its terminal (zellij terminal -e <command>, as xdg-terminal-exec or a file manager runs it):

• "new_session" (default) - in a session of its own
• "existing_session" - as a new tab in the session whose window was focused last, or in a new session when no window is open

terminal_requests "existing_session"

bell

What the window does when a program rings the bell:

• "visual" (default) - asks the desktop to draw attention to the window, eg. by highlighting it in the taskbar
• "audible" - plays the system sound
• "both"
• "none"

bell "both"

Clipboard

allow_remote_clipboard_read

Whether programs in a session on another machine (opened with zellij terminal https://..., see remote attach) may read this computer's clipboard with OSC 52. Local sessions follow dangerously_enable_paste_buffer_read instead.

Default: false

allow_remote_clipboard_read true

Colors

theme

The colors the window paints itself:

terminal {
    theme {
        foreground "#e5e5e5"
        background "#000000"
        cursor "#e5e5e5"
        black "#000000"
        red "#cd0000"
        green "#00cd00"
        yellow "#cdcd00"
        blue "#0000ee"
        magenta "#cd00cd"
        cyan "#00cdcd"
        white "#e5e5e5"
        bright_black "#7f7f7f"
        bright_red "#ff0000"
        bright_green "#00ff00"
        bright_yellow "#ffff00"
        bright_blue "#5c5cff"
        bright_magenta "#ff00ff"
        bright_cyan "#00ffff"
        bright_white "#ffffff"
    }
}

Every color is optional, and is given as RGB (eg. 229 229 229) or as a hex string. The sixteen ANSI colors (black to bright_white) cannot be given as a number from the 256-color palette, because that palette is built from them.

Where the colors come from, from lowest to highest priority:

• foreground and background: the text_unselected colors of the active Zellij theme (following dark and light switching), then this block.
• The sixteen ANSI colors: the terminal_colors section of the active Zellij theme, then this block. Colors that neither of them sets keep the usual xterm defaults (eg. red is 205 0 0).
• cursor: only this block.

So with no theme block here, the window follows the Zellij theme, including its terminal_colors. Colors set in this block stay the same whatever Zellij theme is active.

Commands

These commands can be invoked with zellij [SUBCOMMAND]. For more details, each subcommand has its own help section when run with the --help flag (zellij [SUBCOMMAND] --help).

attach [session-name]

short: a

Zellij will attempt to attach to an already running session, with the name [session-name]. If given no [session-name] and there is only one running session, it will attach to that session.

The attach subcommand will also accept the optional options subcommand.

Starting a session with an initial command

Trailing arguments given after -- are run as a command in the first pane of the session:

$ zellij attach -c my-session -- htop

This works both when creating a session in the foreground (-c, --create) and in the background (-b, --create-background).

The command only runs if the session is created by this invocation. When attaching to an already running session, the trailing command is ignored.

If a layout is used, the pane running the command is placed in the focused tab.

Two flags change how the initial command behaves. Both require an initial command to be given:

Initial commands are not supported for remote (web client) sessions - the CLI will error out.

All the arguments of attach described here also work with zellij terminal.

terminal [session-name]

zellij terminal opens a session in Zellij's own terminal window, without another terminal emulator. It takes the same arguments as attach (eg. zellij terminal -c my-session -- htop), and adds flags for the window and the desktop app (eg. --watch, --startup-mode, --standalone, -e <COMMAND>, --hold, --working-directory, --inbox and --sessions).

$ zellij terminal
$ zellij terminal -c my-session
$ zellij terminal -e htop

See Zellij Terminal for the full reference.

Running zellij with no arguments outside of a terminal (eg. by double-clicking it) opens zellij terminal on macOS, and on Linux when a desktop is available (DISPLAY or WAYLAND_DISPLAY is set). This does not happen over SSH or on Windows.

prompt

zellij prompt shows a question, list, text field or notice as a popup over the calling pane and prints the answer.

$ zellij prompt confirm "Force push?" && git push --force

See Zellij Prompt for the full reference.

list-sessions

short: ls

Will list all the names of currently running sessions.

kill-session [target-session]

short: k

Will kill the session with the name of [target-session], if it is currently running.

kill-all-sessions

short: ka

Will prompt the user to kill all running sessions. -y, --yes skips the prompt.

delete-session [target-session]

short: d

Will delete the exited (resurrectable) session with the name of [target-session]. With -f, --force, a running session is killed first.

delete-all-sessions

short: da

Will prompt the user to delete all exited (resurrectable) sessions. With -f, --force, running sessions are killed and deleted as well. -y, --yes skips the prompt.

watch [session-name]

short: w

Will attach to a session in read-only mode. See Zellij Watch.

list-aliases

short: la

Will list the existing plugin aliases.

run, edit, plugin, pipe, action and subscribe

These commands control a running session from the command line. They are described in Controlling Zellij through the CLI: run and edit (short: r and e), plugin and pipe (short for plugin: p), action (short: ac) and subscribe.

web

Runs and manages the web server. See Web Client.

options

Can be used to change the behaviour of zellij on startup. Will supercede options defined in the config file. To see a list of options look here.

setup

Functionality to help with the setup of zellij.

setup can also do from the command line what the setup screen does:

These flags can be combined with each other, but not with the flags of the first table.

$ zellij setup --copy-to-permanent-folder
$ zellij setup --install-desktop-entry --make-default-terminal
$ zellij setup --keybinding-preset unlock-first

See Desktop Setup for where each item is installed on each platform.

Flags

These flags can be invoked with zellij --flag.

--layout-string

Takes a layout as a raw KDL string rather than as a path to a layout file. Useful for scripting and for generating layouts on the fly.

If invoked from inside a Zellij session (or with an explicit --session), the layout is added to the running session as new tab(s). Otherwise, a new session is started with it.

This flag conflicts with --layout and --new-session-with-layout.

$ zellij --layout-string 'layout { pane split_direction="vertical" { pane; pane; } }'

The layout is parsed and validated before being sent to the session, so syntax errors are reported immediately.

Rebinding Keys

Zellij places great emphasis on being a keyboard-first application. As such, Zellij uses many different shortcuts in order to give users the power to control the application and do so in a way that would make sense to them - not forcing them to learn many obtuse keyboard shortcuts that make little sense and are difficult to remember.

For some users, these shortcuts may "collide" with other shortcuts they use in the terminal in other programs. For these users, Zellij offers several solutions.

1. Using a "non-colliding" keybinding preset, or writing a preset of one's own
2. Changing the modifier keys Zellij uses for keybindings to ones that do not collide
3. Reconfiguring keybindings entirely as part of the configuration file

Mouse clicks and scrolling can be rebound as well, in the mousebinds block. See Mouse Bindings.

Keybinding Presets

Keybinding Presets are a set of keybindings that can be used to control Zellij. Zellij comes with two such presets out of the box, intended to fit different kinds of users. They are described below.

A preset is a file. It holds a full set of keybindings and mouse bindings, written with placeholders for the leader keys (see Leader keys). Besides the two built-in presets, presets can be written by hand and kept in the keybinds folder.

The default preset

This preset should fit most users of Zellij. In it, all modes are accessible from the basic "normal" mode in which the user spends most of their time. One can enter Pane mode by pressing Ctrl p and then have access to all commands inside pane mode (eg. n to open a new pane or x to close the focused pane).

Its name is default. Its full contents can be printed with zellij setup --dump-keybinds default.

The Unlock-First (non-colliding) preset

This preset is tailored to users who use terminal applications with keyboard shortcuts that collide with Zellij's own keybindings. In this preset, users "unlock" the interface before accessing the various input modes. The modes themselves can then be accessed with a single character shortcut.

So for example, in order to open a new pane, the user would press: Ctrl g followed by p followed by n. The Zellij maintainers found that after a short adjustment period, this is a fast, efficient and most importantly mentally-consistent way of interacting with the application.

Its name is unlock-first. Zellij starts in locked mode with this preset, unless the default_mode option is set. Its full contents can be printed with zellij setup --dump-keybinds unlock-first.

How to choose a preset?

In the configuration file

The preset is chosen with the preset attribute of the keybinds block:

keybinds preset="unlock-first" {
}

The value is one of:

• the name of a built-in preset (default or unlock-first)
• the name of a preset file in the keybinds folder, without the .kdl extension
• a path to a preset file (a relative path is taken from the folder of the configuration file)

Without a preset attribute, the default preset is used.

Bindings inside the keybinds block are applied on top of the preset (see Binding and Overriding Keys). To replace the preset completely, add clear-defaults=true to the block.

If the preset cannot be loaded (eg. the file is missing, a leader key is empty, or the primary and secondary leader keys are the same), Zellij warns and uses the default preset instead.

In the settings screen

The preset and its leader keys can also be chosen in the settings screen, under Keyboard → Key bindings and preset…. The settings screen is accessible with:

• Ctrl o + c in the default preset
• Ctrl g + o + c in the Unlock-First preset

The change can be applied just for the current session, or saved to the configuration file. From the same screen, a preset can be copied into the keybinds folder, and the current keybindings can be saved as a new preset there.

Choosing between the two built-in presets is also offered on the setup screen shown on the first run of Zellij.

From the command line

To save a preset to the configuration file (creating the file if needed):

zellij setup --keybinding-preset unlock-first

To use a preset for a single session, without changing the configuration file:

zellij options --keybinds-preset unlock-first --keybinds-unlock "Ctrl a"

The flags are:

• --keybinds-preset - a preset name or a path to a preset file
• --keybinds-primary - the primary leader key (eg. "Ctrl")
• --keybinds-secondary - the secondary leader key (eg. "Alt")
• --keybinds-unlock - the unlock key (eg. "Ctrl g")

When a preset is given with --keybinds-preset, a keybinds clear-defaults=true block in the configuration file is ignored, so that the chosen preset is used as it is. A keybinds block without clear-defaults=true is still applied on top of it.

To print a preset (built-in, or from the keybinds folder):

zellij setup --dump-keybinds default

Leader keys

Presets are written with three placeholders, which are filled in with the leader keys:

They are set with attributes of the keybinds block:

keybinds preset="default" primary="Ctrl Alt" secondary="Alt" {
}

keybinds preset="unlock-first" unlock="Ctrl a" {
}

The primary and secondary values must be different. The leader keys also change the mouse bindings of the preset.

The keybinds folder

Preset files are looked for in the keybinds folder inside the configuration folder (eg. ~/.config/zellij/keybinds/my-preset.kdl is used with preset="my-preset"). A different folder can be set with the keybinds_dir option:

keybinds_dir "/path/to/my/keybinds_dir"

Preset names may contain letters, digits, - and _.

Writing a preset

A preset file has an optional preset block describing it, a keybinds block, and an optional mousebinds block:

preset {
    name "My preset"
    description "All modes available directly from the base mode, eg.:"
    example "{primary} p" "to enter PANE mode"
    example "{primary} t" "to enter TAB mode"
    default_mode "normal"
    defaults {
        primary "Ctrl"
        secondary "Alt"
    }
}
keybinds {
    locked {
        bind "{primary} g" { SwitchToMode "Normal"; }
    }
    shared_except "locked" {
        bind "{primary} g" { SwitchToMode "Locked"; }
        bind "{secondary} n" { NewPane; }
    }
}
mousebinds {
    shared {
        bind "Left" { Click; }
        bind "ScrollUp" { Scroll 3; }
        bind "ScrollDown" { Scroll 3; }
    }
}

• name, description and example (the keys, then what they do) are shown when choosing a preset.
• default_mode is the mode Zellij starts in with this preset, unless the default_mode option is set.
• defaults gives the value of each placeholder used, when the user does not set one.
• Only {primary}, {secondary} and {unlock} can be used, and only in the keys of bind and unbind. Any other placeholder is an error.
• The keybinds block uses the same syntax as in the configuration file (see Keybindings).
• Without a mousebinds block, the mouse bindings of the default preset are used (see Mouse Bindings).

A good starting point is a built-in preset: zellij setup --dump-keybinds default > ~/.config/zellij/keybinds/my-preset.kdl.

More default keys

These keys are in both built-in presets. In unlock-first, the actions return to locked mode instead of normal mode, and modes are entered without Ctrl (eg. Ctrl g + p instead of Ctrl p).

Changing Modifiers

Zellij uses two different modifiers to distinguish between two main sets of actions.

The Primary Modifier (default: Ctrl)

This modifier is used to access the different modes (eg. Pane and Tab). Its exact usage depends on one's preset.

The Secondary Modifier (default: Alt)

This modifier is used for common shortcuts (eg. Alt n to open a new pane or Alt f to toggle floating panes).

The modifiers also apply to the mouse bindings of the preset. With the primary modifier held, dragging a pane frame resizes the pane, dragging inside a pane draws a new floating pane, and scrolling resizes the pane. With the secondary modifier held, clicking adds a pane to or removes it from the pane group, and scrolling jumps between shell prompts.

Rebinding Modifiers

Other than manually configuring keybindings, modifiers can be changed without overriding the current keybindings, with the primary and secondary attributes of the keybinds block:

keybinds primary="Ctrl Alt" secondary="Alt" {
}

The two values must be different. For the Unlock-First preset, the unlock attribute changes the key that unlocks the interface (the Unlock Toggle) entirely:

keybinds preset="unlock-first" unlock="Ctrl a" {
}

The same can be done in the settings screen, under Keyboard → Key bindings and preset…, accessible with:

• Ctrl o + c in the default preset
• Ctrl g + o + c in the Unlock-First preset

For a single session, the --keybinds-primary, --keybinds-secondary and --keybinds-unlock flags of zellij options do the same without changing the configuration file. See Keybinding Presets.

A note about multiple modifiers

While it's certainly possible to change these modifiers to Ctrl Alt, Super or even Ctrl Shift Alt - these all require the usage of a terminal emulator which itself supports multiple modifiers. Examples include: Alacritty, WezTerm and foot.

Terminals do not report Super for mouse events. If a modifier is set to Super, the mouse bindings that use it are skipped.

Configuration

Zellij uses KDL as its configuration language.

Quickstart:

mkdir ~/.config/zellij
zellij setup --dump-config > ~/.config/zellij/config.kdl

Note: In most cases, Zellij will create the above file automatically on first run. Be sure to check if it exists first.

Where does Zellij look for the config file?

By default Zellij will look for config.kdl in the config directory.

Zellij will search for the config directory as follows:

• --config-dir flag

• ZELLIJ_CONFIG_DIR env variable

• $HOME/.config/zellij

• default location

  • Linux: /home/alice/.config/zellij
  • Mac: /Users/Alice/Library/Application Support/org.Zellij-Contributors.Zellij

• system location (/etc/zellij)

How to bypass the config file?

In order to pass a config file directly to zellij:

zellij --config [FILE]

or use the ZELLIJ_CONFIG_FILE environment variable.

To start without loading configuration from default directories:

zellij options --clean

How do I update the config file for running sessions?

Zellij actively watches for changes in the active configuration file. Most fields will be applied immediately without the need for a restart. Otherwise, this will be mentioned in the commentary of the relevant field.

The themes folder, the keybindings folder and the layouts folder are watched as well.

Changing the configuration from the settings screen

Most of the configuration can also be changed from the settings screen (Ctrl o + c with the default keybinding preset, or "Settings…" in the right-click menu). Changes apply right away, and stay unsaved until they are saved to the configuration file.

When saving, Zellij changes only the affected parts of the file and keeps its comments and formatting. The previous version of the file is copied next to it as config.kdl.bak, replacing any earlier backup with that name.

What can be configured?

The configuration file is made of options set at its root, and of blocks:

Settings Screen

Zellij includes a settings screen that changes its behavior and appearance without editing the configuration file by hand. The settings screen reads the configuration file and writes its changes back to it, so both can be used side by side.

Opening the settings screen

• Ctrl o + c in the default preset (Ctrl g + o + c in the Unlock-First preset)
• "Settings…" in the right-click menu
• Loading the configuration alias, optionally at a specific page

Categories

The settings are grouped in these categories:

• General
• Appearance - with the Themes and Pane borders pages
• Keyboard - with the Key bindings page, where the keybinding preset and its leader keys are chosen
• Mouse - with the Mouse bindings and Right-click menu pages
• Clipboard and selection
• Panes and layouts
• Attention - see Inbox & Attention
• Notifications
• Sessions
• Zellij terminal - settings that only apply in the Zellij terminal, see Terminal Options
• Web - see Web Client
• Advanced - with the Plugins and environment page (plugin aliases, plugins loaded at start, environment variables and plugin settings)

Below the selected setting, the screen shows its description, its default, whether it applies only to you or to everyone in the session, and whether it takes effect only after a restart.

Keys

Saving

A change applies to the running session right away. Ctrl a writes all unsaved changes to the configuration file. Changes that are not saved stay applied to the session until it ends.

When writing, Zellij keeps the comments and the formatting of the configuration file. If the file was changed outside the settings screen in the meantime, Zellij asks whether to overwrite it with the unsaved changes or to read it again and keep the changes unsaved.

Some items are shown but cannot be edited:

• Built-in themes and themes from theme_dir (copy one to edit it)
• Keybindings that come from a layout

Without a configuration file, the settings screen still changes the session but cannot save.

Plugin settings

Plugins can add their own entry to the "Plugin settings" section of the Plugins and environment page. Selecting it opens that plugin's own settings.

Options

Configuration options can be set directly at the root of the configuration file

These include:

• on_force_close
• simplified_ui
• default_shell
• pane_frames
• theme
• theme_dark
• theme_light
• default_layout
• default_mode
• mouse_mode
• scroll_buffer_size
• copy_command
• copy_clipboard
• copy_on_select
• scrollback_editor
• mirror_session
• layout_dir
• theme_dir
• env
• rounded_corners
• hide_session_name
• border_style
• auto_layout
• styled_underlines
• session_serialization
• serialize_pane_viewport
• scrollback_lines_to_serialize
• serialization_interval
• disable_session_metadata
• stacked_resize
• show_startup_tips
• show_release_notes
• post_command_discovery_hook
• web_server
• web_server_ip
• web_server_port
• web_server_cert
• web_server_key
• enforce_https_for_localhost
• dangerously_allow_web_serving_without_a_certificate
• base_url
• web_client
• client_async_worker_tasks
• advanced_mouse_actions
• default_cwd
• osc8_hyperlinks
• session_name
• attach_to_session
• support_kitty_keyboard_protocol
• web_sharing
• mouse_hover_effects
• visual_bell
• focus_follows_mouse
• mouse_click_through
• pane_frame_style
• stacked_pane_list
• support_kitty_graphics_protocol
• mouse_scroll_resize
• mouse_hover_tips
• osc133_command_selection
• word_separators
• host_notification_protocol
• nested_session_handling
• dangerously_enable_paste_buffer_read
• scroll_mode_sync
• explicit_theme_hue
• on_quit
• bars_hidden_on_start
• hidden_bars_notification
• mode_hints_when_bars_hidden
• session_indicator
• swap_layout_notification
• stacked_pane_list_orientation
• grapheme_clusters
• mirror_resizes_source_pane
• live_view_release_key
• keybinds_dir
• context_menu_enabled
• context_menu
• session_suggestions
• terminal
• attention

on_force_close

Choose what to do when zellij receives SIGTERM, SIGINT, SIGQUIT or SIGHUP eg. when terminal window with an active zellij session is closed. This also applies to closing a window of the Zellij terminal.

Options:

• detach (Default)
• quit

on_force_close "quit"

simplified_ui

Send a request for a simplified ui (without arrow fonts) to plugins

Options:

• true
• false (Default)

simplified_ui true

default_shell

Choose the path to the default shell that zellij will use for opening new panes

Default: $SHELL

default_shell "fish"

pane_frames

Toggle between having pane frames around the panes. The style of these frames is controlled by pane_frame_style - since 0.45.0 the default style is a single title line above each pane rather than a full border.

Options:

• true (default)
• false

pane_frames true

theme

Choose the Zellij color theme. This theme must be specified in the themes section or loaded from the themes folder. See themes

Setting theme pins the session to this theme and turns off the automatic switching between the bundled default and default-light themes. Switching still happens if both theme_dark and theme_light are also set.

Since 0.46.0, the default theme has a new palette. The previous default theme is bundled as classic.

Default: default

theme "default"

theme_dark

Name of the theme to use as the "dark" theme. Used by the SetDarkTheme / ToggleTheme actions, and applied automatically when the host terminal reports it is in dark mode (CSI 2031 / DSR 997). The named theme must be specified in the themes section or loaded from the themes folder. See themes

Default: default when theme is not set, otherwise unset

theme_dark "catppuccin-mocha"

theme_light

Name of the theme to use as the "light" theme. Used by the SetLightTheme / ToggleTheme actions, and applied automatically when the host terminal reports it is in light mode (CSI 2031 / DSR 997). The named theme must be specified in the themes section or loaded from the themes folder. See themes

Default: default-light when theme is not set, otherwise unset

theme_light "catppuccin-latte"

default_layout

The name of the layout to load on startup (must be in the layouts folder). See layouts

Default: "default"

default_layout "compact"

default_mode "locked"

Choose the mode that zellij uses when starting up and returns to after actions.

Default: normal

default_mode "locked"

mouse_mode

Toggle enabling the mouse mode. On certain configurations, or terminals this could potentially interfere with copying text.

Options:

• true (default)
• false

mouse_mode false

scroll_buffer_size

Configure the scroll back buffer size This is the number of display rows zellij stores for each pane in the scroll back buffer. A line wider than the pane takes one row for each time it wraps. Excess rows are discarded in a FIFO fashion.

Valid values: positive integers

Default value: 10000

scroll_buffer_size 10000

copy_command

Provide a command to execute when copying text. The text will be piped to the stdin of the program to perform the copy. This can be used with terminal emulators which do not support the OSC 52 ANSI control sequence that will be used by default if this option is not set.

Examples, for X11, Wayland and macOS:

copy_command "xclip -selection clipboard"
copy_command "wl-copy"
copy_command "pbcopy"

copy_clipboard

Choose the destination for copied text Allows using the primary selection buffer (on x11/wayland) instead of the system clipboard. Does not apply when using copy_command.

Options:

• system (default)
• primary

copy_clipboard "primary"

copy_on_select

Enable or disable automatic copy of selection when releasing mouse

Default: true

copy_on_select false

scrollback_editor

Path to the default editor to use to edit pane scrollbuffer as well as the CLI and layout edit commands

Default: $EDITOR or $VISUAL

scrollback_editor "/usr/bin/vim"

mirror_session

When attaching to an existing session with other users, should the session be mirrored (true) or should each user have their own cursor (false) Default: false

mirror_session true

Note: since 0.45.0, each tab is sized according to the viewports of only the clients currently viewing it. Clients focused on different tabs therefore no longer constrain each other, while clients viewing the same tab converge on a common size. Tabs that nobody is viewing keep their last dimensions. This behavior is not configurable.

layout_dir

The folder in which Zellij will look for layouts

layout_dir "/path/to/my/layout_dir"

theme_dir

The folder in which Zellij will look for themes. Themes from this folder are read-only in the settings screen (copy one to edit it).

theme_dir "/path/to/my/theme_dir"

env

A key -> value map of environment variables that will be set for each terminal pane Zellij starts.

env {
    RUST_BACKTRACE 1
    FOO "bar"
}

rounded_corners

Set whether the pane frames (if visible) should have rounded corners.

This config variable is set differently than others:

ui {
    pane_frames {
        rounded_corners true
    }
}

hide_session_name

Hides the session name (randomly generated or otherwise) from the UI

ui {
    pane_frames {
        hide_session_name true
    }
}

border_style

The line style of pane borders can be set, for all sides at once or for each side. Like rounded_corners, these keys go inside the ui block:

ui {
    pane_frames {
        rounded_corners true
        border_style "single"
        border_top "double"
        border_right "single"
        border_bottom "single"
        border_left "single"
        border_rounded_corners true
        floating_border_style "double"
        floating_border_top "double"
        floating_border_right "double"
        floating_border_bottom "double"
        floating_border_left "double"
        floating_border_rounded_corners false
    }
}

Line styles:

• "single" (default)
• "double"
• "heavy"
• "dashed"
• "heavy_dashed"

How the keys combine:

• border_style sets all four sides of tiled panes. border_top, border_right, border_bottom and border_left override one side each.
• border_rounded_corners overrides rounded_corners for tiled panes. Corners are only rounded where two thin lines (single or dashed) meet.
• The keys starting with floating_ do the same for floating panes. Any of them that is not set takes the value of the matching tiled pane key.
• When pane frames are off and two neighboring panes ask for different styles on the line they share, that line uses border_style.

These can also be changed from the settings screen.

auto_layout

Toggle between having Zellij lay out panes according to a predefined set of layouts whenever possible Options:

• true (default)
• false

auto_layout true

styled_underlines

Toggle between supporting the extended "styled_underlines" ANSI protocol and ignoring it (can sometimes cause some issues in unsupported terminals). Options:

• true (default)
• false

styled_underlines true

session_serialization

If enabled, sessions will be serialized to the cache folder (and thus become resurrectable between reboots or on exit). Read more about session resurrection. Options:

• true (default)
• false

session_serialization true

serialize_pane_viewport

If enabled along with session_serialization, the pane viewport (the visible part of the terminal excluding the scrollback) will be serialized and resurrectable as well. Read more about session resurrection. Options:

• true
• false (default)

serialize_pane_viewport true

scrollback_lines_to_serialize

When serialize_pane_viewport is enabled, setting scrollback_lines_to_serialize to 0 will serialize all scrollback and to any other number will serialize line number up to that scrollback. Read more about session resurrection.

Note: this might incur higher resource utilization (and certainly a higher cache folder usage...)

Options:

• 0: serialize all scrollback
• int: serialize this much lines for each pane (max is the scrollback limit)

scrollback_lines_to_serialize 100

serialization_interval

How often in seconds sessions are serialized to disk (if session_serialization is enabled).

Note: this might incur higher resource utilization (and certainly a higher cache folder usage...)

Options:

• int: the interval in seconds

serialization_interval 60

disable_session_metadata

Enable or disable writing of session metadata to disk

Note: If disabled, other sessions might not know metadata info on this session, so features such as the session-manager and session listing might not work properly.

Options:

• true
• false (default)

disable_session_metadata true

stacked_resize

Attempt to stack panes with their neighbors when resizing non-directionally (by default Alt+/-).

Options:

• true (default)
• false

stacked_resize true

show_startup_tips

Show usage tips on Zellij startup. These can also be browsed through the about plugin with Ctrl o + a and then ?.

Options:

• true (default)
• false

show_startup_tips true

show_release_notes

Show release notes on first run of a new version. These can also be browsed through the about plugin with Ctrl o + a.

Options:

• true (default)
• false

show_release_notes true

post_command_discovery_hook

When Zellij attempts to discover commands running inside panes so that it can serialize them, it can sometimes be inaccurate. This can happen when (for example) commands are run inside some sort of wrapper. To get around this, it's possible to define a post_command_discovery_hook. This is a command that will run in the context of te user's default shell and be provided the $RESURRECT_COMMAND that has just been discovered for a specific pane and not yet serialized. Whatever this command sends over STDOUT will be serialized in place of the discovered command.

Example, removing sudo from the start of commands:

post_command_discovery_hook "echo \"$RESURRECT_COMMAND\" | sed 's/^sudo\\s\\+//'"

web_server

Whether to start the Zellij web-server on startup.

Options:

• true
• false (default)

web_server_ip

The IP for the Zellij web-server to listen on when it's started. Default: 127.0.0.1.

web_server_port

The port for the Zellij web-server to listen on when it's started. Default: 8082.

web_server_cert

The path to the SSL certificate for the Zellij web-server. Note: the web_server_key must also be present for the server to serve itself as HTTPS.

web_server_key

The path to the private_key of te SSL certificate for the Zellij web-server. Note: the web_server_cert must also be present for the server to serve itself as HTTPS.

enforce_https_for_localhost

Whether to enforce https on localhost for the Zellij web-server. HTTPS is always enforced when listening on non-localhost addresses, unless dangerously_allow_web_serving_without_a_certificate is set. Requires a restart.

Options:

• true
• false (default)

enforce_https_for_localhost true

dangerously_allow_web_serving_without_a_certificate

Allows the Zellij web-server to serve plain, unencrypted HTTP when it listens on an address other than localhost and no web_server_cert and web_server_key are set. Without this option, the web server refuses to start in that case.

Warning: anyone on the network can read and change the traffic, including login tokens. Only use this behind a trusted proxy that adds TLS, or on a fully trusted network.

This option does not override enforce_https_for_localhost. Requires a restart.

Options:

• true
• false (default)

dangerously_allow_web_serving_without_a_certificate true

base_url

Set the base URL path for the Zellij web-server. When set, the web server serves all content under this path prefix. This is useful when running behind a reverse proxy that serves Zellij under a subpath.

Default: none (served at root "/")

web_client {
    base_url "/zellij"
}

web_client

A block with settings for the in-browser terminal of the Zellij web client (eg. colors, font, font size, cursor). Changes require a restart. For the full list, please see: web-server.

web_client {
    font "monospace"
    font_size 14
}

client_async_worker_tasks

The number of background threads used by zellij attach <url> when it connects to a session on another machine. One set of threads is made for that program, not one per client. The web server, browser clients and local sessions are not affected. Most of the work runs on the main thread, so these threads are usually idle. Requires a restart.

Default: the number of physical CPU cores (also used when set to 0)

client_async_worker_tasks 4

advanced_mouse_actions

Whether to enable mouse hover effects and jumping between shell prompts with the mouse wheel (the ScrollToPrompt mouse binding, Alt + scroll by default). When false, those bindings do nothing.

The other mouse interactions are mouse bindings and can be rebound:

• Resizing panes by their frame: the ResizePane binding, on Ctrl + left-drag on the frame of any tiled or floating pane by default
• Drawing a new floating pane: the DrawFloatingPane binding, on Ctrl + left-drag inside a pane by default
• Resizing with the scroll wheel: the ResizeScroll binding, controlled by mouse_scroll_resize

Ctrl here is the preset's primary modifier, which can be changed (see Changing Modifiers).

Options: - true (default) - false

default_cwd

Set the default current working directory for new panes. When set, new panes will open in this directory unless otherwise specified.

default_cwd "/home/user/projects"

osc8_hyperlinks

Enable clickable OSC8 hyperlink output in terminal panes. When enabled, programs that emit OSC8 escape sequences will produce clickable hyperlinks. Requires a restart.

Options:

• true (default)
• false

osc8_hyperlinks false

session_name

Set the name of the session to create when starting Zellij. If not set, a random name will be generated.

session_name "my-session"

attach_to_session

If a session with the name specified in session_name already exists, attach to it instead of creating a new one.

Options:

• true
• false (default)

attach_to_session true

support_kitty_keyboard_protocol

Enable support for the Kitty keyboard protocol. This allows for more detailed key reporting from the terminal. Defaults to true if the terminal supports it.

Options:

• true (default if terminal supports it)
• false

support_kitty_keyboard_protocol true

web_sharing

Whether new sessions are shared through the local web server. This is separate from web_server which controls whether the server starts at all.

Options:

• "on" - new sessions are shared by default
• "off" - new sessions are not shared by default (Default)
• "disabled" - sharing is completely disabled

web_sharing "on"

mouse_hover_effects

Enable mouse hover visual effects, such as pane frame highlight and help text when hovering over panes.

Options:

• true (default)
• false

mouse_hover_effects false

visual_bell

Show visual bell indicators when a pane sends a bell character. This manifests as a brief pane/tab frame flash and a [!] suffix on the tab name.

Options:

• true (default)
• false

visual_bell false

focus_follows_mouse

Whether to automatically focus panes when hovering over them with the mouse.

Options:

• true
• false (default)

focus_follows_mouse true

mouse_click_through

Whether clicking a pane to focus it also sends the click event into the pane (to the running program). When false, the first click only focuses the pane and is consumed by Zellij.

Options:

• true
• false (default)

mouse_click_through true

pane_frame_style

The style of the pane frames when pane_frames is enabled.

Options:

• "titles" (default) - a single title line above each pane
• "full" - a full border around each pane (the pre-0.45.0 look)
• "none" - no frames at all (identical to pane_frames false)

Setting pane_frames false forces the style to none regardless of this option.

The style can also be changed at runtime with the SetPaneFrameStyle action or with zellij action set-pane-frame-style.

pane_frame_style "titles"

stacked_pane_list

Whether stacked panes are rendered as a list of one-line titles with the expanded pane pinned to the bottom of the stack. When false, the expanded pane is rendered in place inside the stack (the pre-0.45.0 behavior).

Options:

• true (default)
• false

stacked_pane_list false

support_kitty_graphics_protocol

Enable support for the Kitty graphics protocol, allowing programs running in panes to display images. Defaults to true if the terminal supports it (queried when Zellij starts). Changing this option requires restarting Zellij.

Options:

• true (default if terminal supports it)
• false

support_kitty_graphics_protocol true

mouse_scroll_resize

Whether holding the primary modifier (Ctrl by default) and scrolling the mouse wheel resizes the pane under the mouse. This is done by the ResizeScroll mouse binding, which can be rebound; when this option is false, that binding does nothing.

Options:

• true (default)
• false

mouse_scroll_resize false

mouse_hover_tips

Whether to show contextual help tips when hovering with the mouse (eg. resize help near pane borders, pane group shortcuts). This is distinct from mouse_hover_effects, which controls hover visual effects such as frame highlighting.

Options:

• true (default)
• false

mouse_hover_tips false

osc133_command_selection

Whether triple-clicking inside output marked with OSC 133 shell integration sequences selects the whole command and its output rather than the logical line under the cursor.

Options:

• true (default)
• false

osc133_command_selection false

word_separators

The characters that terminate a word when double-clicking to select it. Whitespace always separates words and does not need to be included here.

Default: "[]{}<>()"

word_separators "[]{}<>()/\\"

host_notification_protocol

The protocol used to forward desktop notifications emitted by panes (through OSC 9, OSC 99 or OSC 777) to the host terminal. See desktop notifications.

Options:

• "auto" (default) - OSC 99 for terminals that support it (eg. kitty), OSC 9 otherwise
• "osc9" - always use OSC 9
• "osc99" - always use OSC 99
• "bell" - emit a terminal bell instead of a notification
• "off" - do not forward notifications to the host terminal

host_notification_protocol "osc9"

nested_session_handling

What Zellij should do when a pane contains another (nested) Zellij session. See nested sessions.

Options:

• "ask" (default) - show a prompt when focusing the pane, offering to zoom into the nested session or to take control of it
• "fullscreen" - always zoom into the nested session when focusing its pane
• "descend" - always route input to the nested session when focusing its pane
• "never" - do nothing automatically

nested_session_handling "descend"

dangerously_enable_paste_buffer_read

Whether programs running inside panes are allowed to read the system clipboard through the OSC 52 escape sequence. When false, such requests receive an empty reply.

Warning: when this is enabled, any program running in any pane - including one running on a remote machine over SSH - can read the contents of the clipboard at any time, without prompting.

Copying to the clipboard (OSC 52 write) is not affected by this option and is always available.

Options:

• true
• false (default)

dangerously_enable_paste_buffer_read true

scroll_mode_sync

Whether scrolling a pane implicitly enters and exits scroll mode. When false, scrolling a pane (eg. with the mouse wheel) leaves the current mode alone, and scroll mode is only entered through an explicit keybinding.

Options:

• true (default)
• false

scroll_mode_sync false

explicit_theme_hue

Pin the session to a dark or light appearance, ignoring the color scheme reported by the host terminal. It is resolved before the first render, so the session starts with the intended appearance rather than correcting itself once the terminal replies. See themes.

Options:

• "dark" - always treat the terminal as being in dark mode
• "light" - always treat the terminal as being in light mode

Default: unset - the host terminal decides

This only selects which dark or light theme applies. When theme is not set, these are theme_dark and theme_light, or the bundled default and default-light themes in their place. When theme is set, both theme_dark and theme_light must be set for this option to have an effect - otherwise theme remains authoritative.

explicit_theme_hue "dark"

on_quit

Choose what the Quit action (Ctrl q by default) does.

Options:

• "ask_quit" (default) - ask, with quitting preselected
• "ask_detach" - ask, with detaching preselected
• "quit" - quit without asking
• "detach" - detach without asking; the session keeps running

on_quit "ask_detach"

bars_hidden_on_start

The bars (eg. the tab bar and status bar) a new session starts with hidden. Hidden bars come back with the "Show bars" item of the right-click menu or the ToggleBars action.

Options:

• "none" (default) - no bars are hidden
• "all" - all bars are hidden
• bar names separated by commas, eg. "tab-bar,status-bar"

A bar is matched by its plugin alias (eg. tab-bar, status-bar, compact-bar) or by its plugin location.

bars_hidden_on_start "all"

hidden_bars_notification

Whether to briefly show a note saying what was hidden and how to show it again whenever bars are hidden.

Options:

• true (default)
• false

hidden_bars_notification false

mode_hints_when_bars_hidden

While the bar that shows the keys of the current mode is hidden, whether to show those keys in a corner of the screen when entering a mode.

Options:

• true (default)
• false

mode_hints_when_bars_hidden false

session_indicator

Whether to show the other sessions indicator in the tab bar and the compact bar.

Options:

• true (default)
• false

session_indicator false

swap_layout_notification

Whether to briefly show the name of the new swap layout when it is changed.

Options:

• true (default)
• false

swap_layout_notification false

stacked_pane_list_orientation

Whether new stacks show their pane titles in a column (one title per line) or in a row (side by side on one line). The orientation of an existing stack can be changed from its right-click menu.

Options:

• "vertical" (default)
• "horizontal"

stacked_pane_list_orientation "horizontal"

grapheme_clusters

Whether to count each grapheme cluster (an emoji sequence such as a flag or a skin tone, or a letter with its accents) as one unit of width, as the Unicode standard does. When false, width is counted per code point, the way older programs expect, and programs can still ask for clusters with mode 2027. Applies to new panes.

Options:

• true (default)
• false

grapheme_clusters false

mirror_resizes_source_pane

Whether a focused mirror of a pane (a live copy of the pane shown elsewhere) in this session may resize that pane's program to the mirror's size, and whether new mirrors opened in this session do so by default.

Options:

• true (default)
• false

mirror_resizes_source_pane false

live_view_release_key

An extra key that stops typing into a live view of a pane (in the inbox or a mirror) and gives the keys back to the plugin showing it. Alt Enter, the inbox key or a click outside always do this. A key written twice, eg. "Esc Esc", must be pressed twice in a row.

Default: not set

live_view_release_key "Ctrl Alt Home"

keybinds_dir

The folder in which Zellij looks for keybinding presets. Changes to files in this folder are picked up live.

Default: a keybinds folder in the config directory

keybinds_dir "/path/to/my/keybinds_dir"

context_menu_enabled

Whether a right click opens the right-click menu. When false, right clicks go to the focused pane only, and Alt + right click clears the pane group. Plugins can still open the menu through their API.

Options:

• true (default)
• false

context_menu_enabled false

context_menu

A block that sets the items of the right-click menu. See the right-click menu.

session_suggestions

A block that sets how other sessions are suggested on the session card and in the session manager. See session suggestions.

terminal

A block with the settings of the Zellij terminal window (zellij terminal), eg. its font, padding and opacity. See terminal options.

attention

A block that sets how Zellij tracks and shows what panes, tabs and sessions need: the markers on frames and tabs, the inbox, and the desktop app's tray icon and notifications. See the inbox.

Configuring Keybindings

Zellij comes with a default set of keybindings that try to fit as many different users and use cases while trying to maximize comfort for everyone.

The keybindings come from a keybinding preset: a file that holds a full set of keybindings (and mouse bindings). Zellij has two built-in presets, default and unlock-first. The preset to use, and its leader keys, are chosen with attributes of the keybinds block.

It is possible to add to the keys of the preset or even override them with an external configuration. For more information about the configuration file itself, see Configuration.

Keybindings can be configured in the keybinds block of the file. Bindings inside the block are applied on top of the preset.

See the default preset as reference for the default keybindings, or print it with zellij setup --dump-keybinds default.

keybinds preset="default" primary="Ctrl" secondary="Alt" {
    normal {
        bind "Ctrl g" { SwitchToMode "locked"; }
        bind "Ctrl p" { SwitchToMode "pane"; }
        bind "Alt n" { NewPane; }
        bind "Alt h" "Alt Left" { MoveFocusOrTab "Left"; }
    }
    pane {
        bind "h" "Left" { MoveFocus "Left"; }
        bind "l" "Right" { MoveFocus "Right"; }
        bind "j" "Down" { MoveFocus "Down"; }
        bind "k" "Up" { MoveFocus "Up"; }
        bind "p" { SwitchFocus; }
    }
    locked {
        bind "Ctrl g" { SwitchToMode "normal"; }
    }
}

Keybindings are divided into modes. A bind instruction can include one or more keys (each key is bound separately) and one or more actions. The actions of a key run one after another, in the order they are written.

Keybindings can also be changed from the settings screen, under Keyboard → Key bindings and preset….

Modes

The keybindings are divided into several modes. Each mode has its separate keybindings.

eg. keybindings available in normal mode go in the normal block, and keybindings available in pane mode go in the pane block:

keybinds {
    normal {
        bind "Alt n" { NewPane; }
    }
    pane {
        bind "n" { NewPane; SwitchToMode "normal"; }
    }
}

The available modes are:

• normal
• locked
• resize
• pane
• move
• tab
• scroll
• search
• entersearch
• renametab
• renamepane
• renamesession
• session
• tmux

The renamesession mode

The session can be renamed from session mode (r in the built-in presets). While in renamesession mode, typed text edits the new session name (through the SessionNameInput action). The new name is applied when leaving the mode, eg. with Enter or Ctrl c. In the built-in presets, Esc drops the new name with UndoRenameSession and returns to session mode.

A note about scroll mode

Leaving scroll mode keeps the scroll position of the pane - the pane is no longer scrolled back down to the bottom automatically. To scroll to the bottom and leave the mode, use a binding that includes the ScrollToBottom action.

Focusing a pane that is scrolled back automatically enters scroll mode, and focusing a pane that is not scrolled back returns to normal mode.

Scrolling a pane also enters and exits scroll mode implicitly. This can be turned off with the scroll_mode_sync option, in which case scroll mode is only entered through an explicit keybinding.

Binding keys

Keys are bound with bind instructions inside each mode. A bind instruction consists of a list of keys to be bound, as well as a list of actions to be bound to each of those keys.

Note: The actions of a key run one after another, in the order they are written. Each action waits for the one before it to finish.

eg. to bind Alt n to open a new pane, both the h key and the left-arrow key to move pane focus left, and the f key to toggle the focused pane full-screen and switch to normal mode:

    bind "Alt n" { NewPane; }
    bind "h" "Left" { MoveFocus "Left"; }
    bind "f" { ToggleFocusFullscreen; SwitchToMode "Normal"; }

Overriding keys

When configured, keybindings override the keybindings of the active keybinding preset individually (if a certain key was bound in the configuration, it overrides that key in the preset).

It's possible to explicitly unbind a key, either in all modes (unbind at the top of the block) or in a specific mode (one or more keys):

keybinds {
    unbind "Ctrl g"
    normal {
        unbind "Alt h" "Alt n"
    }
}

It's also possible to use the special clear-defaults=true attribute to drop the keybindings of the preset, either globally (all modes):

keybinds clear-defaults=true {
    normal {
        bind "Ctrl g" { SwitchToMode "locked"; }
    }
}

or in a specific mode:

keybinds {
    normal clear-defaults=true {
        bind "Ctrl g" { SwitchToMode "locked"; }
    }
}

Note that when a preset is chosen on the command line (with zellij options --keybinds-preset), a keybinds clear-defaults=true block in the configuration is ignored completely, so that the chosen preset is used as it is.

Keys

Keys are defined in a single quoted string, with space delimiting modifier keys.

eg. the individual character a, a with the ctrl modifier, a with the alt modifier, a with both the ctrl and alt modifiers, the F8 key and the left arrow key:

bind "a" { NewPane; }
bind "Ctrl a" { NewPane; }
bind "Alt a" { NewPane; }
bind "Ctrl Alt a" { NewPane; }
bind "F8" { NewPane; }
bind "Left" { NewPane; }

• Possible keys

  • digits or lowercase characters (eg. a)
  • function keys 1-12 (eg. F1)
  • Backspace
  • Left (left-arrow key)
  • Right (right-arrow key)
  • Up (up-arrow key)
  • Down (down-arrow key)
  • Home
  • End
  • PageUp
  • PageDown
  • Tab
  • Delete (can also be written as Del)
  • Insert
  • Space
  • Enter
  • Esc

• Possible modifiers

  • Ctrl
  • Alt
  • Shift
  • Super

Inside a keybinding preset file, keys can also use the {primary}, {secondary} and {unlock} placeholders (eg. "{primary} p"). These are not supported in the keybinds block of the configuration file.

Mouse buttons are bound separately, in the mousebinds block. See Mouse Bindings.

A note about multiple and special modifiers

Some modifiers (eg. Super), multiple modifiers (eg. Ctrl Alt) as well as certain key combinations require support from the terminal emulator as well. Example of supporting terminals are: Alacritty, WezTerm and foot.

Possible Actions

Actions whose name ends in ByPaneId, ById or ByTabId act on a specific pane or tab instead of the focused one. In a keybinding the pane or tab id must be given. Inside an item of the right-click menu it can be left out, and the clicked pane or tab is used.

Clear

Clear the scrollback buffer of the focused pane

Possible arguments: None

eg.

    bind "a" { Clear; }

Copy

Copy the current text selection to the clipboard

Possible arguments: None

    bind "a" { Copy; }

CopyLastCommandOutput

Copy the output of the last command run in the focused pane to the clipboard. Requires the shell to emit OSC 133 shell integration sequences, which delimit the command's output. The copied region is briefly flashed in the pane.

Possible arguments: None

By default bound to c in scroll mode.

    bind "a" { CopyLastCommandOutput; }

ApplyFloatingSwapLayout

Apply the floating swap layout with the given name, as declared in the layout file. Floating pane visibility and focus are left as they are. If no floating swap layout with that name fits the current number of panes, nothing changes.

Required arguments: the name of the swap layout

    bind "a" { ApplyFloatingSwapLayout "spread"; }

ApplyTiledSwapLayout

Apply the tiled swap layout with the given name, as declared in the layout file. Floating pane visibility and focus are left as they are. If no tiled swap layout with that name fits the current number of panes, nothing changes.

Required arguments: the name of the swap layout

    bind "a" { ApplyTiledSwapLayout "vertical"; }

BreakPane

Break the focused pane out of its current tab into a new tab

Possible arguments: None

eg.

    bind "a" { BreakPane; }

BreakPaneLeft

Break the focused pane out into a new tab to the left of the current tab

Possible arguments: None

eg.

    bind "a" { BreakPaneLeft; }

BreakPaneRight

Break the focused pane out into a new tab to the right of the current tab

Possible arguments: None

eg.

    bind "a" { BreakPaneRight; }

CloseFocus

Close the focused pane

Possible arguments: None

eg.

    bind "a" { CloseFocus; }

CloseFocusByPaneId

Close a specific pane

Required arguments: a pane id as a string, eg. "terminal_1", "plugin_2" or "3" (the same as "terminal_3"). It can only be left out inside a right-click menu item.

    bind "a" { CloseFocusByPaneId "terminal_1"; }

CloseTab

Close the focused tab

Possible arguments: None

eg.

    bind "a" { CloseTab; }

CloseTabById

Close a specific tab

Required arguments: a numeric tab id. It can only be left out inside a right-click menu item.

    bind "a" { CloseTabById 2; }

Detach

Detach from the current session, leaving it running in the background

Possible arguments: None

eg.

    bind "a" { Detach; }

DismissInfoPopups

Close the information popups (such as those shown with zellij prompt notify) shown to this user

Possible arguments: None

    bind "a" { DismissInfoPopups; }

DumpScreen

Dump the contents of the focused pane, including its entire scrollback, to the specified file.

Required arguments: A path to a file on the hard-drive

Optional arguments: full - true or false (include full scrollback, default is false), ansi - true or false (preserve ANSI styling, default is false)

eg.

    bind "a" { DumpScreen "/tmp/my-dump.txt"; }

EditScrollback

Edit the scrollback of the currently focused pane with the user's default editor.

Optional arguments (in child block):

• ansi - true or false (preserve ANSI styling in the scrollback dump, default is false)

    bind "a" { EditScrollback; }

or with ANSI styling preserved:

    bind "a" { EditScrollback { ansi true; } }

FocusGuestSession

When the focused pane contains a nested Zellij session, descend into it - routing keyboard and mouse input to the nested (guest) session and dimming the chrome of the host session.

Possible arguments: None

By default bound to [ in session mode.

    bind "a" { FocusGuestSession; }

FocusHostSession

When running inside a nested Zellij session, return focus to the host (outer) session.

Possible arguments: None

By default bound to ] in session mode.

    bind "a" { FocusHostSession; }

FocusLastPane

Change focus back to the pane that was focused before the currently focused one. Takes floating panes into account, and swaps the pane in place when the focused pane is fullscreen.

Possible arguments: None

By default bound to ; in pane mode.

    bind "a" { FocusLastPane; }

FocusNextPane

Change focus to the next pane (order not guaranteed)

Possible arguments: None

    bind "a" { FocusNextPane; }

FocusPreviousPane

Change focus to the previous pane (order not guaranteed)

Possible arguments: None

    bind "a" { FocusPreviousPane; }

GoToNextAttention

Jump to the next pane that needs attention (see the inbox), in any session, switching session if needed

Possible arguments: None

By default bound to n in session mode.

    bind "a" { GoToNextAttention; }

GoToNextSession

Go forward in this user's history of visited sessions

Possible arguments: None

By default bound to Right in session mode.

    bind "a" { GoToNextSession; }

GoToPreviousSession

Go back in this user's history of visited sessions

Possible arguments: None

By default bound to Left in session mode.

    bind "a" { GoToPreviousSession; }

GoToNextTab

Change focus to the next tab

Possible arguments: None

    bind "a" { GoToNextTab; }

GoToPreviousTab

Change focus to the previous tab

Possible arguments: None

    bind "a" { GoToPreviousTab; }

GoToTab

Change focus to a tab with a specific index

Required arguments: numeric tab index (eg. 1)

    bind "a" { GoToTab 1; }

HalfPageScrollDown

Scroll the focused pane half a page down

Possible arguments: None

    bind "a" { HalfPageScrollDown; }

HalfPageScrollUp

Scroll the focused pane half a page up

Possible arguments: None

    bind "a" { HalfPageScrollUp; }

HideBarByPaneId

Hide the bar (eg. the tab-bar or status-bar) shown in a specific pane, in every tab

Required arguments: a pane id as a string, eg. "terminal_1", "plugin_2" or "3" (the same as "terminal_3"). It can only be left out inside a right-click menu item.

    bind "a" { HideBarByPaneId "plugin_1"; }

HideBars

Hide the named bars in every tab, or all bars if none are named. They can be shown again with ShowBars or ToggleBars.

Possible arguments: zero or more bar names: tab-bar, status-bar, compact-bar, a plugin alias or location, or all

    bind "a" { HideBars; }

or:

    bind "a" { HideBars "status-bar"; }

HideFloatingPanes

Hide all floating panes in the current (or specified) tab

Possible arguments: An optional tab index (integer)

    bind "a" { HideFloatingPanes; }

or:

    bind "a" { HideFloatingPanes 2; }

IgnorePaneOutput

Stop or start reporting new output of the focused pane. Only the "new output" note is hidden; panes that need attention, failed commands and finished commands are still reported.

Possible arguments: None

By default bound to g in pane mode.

    bind "a" { IgnorePaneOutput; }

IgnorePaneOutputByPaneId

Like IgnorePaneOutput, for a specific pane

Required arguments: a pane id as a string, eg. "terminal_1", "plugin_2" or "3" (the same as "terminal_3"). It can only be left out inside a right-click menu item.

    bind "a" { IgnorePaneOutputByPaneId "terminal_1"; }

LaunchOrFocusPlugin

Launch a plugin if it is not already loaded somewhere in the session, focus it if it is

Required arguments: The plugin URL (eg. file:/path/to/my/plugin.wasm)

Optional arguments:

• floating - true or false (default is false)
• in_place - true or false (open in place of the focused pane, default is false)
• close_replaced_pane - true or false (when using in_place, close the replaced pane instead of suspending it, default is false)
• move_to_focused_tab - true or false (if the plugin is already running, move it to the focused tab, default is false)
• skip_plugin_cache - true or false (skip the plugin cache and force reloading, default is false)

    bind "a" {
        LaunchOrFocusPlugin "zellij:strider" {
            floating true
        }
    }

or:

    bind "a" {
        LaunchOrFocusPlugin "zellij:strider" {
            in_place true
            move_to_focused_tab true
        }
    }

LaunchPlugin

Launch a new plugin instance. Unlike LaunchOrFocusPlugin, this always launches a new instance even if one is already running.

Required arguments: The plugin URL (eg. file:/path/to/my/plugin.wasm)

Optional arguments:

• floating - true or false (default is false)
• in_place - true or false (open in place of the focused pane, default is false)
• close_replaced_pane - true or false (when using in_place, close the replaced pane instead of suspending it, default is false)
• skip_plugin_cache - true or false (skip the plugin cache and force reloading, default is false)
• Additional key-value pairs are passed as plugin user configuration

    bind "a" {
        LaunchPlugin "file:/path/to/my/plugin.wasm" {
            floating true
            skip_plugin_cache true
            my_config_key "my_config_value"
        }
    }

MarkAllSeen

Mark every pane of every running session as seen, clearing past events

Optional arguments: this_session - true or false (only mark the panes of the current session, default is false)

    bind "a" { MarkAllSeen; }

or:

    bind "a" { MarkAllSeen this_session=true; }

MarkPaneSeen

Mark the focused pane as seen, clearing its past events

Possible arguments: None

    bind "a" { MarkPaneSeen; }

MessagePlugin

Send a message to one or more plugins, using a pipe - meaning the plugin will be launched if it is not already running.

Required arguments: None (with no options specified, this keybind will send an empty message to all plugins)

Optional arguments:: - launch_new (true/false): force a new plugin to launch even if one is already running - skip_cache (true/false): skip the plugin cache and force reloading (and re-download if the plugin is http), even if the plugin is already running or cached - floating (true/false): if launching a new plugin, should it be floating or tiled - in_place (true/false): if launching a new plugin, open it in place of the focused pane - name (String): The name of the message - payload (String): The payload of the message - title (String): The pane title of the pane if launching a new plugin instance - cwd (String): The working directory of the plugin if launching a new instance

    bind "a" {
        MessagePlugin "file:/path/to/my/plugin.wasm" {
            name "message_name"
            payload "message_payload"
            cwd "/path/to/my/working/directory"
        }
    }

There is also MessagePluginId which sends a message to a specific running plugin by its numeric ID:

    bind "a" {
        MessagePluginId 42 {
            name "message_name"
            payload "message_payload"
        }
    }

MoveFocus

Move focus in a specific direction

Required arguments: Left | Right | Up | Down

    bind "a" { MoveFocus "Left"; }

MoveFocusOrTab

Move focus left or right, or to the next or previous tab if on screen edge

Required arguments: Left | Right

    bind "a" { MoveFocusOrTab "Left"; }

MovePane

Move the position of the focused pane in the specific direction

Required arguments: Left | Right | Up | Down

    bind "a" { MovePane "Left"; }

MovePaneBackwards

Move the focused pane backwards in the layout order (the inverse of MovePane without a direction)

Possible arguments: None

    bind "a" { MovePaneBackwards; }

MoveTab

Change the position of the active tab either left or right.

Required arguments: the direction, either "Left" or "Right"

    bind "a" { MoveTab "Left"; }

MoveTabByTabId

Move a specific tab one position to the left or right

Required arguments: the direction ("left" or "right") followed by a numeric tab id. The tab id can only be left out inside a right-click menu item.

    bind "a" { MoveTabByTabId "left" 2; }

MoveTabToPosition

Move a specific tab to a position in the tab list. This is also what dragging a tab in the tab bar does.

Required arguments: the position ("start", "end", or a number counting from 0) followed by a numeric tab id. The tab id can only be left out inside a right-click menu item.

    bind "a" { MoveTabToPosition "start" 2; }

MutePane

Mute or unmute the focused pane. A muted pane shows nothing it reports (on its frame, in the tab bar or in the inbox) and raises no desktop notifications. It is still tracked, so unmuting it shows its current state.

Possible arguments: None

By default bound to u in pane mode.

    bind "a" { MutePane; }

MutePaneByPaneId

Like MutePane, for a specific pane

Required arguments: a pane id as a string, eg. "terminal_1", "plugin_2" or "3" (the same as "terminal_3"). It can only be left out inside a right-click menu item.

    bind "a" { MutePaneByPaneId "terminal_1"; }

MuteSession

Mute or unmute all panes of the current session

Possible arguments: None

By default bound to u in session mode.

    bind "a" { MuteSession; }

MuteTab

Mute or unmute all panes of the active tab

Possible arguments: None

By default bound to u in tab mode.

    bind "a" { MuteTab; }

MuteTabByTabId

Like MuteTab, for a specific tab

Required arguments: a numeric tab id. It can only be left out inside a right-click menu item.

    bind "a" { MuteTabByTabId 2; }

NextSwapLayout

Change the layout of the current tab (either tiled or floating) to the next one

Possible arguments: None

By default bound to Alt ] in all modes except locked, and to Space in tab mode.

    bind "a" { NextSwapLayout; }

OverrideLayout

Override the layout of the active tab with the specified layout file.

Optional arguments (in child block):

• layout - path to the layout file
• cwd - working directory for the layout
• name - name of the tab
• retain_existing_terminal_panes - true or false (keep terminal panes not fitting the new layout, default is false)
• retain_existing_plugin_panes - true or false (keep plugin panes not fitting the new layout, default is false)
• apply_only_to_active_tab - true or false (only apply to the active tab, default is false)

    bind "a" {
        OverrideLayout {
            layout "/path/to/layout.kdl"
            retain_existing_terminal_panes true
            apply_only_to_active_tab true
        }
    }

NewFloatingPane

Open a new floating terminal pane

Possible arguments: None

By default bound to a in pane mode.

    bind "a" { NewFloatingPane; }

NewPane

Open a new pane (in the specified direction)

Possible arguments: Down | Right | Stacked

Behaviour without arguments: Opens a pane in the largest available space or if floating panes are visible, in the next floating pane position.

    bind "a" { NewPane "Right"; }

or open a stacked pane:

    bind "a" { NewPane "Stacked"; }

Note: For more advanced pane creation options (floating coordinates, borderless, close-on-exit, cwd, etc.), use the Run keybinding action instead.

NewTab

Open a new tab

Possible arguments: cwd

Current working directory for the new tab, name - the name of the new tab, layout - path to the layout file to load for this tab

    bind "a" { NewTab; }

or:

    bind "a" {
       NewTab {
           cwd "/tmp"
           name "My tab name"
           layout "/path/to/my/layout.kdl"
       }
    }

OpenContextMenu

Open the right-click menu of the focused pane, at that pane's position

Possible arguments: None

    bind "a" { OpenContextMenu; }

OpenSessionInTerminal

Open the current session in a window of the Zellij terminal

Possible arguments: None

    bind "a" { OpenSessionInTerminal; }

PageScrollDown

Scroll the focused pane one page down

Possible arguments: None

    bind "a" { PageScrollDown; }

PageScrollUp

Scroll the focused pane one page up

Possible arguments: None

    bind "a" { PageScrollUp; }

PaneNameInput

Send byte input for renaming the focused pane. Typically used in the RenamePane input mode.

Required arguments: One or more integer (u8) byte values

    bind "a" { PaneNameInput 0; }

PasteFromClipboardByPaneId

Paste the clipboard into a specific pane. This only works in clients that can read the clipboard (the Zellij terminal); elsewhere it does nothing.

Required arguments: a pane id as a string, eg. "terminal_1", "plugin_2" or "3" (the same as "terminal_3"). It can only be left out inside a right-click menu item.

    bind "a" { PasteFromClipboardByPaneId "terminal_1"; }

PreviousSwapLayout

Change the layout of the current tab (either tiled or floating) to the previous one

Possible arguments: None

By default bound to Alt [ in all modes except locked, and to Shift Space in tab mode.

    bind "a" { PreviousSwapLayout; }

Quit

Quit Zellij :(

Since 0.46.0, quitting from a keybinding first asks for confirmation. What it asks (or whether it asks at all) is set with the on_quit option. Pressing the quit key again while the question is shown quits.

Possible arguments: None

    bind "a" { Quit; }

Resize

Resize the focused pane either in the specified direction or increase/decrease its size automatically

Required arguments: Left | Right | Up | Down | Increase | Decrease

    bind "a" { Resize "Increase"; }

RenameSession

Rename the current session

Required arguments: The new session name as a string

    bind "a" { RenameSession "my-new-session-name"; }

Run

Run the specified command in a new pane

Required arguments: The command to run, followed by optional arguments

Possible arguments (in child block):

• cwd - current working directory
• direction - the direction to open the new command pane ("Down" | "Right")
• floating - true or false (open as a floating pane)
• in_place - true or false (open in place of the focused pane)
• close_replaced_pane - true or false (when using in_place, close the replaced pane)
• stacked - true or false (open as a stacked pane)
• name - name for the new pane
• close_on_exit - true or false (close the pane when the command exits)
• start_suspended - true or false (start the command suspended)
• x, y, width, height - floating pane coordinates (when floating is true)
• pinned - true or false (pin the floating pane, when floating is true)
• borderless - true or false (hide the pane border, when floating is true)
• border_style - the line style of the new pane's border: "single", "double", "heavy", "dashed" or "heavy_dashed". border_top, border_right, border_bottom and border_left set one side each, and border_rounded_corners (true or false) rounds the corners. These apply to floating and tiled panes, not to in_place or stacked ones.
• background - true or false (run the command without opening a pane, default is false). Only the command, its arguments and cwd are used; the other arguments are ignored. Without cwd, the command runs in the working directory of the pane that was focused; a relative cwd is taken from that directory.

A command started with Run gets the ZELLIJ_ORIGIN_PANE_ID environment variable: the id of the pane that was focused when the key was pressed, eg. terminal_3 or plugin_2. Focus changes made earlier in the same binding count, so MoveFocus "Left"; Run "my-script"; reports the pane on the left. A background command also gets ZELLIJ_PANE_ID set to that terminal pane's number (it is not set when the focused pane is a plugin).

eg. to run "tail -f /tmp/foo" in a pane opened below the focused one:

    bind "a" {
        Run "tail" "-f" "foo" {
            cwd "/tmp"
            direction "Down"
        }
    }

or as a floating pane:

    bind "a" {
        Run "htop" {
            floating true
            x "10%"
            y "10%"
            width "80%"
            height "80%"
        }
    }

or in place of the focused pane:

    bind "a" {
        Run "htop" {
            in_place true
            close_replaced_pane true
        }
    }

or as a stacked pane:

    bind "a" {
        Run "htop" {
            stacked true
        }
    }

or with a double border:

    bind "a" {
        Run "htop" {
            floating true
            border_style "double"
        }
    }

or in the background, without a pane:

    bind "a" {
        Run "sh" "-c" "echo $ZELLIJ_ORIGIN_PANE_ID >> /tmp/focused-panes" {
            background true
        }
    }

ScrollDown

Scroll the focused pane down 1 line

Possible arguments: None

    bind "a" { ScrollDown; }

ScrollToBottom

Scroll the focused pane completely down

Possible arguments: None

    bind "a" { ScrollToBottom; }

ScrollToNextPrompt

Scroll the focused pane down to the next shell prompt in its scrollback. Requires the shell to emit OSC 133 shell integration sequences.

Possible arguments: None

By default bound to ] in scroll and search modes.

    bind "a" { ScrollToNextPrompt; }

ScrollToPreviousPrompt

Scroll the focused pane up to the previous shell prompt in its scrollback. Requires the shell to emit OSC 133 shell integration sequences.

Possible arguments: None

By default bound to [ in scroll and search modes.

    bind "a" { ScrollToPreviousPrompt; }

ScrollUp

Scroll the focused pane up 1 line

Possible arguments: None

    bind "a" { ScrollUp; }

ScrollToTop

Scroll the focused pane completely up

Possible arguments: None

    bind "a" { ScrollToTop; }

Search

When searching, move to the next or previous search occurrence

Required arguments: "down" | "up"

    bind "a" { Search "up"; }

SearchInput

Send byte input for the search needle. Typically used in the EnterSearch input mode.

Required arguments: One or more integer (u8) byte values

    bind "a" { SearchInput 0; }

SearchToggleOption

Toggle various search options on/off

Required arguments: "CaseSensitivity" | "Wrap" | "WhileWord"

    bind "a" { SearchToggleOption "CaseSensitivity"; }

SelectCommandAtScrollPosition

Select the command and its output at the current scroll position of the focused pane, so that it can be copied. Requires the shell to emit OSC 133 shell integration sequences.

Possible arguments: None

By default bound to m in scroll and search modes.

    bind "a" { SelectCommandAtScrollPosition; }

SessionNameInput

Send byte input for renaming the current session. Typically used in the RenameSession input mode, where 0 clears the name to start typing a new one.

Required arguments: One or more integer (u8) byte values

By default bound to r in session mode.

    bind "a" { SwitchToMode "RenameSession"; SessionNameInput 0; }

SetDarkTheme

Switch the theme to dark (uses the configured theme_dark).

Possible arguments: None

    bind "a" { SetDarkTheme; }

SetLightTheme

Switch the theme to light (uses the configured theme_light).

Possible arguments: None

    bind "a" { SetLightTheme; }

SetPaneFrameStyle

Set the style of the pane frames for the whole session (see the pane_frame_style option)

Required arguments: "full" | "titles" | "none"

    bind "a" { SetPaneFrameStyle "full"; }

SwitchToMode

Switch the current input mode

Required arguments: See Modes

    bind "a" { SwitchToMode "locked"; }

ShowBars

Show all hidden bars

Possible arguments: None

    bind "a" { ShowBars; }

ShowFloatingPanes

Show all floating panes in the current (or specified) tab

Possible arguments: An optional tab index (integer)

    bind "a" { ShowFloatingPanes; }

or:

    bind "a" { ShowFloatingPanes 2; }

StartRenamePaneByPaneId

Start renaming a specific pane: enter the RenamePane input mode for that pane, with its name cleared

Required arguments: a pane id as a string, eg. "terminal_1", "plugin_2" or "3" (the same as "terminal_3"). It can only be left out inside a right-click menu item.

    bind "a" { StartRenamePaneByPaneId "terminal_1"; }

StartRenameTabByTabId

Start renaming a specific tab: enter the RenameTab input mode for that tab, with its name cleared

Required arguments: a numeric tab id. It can only be left out inside a right-click menu item.

    bind "a" { StartRenameTabByTabId 2; }

SwitchSession

Switch to a different named session. The session must already exist or be creatable.

Required arguments: name - the session name to switch to

Optional arguments (in child block):

• tab_position - tab index to focus after switching (integer)
• pane_id - pane ID to focus after switching (integer)
• is_plugin - whether the pane_id refers to a plugin pane (true or false, default is false)
• layout - layout file path to apply
• cwd - working directory for the session
• close_current - true or false (close the current session after switching, if no command has been run in it and no other user is attached; default is false)

    bind "a" {
        SwitchSession {
            name "my-other-session"
        }
    }

or:

    bind "a" {
        SwitchSession {
            name "my-session"
            tab_position 0
            layout "/path/to/layout.kdl"
            cwd "/home/user"
        }
    }

TabNameInput

Send byte input for renaming the focused tab. Typically used in the RenameTab input mode.

Required arguments: One or more integer (u8) byte values

    bind "a" { TabNameInput 0; }

ToggleActiveSyncTab

Toggle the syncing of input between all panes in the focused tab

Possible arguments: None

    bind "a" { ToggleActiveSyncTab; }

ToggleBars

If any bar is hidden, show all bars. Otherwise hide the named bars (all bars if none are named) in every tab.

Possible arguments: zero or more bar names: tab-bar, status-bar, compact-bar, a plugin alias or location, or all

By default bound to Shift z in pane mode.

    bind "a" { ToggleBars; }

ToggleFloatingPanes

Show/hide floating panes; if none are open, one will be opened

Possible arguments: None

    bind "a" { ToggleFloatingPanes; }

ToggleFocusFullscreen

Toggle the focused pane as fullscreen on/off

Possible arguments: None

    bind "a" { ToggleFocusFullscreen; }

ToggleFocusFullscreenByPaneId

Like ToggleFocusFullscreen, for a specific pane

Required arguments: a pane id as a string, eg. "terminal_1", "plugin_2" or "3" (the same as "terminal_3"). It can only be left out inside a right-click menu item.

    bind "a" { ToggleFocusFullscreenByPaneId "terminal_1"; }

ToggleFocusNoUiFullscreen

Toggle the focused pane as fullscreen on/off, with the pane taking up the entire display - including the space normally occupied by the UI bars (eg. the tab-bar and status-bar). Unlike ToggleFocusFullscreen, which keeps them visible.

Possible arguments: None

By default bound to Shift f in pane mode.

    bind "a" { ToggleFocusNoUiFullscreen; }

ToggleHostFullscreen

When running inside a nested Zellij session, toggle the fullscreen state of this session's pane within the host (outer) session.

Possible arguments: None

By default bound to f in session mode.

    bind "a" { ToggleHostFullscreen; }

ToggleMirrorResize

Toggle whether the live view of a pane shown in the focused plugin pane (eg. in the inbox) resizes the program of the pane it shows

Possible arguments: None

    bind "a" { ToggleMirrorResize; }

ToggleMouseMode

Toggle mouse support on/off

Possible arguments: None

    bind "a" { ToggleMouseMode; }

TogglePaneEmbedOrFloating

Float focused embedded pane or embed focused floating pane

Possible arguments: None

    bind "a" { TogglePaneEmbedOrFloating; }

TogglePaneEmbedOrFloatingByPaneId

Like TogglePaneEmbedOrFloating, for a specific pane

Required arguments: a pane id as a string, eg. "terminal_1", "plugin_2" or "3" (the same as "terminal_3"). It can only be left out inside a right-click menu item.

    bind "a" { TogglePaneEmbedOrFloatingByPaneId "terminal_1"; }

TogglePaneFrames

Show/hide the frames around panes (notice, these might have valuable UX info)

Possible arguments: None

    bind "a" { TogglePaneFrames; }

TogglePaneInGroup

Toggle whether the focused pane is included in a pane group

Possible arguments: None

    bind "a" { TogglePaneInGroup; }

TogglePaneInGroupByPaneId

Like TogglePaneInGroup, for a specific pane

Required arguments: a pane id as a string, eg. "terminal_1", "plugin_2" or "3" (the same as "terminal_3"). It can only be left out inside a right-click menu item.

    bind "a" { TogglePaneInGroupByPaneId "terminal_1"; }

TogglePanePinned

Toggle the pinned state of a floating pane. A pinned floating pane stays on top of other panes.

Possible arguments: None

    bind "a" { TogglePanePinned; }

TogglePanePinnedByPaneId

Like TogglePanePinned, for a specific pane

Required arguments: a pane id as a string, eg. "terminal_1", "plugin_2" or "3" (the same as "terminal_3"). It can only be left out inside a right-click menu item.

    bind "a" { TogglePanePinnedByPaneId "terminal_1"; }

ToggleGroupMarking

Toggle group marking mode, allowing selection of multiple panes for group operations

Possible arguments: None

    bind "a" { ToggleGroupMarking; }

ToggleSession

Switch to the session this user was in before (run again to return), or to the next running session if there is none

Possible arguments: None

By default bound to Tab in session mode.

    bind "a" { ToggleSession; }

ToggleSessionCard

Show or hide the inbox. If the inbox is open but not focused, focus it. If a live view of a pane inside the inbox has the keyboard, give the keys back to the inbox instead.

Possible arguments: None

By default bound to i in session mode.

    bind "a" { ToggleSessionCard; }

ToggleStackListOrientation

Switch the focused stack between showing its pane titles in a column (vertical) and in a row (horizontal). See the stacked_pane_list_orientation option.

Possible arguments: None

By default bound to Shift s in pane mode.

    bind "a" { ToggleStackListOrientation; }

ToggleStackListOrientationByPaneId

Like ToggleStackListOrientation, for the stack holding a specific pane

Required arguments: a pane id as a string, eg. "terminal_1", "plugin_2" or "3" (the same as "terminal_3"). It can only be left out inside a right-click menu item.

    bind "a" { ToggleStackListOrientationByPaneId "terminal_1"; }

ToggleTab

Change the tab focus

Possible arguments: None

    bind "a" { ToggleTab; }

ToggleTheme

Toggle between the configured theme_dark and theme_light.

Possible arguments: None

    bind "a" { ToggleTheme; }

ToggleTrayIcon

Show or hide the tray (menu-bar) icon of the Zellij desktop app until the app restarts. Sessions and notifications keep working while it is hidden.

Possible arguments: None

    bind "a" { ToggleTrayIcon; }

UndoRenamePane

Undo a rename pane operation currently in progress (reverting to the previous name)

Possible arguments: None

    bind "a" { UndoRenamePane; }

UndoRenameTab

Undo a rename tab operation currently in progress (reverting to the previous name)

Possible arguments: None

    bind "a" { UndoRenameTab; }

UndoRenameSession

Undo a rename session operation currently in progress (keeping the previous name)

Possible arguments: None

By default bound to Esc in renamesession mode.

    bind "a" { UndoRenameSession; }

WatchPane

Watch or stop watching the focused pane. A watched pane is reported as needing attention each time a command finishes (even a short one), the pane exits, or its output goes quiet. New output alone is not reported. It stays on until turned off.

Possible arguments: None

By default bound to v in pane mode.

    bind "a" { WatchPane; }

WatchPaneByPaneId

Like WatchPane, for a specific pane

Required arguments: a pane id as a string, eg. "terminal_1", "plugin_2" or "3" (the same as "terminal_3"). It can only be left out inside a right-click menu item.

    bind "a" { WatchPaneByPaneId "terminal_1"; }

Write

Write bytes to the active pane

Required arguments: the bytes to write as integers

    bind "a" { Write 102 111 111; }

WriteChars

Write a string of characters to the active pane

Required arguments: the string of characters to write

    bind "a" { WriteChars "hi there!"; }

Shared bindings

There are three special node types that can be used when defining keybindings:

• shared: the keybindings are present in all modes
• shared_except: the keybindings are present in all modes except the listed ones (here resize and locked)
• shared_among: the keybindings are present only in the listed modes (here resize and locked)

keybinds {
    shared {
        bind "Ctrl g" { SwitchToMode "locked"; }
    }
    shared_except "resize" "locked" {
        bind "Ctrl g" { SwitchToMode "locked"; }
    }
    shared_among "resize" "locked" {
        bind "Ctrl g" { SwitchToMode "locked"; }
    }
}

The same node types can be used in the mousebinds block.

Mouse Bindings

What mouse clicks and the scroll wheel do can be configured in the mousebinds block of the configuration file, the same way keys are configured in the keybinds block. Mouse bindings only apply while mouse_mode is on.

The default mouse bindings come from the active keybinding preset. Bindings in the mousebinds block are applied on top of them. Mouse bindings can also be changed in the settings screen, under Mouse → Mouse bindings….

mousebinds {
    shared {
        bind "Middle" { NewTab; }
        bind "Alt Double Left" on="frame" { ToggleFullscreen; }
        bind "ScrollUp" app_first=false { Scroll 5; }
        bind "ScrollDown" app_first=false { Scroll 5; }
    }
    locked {
        unbind "Right"
    }
}

Modes

Like keybindings, mouse bindings are divided into modes. The shared, shared_except and shared_among blocks work the same way as for keybindings.

mousebinds {
    normal {
        bind "Middle" { NewPane; }
    }
    shared_except "locked" {
        bind "Alt Middle" { NewTab; }
    }
}

Triggers

A trigger is a quoted string made of optional modifiers, an optional click count and a button, separated by spaces, eg. "Left", "Ctrl Left", "Double Left" or "Ctrl Shift Triple Right".

• Buttons

  • Left
  • Right
  • Middle
  • ScrollUp
  • ScrollDown
  • ScrollLeft
  • ScrollRight

• Modifiers

  • Ctrl
  • Alt
  • Shift

• Click counts

  • Double
  • Triple

Double and Triple can only be used with Left, Right and Middle. Super cannot be used, because terminals do not report it for mouse events.

Where the click lands: on

The on attribute limits a binding to one part of a pane:

• "content" - inside the pane
• "frame" - on the pane's frame
• "any" - anywhere on the pane (the default)

mousebinds {
    shared {
        bind "Double Left" on="frame" { ToggleFullscreen; }
        bind "Double Left" on="content" { Select; }
    }
}

Which binding is used

When a button is pressed, Zellij looks for a binding in this order:

1. A binding with the exact modifiers. If none matches and Shift is held, the same trigger without Shift is tried.
2. A binding with the exact click count, then with fewer clicks (a triple click falls back to Double, then to a single click).
3. A binding for the part of the pane that was clicked (content or frame), then an any binding.

A trigger with no binding is passed to the program in the pane (see PassToApp).

Programs that use the mouse: app_first

Some programs (eg. vim or htop) ask the terminal for mouse events. With app_first=true, a click on the focused pane goes to such a program instead of to the binding. Scroll bindings with app_first=true send the scroll to such programs, and to programs that use the full screen (eg. less), instead of scrolling the pane's scrollback.

mousebinds {
    shared {
        bind "Right" app_first=false { ContextMenu; }
    }
}

Without app_first, it is true for the Click, Select, FocusPane, ContextMenu, Scroll, ScrollColumns and ScrollToPrompt behaviours, and false for the others and for bindings that run actions.

What a binding does

A binding does one of two things:

• One mouse behaviour (listed below), which must be the only item in the binding:

  bind "Middle" { ToggleFullscreen; }
  

• One or more actions, as in a keybinding. The pane under the pointer is focused first, then the actions run:

  bind "Alt Middle" { NewPane "Right"; SwitchToMode "normal"; }
  

MovePane without arguments is the mouse behaviour (drag a floating pane). With a direction (eg. MovePane "left") it is the normal action.

Mouse behaviours

For example, to draw a floating terminal with Ctrl and a floating plugin with Ctrl Alt:

mousebinds {
    normal {
        bind "Ctrl Left" on="content" { DrawFloatingPane; }
        bind "Ctrl Alt Left" { DrawFloatingPane "file:/path/to/plugin.wasm" { key "value"; }; }
    }
}

Unbinding and clearing

unbind removes a binding, either in all modes (at the top of the block) or in one mode. It takes the same on attribute as bind:

mousebinds {
    unbind "ScrollLeft" "ScrollRight"
    normal {
        unbind "Middle" on="content"
    }
}

clear-defaults=true drops the bindings of the preset, either on the whole block or for one mode:

mousebinds clear-defaults=true {
    shared {
        bind "Left" { Click; }
        bind "ScrollUp" { Scroll 3; }
        bind "ScrollDown" { Scroll 3; }
    }
}

A mousebinds block in a layout is applied on top of the one in the configuration file.

Default mouse bindings

These are the mouse bindings of both built-in presets, in all modes. Ctrl is the primary modifier and Alt the secondary one; changing the modifiers changes these bindings too.

In a keybinding preset file, the same bindings are written with placeholders, eg. bind "{primary} Left" on="frame" { ResizePane; }. A preset without a mousebinds block uses these default bindings.

The tab bar

The tab bar (and the compact bar) handle their own clicks:

• Clicking a tab switches to it.
• Dragging a tab left or right moves it to a new position.
• Double-clicking a tab starts renaming it.
• Double-clicking an empty part of the bar opens a new tab.
• Right-clicking a tab or the bar opens the right-click menu for it.
• Scrolling over the tab bar switches tabs.

The two double-click actions can be turned off with the double_click_tab and double_click_empty plugin options:

plugins {
    tab-bar location="zellij:bars" {
        role "tab-bar"
        double_click_tab "none"
        double_click_empty "none"
    }
}

The Right-Click Menu

Right-clicking in Zellij opens a menu with actions for what was clicked. There are three menus:

• pane: opened by right-clicking inside a pane or on its frame
• tab: opened by right-clicking a tab in the tab bar
• bar: opened by right-clicking the background of a bar (eg. the tab bar or the status bar)

Items that do the same as a keybinding show that keybinding next to them. Items that do not apply where the menu was opened are left out: for example "Paste" when there is nothing to paste, "Show bars" when no bar is hidden, or "Show titles in a row" outside of a stack.

The menu itself is drawn by a plugin, see the context-menu alias.

Turning the menu off

The menu is turned off with the context_menu_enabled option:

context_menu_enabled false

When it is off, right clicks go to the focused pane only, and Alt + right click clears the pane group. Plugins can still open the menu through their API.

Changing the items

The items are set in the context_menu block of the configuration file. It has one section for each menu (pane, tab and bar), and a common section whose items are added to the end of every menu, after a separator.

Without clear-defaults, a section changes the default items of its menu with these statements:

remove ignores labels that do not exist, and an item placed after or before a label that does not exist goes to the end.

For example, this adds an item to the pane menu after "New floating pane", and removes "Mute pane":

context_menu {
    pane {
        item "Edit scrollback" after="New floating pane" { EditScrollback; }
        remove "Mute pane"
    }
}

Replacing the default items

clear-defaults=true on a section replaces the default items of that section with the items listed in it. On the whole block, it replaces the default items of every section:

context_menu {
    tab clear-defaults=true {
        item "Rename tab…" { StartRenameTabByTabId; }
        separator
        item "Close tab" { CloseTabById; }
    }
}

An empty context_menu clear-defaults=true {} leaves the menu empty, so it never opens, but Zellij still takes right clicks. To give right clicks back to the panes, use context_menu_enabled false instead.

Items

An item has a label and one or more actions, the same actions that can be bound to keys. The actions run in order when the item is chosen.

An item can also have a toggled_label, shown instead of the label while the thing the item toggles is on. For example, this item shows "Exit fullscreen" while the clicked pane is fullscreen:

item "Fullscreen" toggled_label="Exit fullscreen" { ToggleFocusFullscreenByPaneId; }

Actions on the clicked pane or tab

These actions, written without a pane or tab id, apply to the pane or tab that was right-clicked rather than to the focused one:

Any other action applies as it would from a keybinding.

Placeholders in labels

Two kinds of items can have {} in their label:

• An item that runs HideBarByPaneId: {} is replaced by the name of the clicked bar (eg. "Hide {}" becomes "Hide tab bar").
• An item that runs ToggleSession: {} is replaced by the name of the previous session. Without {}, the name is added to the end of the label. The item is left out when there is no previous session.

The default menu

These are the default items:

context_menu {
    pane {
        item "Paste" { PasteFromClipboardByPaneId; }
        separator
        item "New pane" { NewPane; }
        item "New floating pane" { NewFloatingPane; }
        separator
        item "Rename pane…" { StartRenamePaneByPaneId; }
        item "Fullscreen" toggled_label="Exit fullscreen" { ToggleFocusFullscreenByPaneId; }
        item "Make floating" toggled_label="Make tiled" { TogglePaneEmbedOrFloatingByPaneId; }
        item "Show titles in a row" toggled_label="Show titles in a column" { ToggleStackListOrientationByPaneId; }
        separator
        item "Watch pane" toggled_label="Stop watching" { WatchPaneByPaneId; }
        item "Mute pane" toggled_label="Unmute pane" { MutePaneByPaneId; }
        separator
        item "Close pane" { CloseFocusByPaneId; }
    }
    tab {
        item "New tab" { NewTab; }
        item "Rename tab…" { StartRenameTabByTabId; }
        item "Move left" { MoveTabByTabId "left"; }
        item "Move right" { MoveTabByTabId "right"; }
        item "Move to start" { MoveTabToPosition "start"; }
        item "Move to end" { MoveTabToPosition "end"; }
        item "Mute tab" toggled_label="Unmute tab" { MuteTabByTabId; }
        separator
        item "Close tab" { CloseTabById; }
    }
    bar {
        item "New tab" { NewTab; }
        separator
        item "Rename session…" { SwitchToMode "RenameSession"; SessionNameInput 0; }
        item "Back to {}" { ToggleSession; }
        item "Session manager…" {
            LaunchOrFocusPlugin "session-manager" {
                floating true
                move_to_focused_tab true
            }
        }
        item "Open in a Zellij terminal" { OpenSessionInTerminal; }
        separator
        item "Hide {}" { HideBarByPaneId; }
        item "Hide all bars" { HideBars; }
        separator
        item "Detach" { Detach; }
    }
    common {
        item "Show bars" { ShowBars; }
        item "Settings…" {
            LaunchOrFocusPlugin "configuration" {
                floating true
                move_to_focused_tab true
            }
        }
    }
}

The "Watch pane" and "Mute pane" items are left out when attention is turned off. "Open in a Zellij terminal" is only shown when a Zellij terminal window can be opened.

Editing the menu from the settings screen

The items can also be added, removed, changed and reordered in the "Right-click menu" page of the settings screen. When saved, each changed section is written to the context_menu block as changes to its default items, using the statements above. A section that cannot be written that way is written in full, with clear-defaults=true.

Session Suggestions

Zellij suggests other sessions that fit what the current session is working on, on the session card and in the session manager. For example, other sessions opened in the same folder, or on the same git branch, are listed first.

The order is set in the session_suggestions block of the configuration file. Without it, Zellij uses these rules:

session_suggestions {
    match "directory" "git_branch"
    match "git_repo" "git_branch"
    match "directory"
    match "git_repo"
    then "recent"
}

How sessions are ordered

Zellij keeps a few facts about each session (running or exited), taken from the folder of the session's focused pane. These are compared with the facts of the current session.

• match lists one or more facts. A session matches the rule when all of these facts are known for both sessions and are the same.
• The rules are tried in order, and the first one a session matches decides its place: sessions that match the first rule come first, then those that match the second rule, and so on.
• Within a rule, running sessions come first, then the most recently used ones.
• then sets the order of the sessions that match no rule:
  • "recent" (default) - running sessions first, then the most recently used
  • "alphabetical" - by name
  • "none" - these sessions are not suggested at all

Listing match rules replaces all the default rules.

Built-in facts

The built-in facts used by the rules are also shown as columns in the session manager.

Custom facts

fact adds a fact of its own, from the output of a command:

session_suggestions {
    fact "project" command="echo $PROJECT" column="project" at="live"
    match "project"
    match "directory"
}

• The first argument is the name of the fact. It cannot be one of the built-in names.
• command runs with sh -c in the folder. Its output, with spaces at the start and end removed, is the value of the fact. A command that fails, prints nothing, or takes longer than 1.5 seconds gives no value.
• column (optional) shows the fact as a column with this title in the session manager.
• at (optional) is when the command runs:
  • "live" (default) - again each time the folder of the focused pane changes
  • "start" - once, when the session starts, in the folder it started in

A fact used in a match rule must be built in or defined with fact.

Ranking script

script hands the final order to a program:

session_suggestions {
    script "~/.config/zellij/rank.sh" timeout_ms=300 hide_unlisted=false
}

• The first argument is the path of the program (a leading ~ is the home folder). It runs in the folder of the current session.
• timeout_ms (optional, default 300) is how long, in milliseconds, Zellij waits for the program. If it takes longer, the order from the rules is shown first, and replaced by the program's order when it finishes (within 10 seconds).
• hide_unlisted (optional, default false): when true, sessions the program does not print are not suggested. When false, they follow the printed ones, in the order from the rules.

The program receives up to 100 sessions on its standard input, already in the order from the rules (running sessions first), one JSON object per line:

The program prints session names, one per line, in the order they should be suggested. A name can be followed by a tab and a short label to show with that session. Unknown names and repeated names are ignored. If the program fails or prints nothing, the order from the rules is used.

For example, a script with this one command suggests running sessions only:

jq -r 'select(.running) | .name'

Recording facts with a script

record runs a program that adds facts to the current session:

session_suggestions {
    record "~/.config/zellij/record.sh"
}

The program runs in the folder of the focused pane, each time that folder changes. It receives one JSON line on its standard input:

{"session": "my-session", "folder": "/home/me/projects/app"}

It prints facts, one per line, as name<TAB>value or name=value. These become facts of the session, and are passed to the ranking script in its facts field. match rules can only use built-in facts and facts defined with fact. If the program fails or takes longer than 1.5 seconds, no facts are recorded.

Themes

Using the built-in themes

The built-in themes in Zellij can be used by setting the theme [THEME_NAME] in the configuration file. Take a look at the list of themes to see what's possible.

Since 0.46.0, the default theme has a new palette, and is paired with a new default-light theme. The theme that was called default before 0.46.0 is bundled as classic:

theme "classic"

Automatic dark and light theme switching

When none of theme, theme_dark and theme_light is set, Zellij switches automatically between the bundled default theme (when the host terminal is in dark mode) and default-light (when it is in light mode).

Other themes can be chosen for each mode:

theme_dark "catppuccin-mocha"
theme_light "catppuccin-latte"

How these options combine:

Zellij detects the color scheme of the terminal it is attached to (through DSR 997 replies and CSI 2031 change notifications) and switches themes when it changes. Terminals that do not report their color scheme will not trigger switching.

The theme can also be switched manually, with these actions (bindable in the keybinds block) and their CLI equivalents:

Programs running inside panes can subscribe to color scheme changes themselves with CSI ? 2031 h and will receive CSI ?997;1 n (dark) or CSI ?997;2 n (light) whenever the mode changes.

Overriding the terminal's reported hue

The explicit_theme_hue option pins the session to a dark or light appearance, ignoring what the host terminal reports:

explicit_theme_hue "dark"

It is resolved before the first render, so the session starts with the intended appearance instead of correcting itself once the terminal replies. This is useful for terminals that report the wrong color scheme, or that do not report one at all. When it is unset, the host terminal decides.

It only selects which of the dark and light themes applies, following the table above. When theme is set and switching is off, it has no effect.

Theme Definition Specification

Themes in Zellij are defined according to UI components. These components are used in the various plugins that make up the Zellij interface, and can also be used dynamically in user plugins.

Structure of a theme definition

Note: the easiest way to create or change a theme is the theme editor, which shows a preview of the colors and can fix colors that are hard to read. The structure below is what it writes to the theme file.

A theme definition is a KDL file (or part of one). It has a node named themes, with a node inside it named after the theme, and inside that a list of nodes defining the UI components:

themes {
    dracula {
        ribbon_unselected {
            base 0 0 0
            background 255 153 0
            emphasis_0 255 53 94
            emphasis_1 255 255 255
            emphasis_2 0 217 227
            emphasis_3 255 0 255
        }
    }
}

A full theme has one such node for each of the components listed below.

It can either be placed directly in the main configuration file or in a separate directory.

Theme UI Components

Components have the following attributes, each one including a space separated list of three numbers representing the RGB color. A color can also be given as a hex string (eg. "#ff8c00" or "#f80") or as a single number from the 256-color palette.

1. base - the base color of the component
2. background - the background color of the component
3. emphasis_0, emphasis_1, emphasis_2, emphasis_3 - the color of text emphases inside the text. These are used either to differentiate whole text components one from another (with each having a full color of one of the emphases), or even combined in a single component (eg. when indicating indices in fuzzy find results). Not all of these are used in the base UI, but they might be used in user plugins.

Following is the list of available component specifications:

text_unselected

This component refers to the bare text parts of the Zellij UI (for example, the Ctrl or Alt modifier indications in the status-bar).

text_selected

This component refers to the bare text parts of the Zellij UI when they need to indicate selection (eg. when paging through search results). This is often done by providing them a different color background than their unselected counterparts.

ribbon_unselected

Ribbons are used often in the Zellij UI, examples are the tabs and the keybinding modes in the status bar. Its emphasis colors (emphasis_0 to emphasis_3) color parts of the text inside unselected ribbons, eg. when a plugin highlights part of a ribbon's text with a color index. The color of hovered tabs is set by ribbon_hover.

ribbon_selected

Selected ribbons are often indicated with a different color than their unselected counterparts (eg. the focused tab, or the active keybinding mode in the status bar).

ribbon_hover

The colors of a ribbon that is hovered with the mouse, or shown as an alternate tab (the shading that tells neighboring tabs apart). This section is optional.

themes {
    my-theme {
        ribbon_hover {
            base 11 11 11
            background 220 220 220
            emphasis_0 79 26 34
            emphasis_1 60 20 70
            emphasis_2 20 49 79
            emphasis_3 99 11 20
        }
    }
}

The built-in bars use these colors as follows:

When a theme has no ribbon_hover section:

• If it has a ribbon_unselected section, the hover fill is ribbon_unselected's emphasis_1, and the other hover colors are taken from ribbon_unselected.
• If it has neither section, the built-in default hover colors are used.
• Legacy themes (written with fg, bg, red and so on) get the same emphasis_1 fallback.

All the built-in themes have a ribbon_hover section.

table_title

The table UI component has a different style applied to its title line than the rest of the table. This is what differentiates this line.

table_cell_unselected

The style of an unselected cell in a table. Cells can be specified as selected or unselected individually, but it is often the case that a full table line is specified to have selected or unselected cells.

table_cell_selected

Often differentiated from its unselected counterpart by changing its background color.

list_unselected

A line item in a nested list, it can be arbitrarily indented. Its indentation indication is not included in the item specification.

list_selected

Often differentiated from its unselected counterpart with a different background color.

frame_unselected

The frame around the other non-focused panes.

frame_selected

The frame around the focused pane.

frame_highlight

This is the frame around the focused pane when the user enters a mode other than the base mode (eg. PANE or TAB mode).

exit_code_success

The color of the exit code indication (here, only the base part of the specification is used, the rest are reserved for future use). These can be seen in command panes (eg. when using zellij run) after the command exited successfully.

exit_code_error

The color of the exit code indication (here, only the base part of the specification is used, the rest are reserved for future use). These can be seen in command panes (eg. when using zellij run) after the command exited with an error.

multiplayer_user_colors

This is the only theme section that is different from the rest of the UI components and is defined thus:

multiplayer_user_colors {
    player_1 255 0 255
    player_2 0 217 227
    player_3 0
    player_4 255 230 0
    player_5 0 229 229
    player_6 0
    player_7 255 53 94
    player_8 0
    player_9 0
    player_10 0
}

Each player represents the color given to a user joining (attaching) to an active session. These colors appear the same to all users and are given by order of attaching.

terminal_colors

A theme can also define the sixteen ANSI colors that programs use (eg. ls --color or a shell prompt). Any of the sixteen can be left out:

terminal_colors {
    black 33 34 44
    red 255 85 85
    green 80 250 123
    yellow 241 250 140
    blue 189 147 249
    magenta 255 121 198
    cyan 139 233 253
    white 248 248 242
    bright_black 98 114 164
    bright_red 255 110 110
    bright_green 105 255 148
    bright_yellow 255 255 165
    bright_blue 214 172 255
    bright_magenta 255 146 223
    bright_cyan 164 255 255
    bright_white 255 255 255
}

These colors must be given as RGB or as a hex string, not as a number from the 256-color palette.

They are only used by the Zellij terminal window, which paints these colors itself. Inside another terminal emulator, that terminal's own colors are used. The theme section of the terminal block takes priority over them. Most of the built-in themes include this section.

The theme editor

Themes can be created and edited from inside Zellij, without editing files by hand, in the theme editor of the settings screen (Settings → Appearance → Themes).

• Creating a theme: a adds a new theme. Built-in themes and themes from the themes folder are read-only: copy one to start from it.
• Editing colors: Enter opens the colors of the selected theme. Enter and the arrow keys move between colors, which can be typed as #rrggbb, rrggbb, r g b or a number from the 256-color palette. Ctrl a applies the changes.
• Previewing: a sample of the Zellij interface drawn with the theme's colors is shown next to them (when the pane is wide enough). When the theme being edited is the active one, the whole of Zellij changes along with it.
• Hover colors: the editor has a row for each of the six ribbon_hover colors, and the preview shows a "Hover" ribbon next to "Tab" and "Active". When a theme without a ribbon_hover section is opened, these rows are filled with the colors the theme currently uses for hover, and saving writes the section to the theme.
• Fixing contrast: colors that are hard to read against their background are pointed out. Most text colors are checked against a contrast of 3:1. The emphasis_1 and emphasis_2 colors of ribbons are checked against their ribbon's background, and the hover text colors against the hover fill, at 4.5:1. Ctrl f raises the contrast of the selected color to its target. Ctrl e fixes every color below 3:1, changing each color only as much as needed; colors between 3:1 and 4.5:1 are marked but left for Ctrl f.
• Managing themes: n renames a theme, Del deletes it, r reverts unsaved changes and / searches the list.

Getting Zellij to pick up the theme

While developing and iterating over a theme, the easiest way would be to define it directly in the main configuration file (add the themes block defined above with your theme) and then set the:

theme "your_theme_name"

directive above or below it. This way, Zellij will pick up on any changes to the theme in real time and you will not have to restart the session to see your changes.

Otherwise, it's possible to define themes in separate files under the themes folder located in CONFIG_DIR/themes. You can find the exact location of this folder with zellij setup --check. Changes to files in this folder are also picked up live, without restarting the session. This also works when the folder is created after Zellij started. A different folder can be set with the theme_dir option.

Themes can also be loaded from the command line when starting Zellij:

zellij options --theme [NAME]

Example Themes

Here are some example themes these are the themes that come built-in with Zellij and can be freely used for inspiration and to kick off your own theme definition.

List of Themes

These themes are provided built-in with Zellij. One can switch to them by changing the theme configuration option

When no theme is set, Zellij uses default when the host terminal is in dark mode and default-light when it is in light mode. See automatic dark and light theme switching.

Dark Themes

• default
• classic (the default theme before 0.46.0)
• ansi
• ao
• atelier-sulphurpool
• ayu-mirage
• ayu-dark
• blade-runner
• catppuccin-frappe
• catppuccin-macchiato
• catppuccin-mocha
• cyber-noir
• dracula
• everforest-dark
• flexoki-dark
• gruber-darker
• gruvbox-dark
• iceberg-dark
• kanagawa
• lucario
• menace
• molokai-dark
• night-owl
• nightfox
• nord
• one-half-dark
• onedark
• retro-wave
• solarized-dark
• terafox
• tokyo-night-dark
• tokyo-night-storm
• tokyo-night
• vesper

Light Themes

• default-light
• ayu-light
• catppuccin-latte
• dayfox
• everforest-light
• gruvbox-light
• iceberg-light
• pencil-light
• solarized-light
• tokyo-night-light

Legacy Themes

This file defines the original Zellij theme specification. It is still supported, but new themes should be written in the new spec defined at the root of this section.

The colors named black, red and so on in this format color the Zellij interface. They do not set the ANSI colors of the Zellij terminal window. A legacy theme can also contain a terminal_colors section for that.

The colors of hovered and alternate tabs in a legacy theme are worked out the same way as for a theme without a ribbon_hover section.

Truecolor themes

themes {
   dracula {
        fg 248 248 242
        bg 40 42 54
        black 0 0 0
        red 255 85 85
        green 80 250 123
        yellow 241 250 140
        blue 98 114 164
        magenta 255 121 198
        cyan 139 233 253
        white 255 255 255
        orange 255 184 108
    }
}

256 color themes

themes {
    my-256-color-theme {
        fg 1
        bg 10
        black 20
        red 30
        green 40
        yellow 50
        blue 60
        magenta 70
        cyan 80
        white 90
        orange 254
    }
}

Hexadecimal color themes

themes {
    nord {
        fg "#D8DEE9"
        bg "#2E3440"
        black "#3B4252"
        red "#BF616A"
        green "#A3BE8C"
        yellow "#EBCB8B"
        blue "#81A1C1"
        magenta "#B48EAD"
        cyan "#88C0D0"
        white "#E5E9F0"
        orange "#D08770"
    }
}

Command Line Configuration Options

In addition to the configuration file, zellij can also be configured through the command line when running it. These options will override options in the configuration file.

Migration Note: The --disable-mouse-mode and --no-pane-frames flags have been removed. Use --mouse-mode false (equivalent of --disable-mouse-mode) and --pane-frames false (equivalent of --no-pane-frames) instead.

Every top-level option that can be set in the configuration file also has a corresponding flag here (settings inside blocks, such as ui, env, web_client, terminal, attention, context_menu and session_suggestions, do not), in nearly all cases using the same name in kebab-case (eg. the nested_session_handling option is --nested-session-handling). The exceptions are the web server options (web_server_ip, web_server_port, web_server_cert, web_server_key, enforce_https_for_localhost, dangerously_allow_web_serving_without_a_certificate), which are taken as positional arguments rather than flags.

Note: since 0.45.0 (which uses clap 4 for argument parsing), repeating the same flag no longer produces an error - the last occurrence overrides the previous ones. Help output is also styled and colored.

A keybinding preset can be chosen for a single session with --keybinds-preset (a name from the keybinds folder, a built-in preset, or a path to a preset file), together with --keybinds-primary, --keybinds-secondary and --keybinds-unlock to change its keys:

$ zellij options --keybinds-preset unlock-first --keybinds-unlock "Ctrl a"

The listing below is the output of zellij options --help. A shorter summary is available with zellij options -h.

Change the behaviour of zellij

Usage: zellij options [OPTIONS] [WEB_SERVER_IP] [WEB_SERVER_PORT] [WEB_SERVER_CERT] [WEB_SERVER_KEY] [ENFORCE_HTTPS_FOR_LOCALHOST] [DANGEROUSLY_ALLOW_WEB_SERVING_WITHOUT_A_CERTIFICATE]

Arguments:
  [WEB_SERVER_IP]


  [WEB_SERVER_PORT]


  [WEB_SERVER_CERT]


  [WEB_SERVER_KEY]


  [ENFORCE_HTTPS_FOR_LOCALHOST]
          [possible values: true, false]

  [DANGEROUSLY_ALLOW_WEB_SERVING_WITHOUT_A_CERTIFICATE]
          [possible values: true, false]

Options:
      --simplified-ui <SIMPLIFIED_UI>
          Allow plugins to use a more simplified layout that is compatible with more fonts (true or false)

          [possible values: true, false]

      --theme <THEME>
          Set the default theme

      --theme-dark <THEME_DARK>
          Theme name to apply when the host terminal reports a dark color palette (CSI 2031 / DSR 997). Requires
          `theme_light` to also be set; if either is missing the static `theme` remains authoritative

      --theme-light <THEME_LIGHT>
          Theme name to apply when the host terminal reports a light color palette (CSI 2031 / DSR 997). Requires
          `theme_dark` to also be set; if either is missing the static `theme` remains authoritative

      --explicit-theme-hue <EXPLICIT_THEME_HUE>
          Pin the session to a dark or light appearance ("dark" or "light"), resolved before the first render and kept
          authoritative over ambient host terminal reports (CSI 2031 / DSR 997). When unset, the session follows the
          host terminal

      --default-mode <DEFAULT_MODE>
          Set the default mode

      --default-shell <DEFAULT_SHELL>
          Set the default shell

      --default-cwd <DEFAULT_CWD>
          Set the default cwd

      --default-layout <DEFAULT_LAYOUT>
          Set the default layout

      --layout-dir <LAYOUT_DIR>
          Set the layout_dir, defaults to subdirectory of config dir

      --theme-dir <THEME_DIR>
          Set the theme_dir, defaults to subdirectory of config dir

      --keybinds-dir <KEYBINDS_DIR>
          Set the keybinds_dir, defaults to subdirectory of config dir

      --keybinds-preset <KEYBINDS_PRESET>
          Use this keybinding preset for this session: a name from the keybinds folder, a built-in preset, or a path to
          a preset file

      --keybinds-primary <KEYBINDS_PRIMARY>
          The primary leader key for the keybinding preset (for example "Ctrl")

      --keybinds-secondary <KEYBINDS_SECONDARY>
          The secondary leader key for the keybinding preset (for example "Alt")

      --keybinds-unlock <KEYBINDS_UNLOCK>
          The unlock key for the keybinding preset (for example "Ctrl g")

      --mouse-mode <MOUSE_MODE>
          Set the handling of mouse events (true or false) Can be temporarily bypassed by the [SHIFT] key

          [possible values: true, false]

      --pane-frames <PANE_FRAMES>
          Set display of the pane frames (true or false)

          [possible values: true, false]

      --pane-frame-style <PANE_FRAME_STYLE>


      --mirror-session <MIRROR_SESSION>
          Mirror session when multiple users are connected (true or false)

          [possible values: true, false]

      --on-force-close <ON_FORCE_CLOSE>
          Set behaviour on force close (quit or detach)

      --scroll-buffer-size <SCROLL_BUFFER_SIZE>


      --copy-command <COPY_COMMAND>
          Switch to using a user supplied command for clipboard instead of OSC52

      --copy-clipboard <COPY_CLIPBOARD>
          OSC52 destination clipboard

          [possible values: system, primary]

      --copy-on-select <COPY_ON_SELECT>
          Automatically copy when selecting text (true or false)

          [possible values: true, false]

      --osc8-hyperlinks <OSC8_HYPERLINKS>
          Enable OSC8 hyperlink output (true or false)

          [possible values: true, false]

      --scrollback-editor <SCROLLBACK_EDITOR>
          Explicit full path to open the scrollback editor (default is $EDITOR or $VISUAL)

      --session-name <SESSION_NAME>
          The name of the session to create when starting Zellij

      --attach-to-session <ATTACH_TO_SESSION>
          Whether to attach to a session specified in "session-name" if it exists

          [possible values: true, false]

      --auto-layout <AUTO_LAYOUT>
          Whether to lay out panes in a predefined set of layouts whenever possible

          [possible values: true, false]

      --session-serialization <SESSION_SERIALIZATION>
          Whether sessions should be serialized to the HD so that they can be later resurrected, default is true

          [possible values: true, false]

      --serialize-pane-viewport <SERIALIZE_PANE_VIEWPORT>
          Whether pane viewports are serialized along with the session, default is false

          [possible values: true, false]

      --scrollback-lines-to-serialize <SCROLLBACK_LINES_TO_SERIALIZE>
          Scrollback lines to serialize along with the pane viewport when serializing sessions, 0 defaults to the
          scrollback size. If this number is higher than the scrollback size, it will also default to the scrollback
          size

      --styled-underlines <STYLED_UNDERLINES>
          Whether to use ANSI styled underlines

          [possible values: true, false]

      --serialization-interval <SERIALIZATION_INTERVAL>
          The interval at which to serialize sessions for resurrection (in seconds)

      --disable-session-metadata <DISABLE_SESSION_METADATA>
          If true, will disable writing session metadata to disk

          [possible values: true, false]

      --support-kitty-keyboard-protocol <SUPPORT_KITTY_KEYBOARD_PROTOCOL>
          Whether to enable support for the Kitty keyboard protocol (must also be supported by the host terminal),
          defaults to true if the terminal supports it

          [possible values: true, false]

      --support-kitty-graphics-protocol <SUPPORT_KITTY_GRAPHICS_PROTOCOL>
          Whether to enable support for the Kitty graphics (image) protocol (must also be supported by the host
          terminal), defaults to true if the terminal supports it

          [possible values: true, false]

      --grapheme-clusters <GRAPHEME_CLUSTERS>
          Count each grapheme cluster (an emoji sequence, a letter with its accents) as one unit of width, as the
          Unicode standard does (true or false, default true). When false, widths are counted per code point and
          programs may still ask for clusters with mode 2027

          [possible values: true, false]

      --mirror-resizes-source-pane <MIRROR_RESIZES_SOURCE_PANE>
          Whether a focused mirror of a pane may resize that pane's program to the mirror's size, and whether new
          mirrors resize their source pane by default (true or false, default true)

          [possible values: true, false]

      --live-view-release-key <LIVE_VIEW_RELEASE_KEY>
          An extra key that gives typing back to a plugin while a live pane view inside it is taking the keyboard
          (default: none, Alt Enter, the inbox key or a click outside always do it; a key written twice means pressing
          it twice)

      --web-server <WEB_SERVER>
          Whether to make sure a local web server is running when a new Zellij session starts. This web server will
          allow creating new sessions and attaching to existing ones that have opted in to being shared in the browser.

          Note: a local web server can still be manually started from within a Zellij session or from the CLI. If this
          is not desired, one can use a version of Zellij compiled without web_server_capability

          Possible values: - true - false Default: false

          [possible values: true, false]

      --web-sharing <WEB_SHARING>
          Whether to allow new sessions to be shared through a local web server, assuming one is running (see the
          `web_server` option for more details).

          Note: if Zellij was compiled without web_server_capability, this option will be locked to "disabled"

          Possible values: - "on" (new sessions will allow web sharing through the local web server if it is online) -
          "off" (new sessions will not allow web sharing unless they explicitly opt-in to it) - "disabled" (new sessions
          will not allow web sharing and will not be able to opt-in to it) Default: "off"

          [possible values: on, off, disabled]

      --stacked-resize <STACKED_RESIZE>
          Whether to stack panes when resizing beyond a certain size default is true

          [possible values: true, false]

      --stacked-pane-list <STACKED_PANE_LIST>
          [possible values: true, false]

      --stacked-pane-list-orientation <STACKED_PANE_LIST_ORIENTATION>
          Whether new stacks show their titles in a column (vertical) or in a row (horizontal) default is vertical

      --show-startup-tips <SHOW_STARTUP_TIPS>
          Whether to show startup tips when starting a new session default is true

          [possible values: true, false]

      --show-release-notes <SHOW_RELEASE_NOTES>
          Whether to show release notes on first run of a new version default is true

          [possible values: true, false]

      --advanced-mouse-actions <ADVANCED_MOUSE_ACTIONS>
          Whether to enable mouse hover effects and pane grouping functionality default is true

          [possible values: true, false]

      --mouse-scroll-resize <MOUSE_SCROLL_RESIZE>
          Whether Ctrl+ScrollWheel resizes panes default is true

          [possible values: true, false]

      --scroll-mode-sync <SCROLL_MODE_SYNC>
          Whether scrolling a pane implicitly enters (and leaving the scroll implicitly exits) Scroll mode default is
          true

          [possible values: true, false]

      --mouse-hover-effects <MOUSE_HOVER_EFFECTS>
          Whether to enable mouse hover visual effects (frame highlight and help text) default is true

          [possible values: true, false]

      --mouse-hover-tips <MOUSE_HOVER_TIPS>
          Whether to show mouse hover help-text tips (resize help and group shortcuts) default is true

          [possible values: true, false]

      --visual-bell <VISUAL_BELL>
          Whether to show visual bell indicators (pane/tab frame flash and [!] suffix) default is true

          [possible values: true, false]

      --focus-follows-mouse <FOCUS_FOLLOWS_MOUSE>
          Whether to focus panes on mouse hover (true or false) default is false

          [possible values: true, false]

      --mouse-click-through <MOUSE_CLICK_THROUGH>
          Whether clicking a pane to focus it also sends the click into the pane (true or false) default is false

          [possible values: true, false]

      --context-menu-enabled <CONTEXT_MENU_ENABLED>
          Whether a right click opens the right-click menu (true or false), default is true

          [possible values: true, false]

      --osc133-command-selection <OSC133_COMMAND_SELECTION>
          Whether triple-clicking inside shell-marked (OSC 133) command output selects the command and its output rather
          than the logical line default is true

          [possible values: true, false]

      --word-separators <WORD_SEPARATORS>
          Characters that terminate a word when double-clicking to select it, in addition to whitespace (which is always
          a separator) default is "[]{}<>()"

      --host-notification-protocol <HOST_NOTIFICATION_PROTOCOL>
          [possible values: auto, osc9, osc99, bell, off]

      --post-command-discovery-hook <POST_COMMAND_DISCOVERY_HOOK>
          A command to run after the discovery of running commands when serializing, for the purpose of manipulating the
          command (eg. with a regex) before it gets serialized

      --client-async-worker-tasks <CLIENT_ASYNC_WORKER_TASKS>
          Number of background threads used by `zellij attach <url>` when it connects to a session on another machine.
          One set is made for that program, not one per client; the web server, browser clients and local sessions are
          not affected.

          Most of the work runs on the main thread, so these threads are usually idle. Set to 0 to use the number of
          (physical) CPU cores.

      --nested-session-handling <NESTED_SESSION_HANDLING>
          How to handle a nested Zellij session detected inside a pane (ask, fullscreen, descend, never)

      --dangerously-enable-paste-buffer-read <DANGEROUSLY_ENABLE_PASTE_BUFFER_READ>
          [possible values: true, false]

      --session-indicator <SESSION_INDICATOR>
          Whether to show the other sessions indicator in the tab bar and compact bar (true or false), default is true

          [possible values: true, false]

      --swap-layout-notification <SWAP_LAYOUT_NOTIFICATION>
          Whether to briefly show the new swap layout name when it is changed (true or false), default is true

          [possible values: true, false]

      --on-quit <ON_QUIT>
          What the quit action does: ask_quit (ask, Quit preselected), ask_detach (ask, Detach preselected), quit or
          detach. Default is ask_quit

          [possible values: ask_quit, ask_detach, quit, detach]

      --bars-hidden-on-start <BARS_HIDDEN_ON_START>
          Which bars a new session starts with hidden: bar names separated by commas (eg. tab-bar,status-bar), all or
          none. Default is none

      --hidden-bars-notification <HIDDEN_BARS_NOTIFICATION>
          Whether to briefly show what was hidden and how to show it again when bars are hidden (true or false), default
          is true

          [possible values: true, false]

      --mode-hints-when-bars-hidden <MODE_HINTS_WHEN_BARS_HIDDEN>
          Whether to show the current mode's keys in a corner while a bar that would show them is hidden (true or
          false), default is true

          [possible values: true, false]

  -h, --help
          Print help (see a summary with '-h')

Controlling Zellij through the CLI

Zellij can be controlled through the CLI. Whether inside or outside a zellij session, one can issue commands from the terminal to interact with any session running on the machine.

eg.

$ zellij action new-pane

Commands can also be issued to a different Zellij session:

$ zellij --session pretentious-cat action new-pane

• Zellij Run & Edit - Launch commands in new panes or open files in your default editor
• Zellij Action - Full reference of all zellij action subcommands for controlling panes, tabs, layouts, and more
• Zellij Plugin & Pipe - Load plugins and send data to them from the command line
• Zellij Subscribe - Stream the rendered output of one or more panes to stdout in real time
• Zellij Prompt - Ask the user a question, a choice or a value in a popup and print the answer
• Zellij Watch - Watch a session in read-only mode
• CLI Recipes & Scripting - Task-oriented examples and common workflows for scripting with Zellij
• Programmatic Control - Patterns for non-interactive, machine-driven control of Zellij sessions

Zellij Watch

The zellij watch command provides a read-only view of a session:

$ zellij watch my-session-name

This attaches to the specified session in read-only mode - the terminal output is visible but no input can be sent.

The same read-only view can be opened in the Zellij terminal window with zellij terminal --watch my-session-name (see Zellij Terminal).

Completions

For convenience, zellij provides cli completions for popular shells.

You can dump these completions to STDOUT and then append them to your shell's configuration file with:

$ zellij setup --generate-completion fish
$ zellij setup --generate-completion bash
$ zellij setup --generate-completion zsh

These completions also include aliases for running a command in a new pane and editing a file in a new pane:

$ zr tail -f /path/to/my/file # open a new pane tailing this file
$ zrf htop # open a new floating pane with htop
$ ze ./main.rs # open a new pane with your editor (eg. vim) pointed at ./main.rs

See your shell's documentation for information on where to append these.

The fish completions additionally complete session names for zellij attach, zellij kill-session and zellij delete-session (as well as their aliases, eg. d).

Zellij Run & Edit

• Zellij Run - Launch a command in a new pane with options for floating, blocking, and more
• Zellij Edit - Open a file in your default editor in a new pane

Zellij Run

Zellij includes a top-level run command that can be used to launch a new Zellij pane running a specific command:

eg.

$ zellij run -- git diff
$ zellij run --notify -- cargo build

OPTIONS:

-b, --borderless <BORDERLESS>     start this pane without a border (warning: will make it
                                  impossible to move with the mouse) [possible values: true,
                                  false]
    --border-style <BORDER_STYLE> Border line style, eg. "double" or
                                  "top:double,left:single,rounded"
    --block-until-exit            Block until the command exits (regardless of exit status) OR
                                  its pane has been closed
    --block-until-exit-failure    Block until the command exits with failure (non-zero exit
                                  status) OR its pane has been closed
    --block-until-exit-success    Block until the command exits successfully (exit status 0) OR
                                  its pane has been closed
    --blocking                    Block until the command has finished and its pane has been
                                  closed
-c, --close-on-exit               Close the pane immediately when its command exits
    --close-replaced-pane         Close the replaced pane instead of suspending it (only
                                  effective with --in-place)
    --cwd <CWD>                   Change the working directory of the new pane
-d, --direction <DIRECTION>       Direction to open the new pane in
-f, --floating                    Open the new pane in floating mode
-h, --help                        Print help information
    --height <HEIGHT>             The height if the pane is floating as a bare integer (eg. 1)
                                  or percent (eg. 10%)
-i, --in-place                    Open the new pane in place of the current pane, temporarily
                                  suspending it
-n, --name <NAME>                 Name of the new pane
    --near-current-pane           if set, will open the pane near the current one rather than
                                  following the user's focus
    --no-focus                    Open the pane without changing the focus of any client
    --notify                      Watch the pane: notify each time its command finishes or its
                                  output goes quiet, until the watch is turned off
    --pinned <PINNED>             Whether to pin a floating pane so that it is always on top
-s, --start-suspended             Start the command suspended, only running after you first
                                  presses ENTER
    --stacked
    --tab-id <TAB_ID>             Open the pane in the tab with this id (conflicts with
                                  --in-place and --near-current-pane)
    --width <WIDTH>               The width if the pane is floating as a bare integer (eg. 1) or
                                  percent (eg. 10%)
-x, --x <X>                       The x coordinates if the pane is floating as a bare integer
                                  (eg. 1) or percent (eg. 10%)
-y, --y <Y>                       The y coordinates if the pane is floating as a bare integer
                                  (eg. 1) or percent (eg. 10%)

Note: to shorten this command to a more friendly length, see Completions under: CLI

About --no-focus: the pane is opened without changing the focus of any connected client. Its placement is relative to the pane the command was issued from rather than to the focused pane. This is useful for scripts that open panes in the background.

About --notify: the pane is watched as with zellij action watch-pane: a notification is sent each time its command finishes or its output goes quiet, until the watch is turned off. See the inbox.

About --border-style: sets the line style of the pane's border. The format is described under set-pane-border-style.

About --tab-id: the pane is opened in the tab with the given (numeric) id rather than in the focused tab. Tab ids can be obtained with zellij action list-tabs or zellij action query-tab-names.

This new pane will not immediately close when the command exits. Instead, it will show its exit status on the pane frame and allow users to press <ENTER> to re-run the command inside the same pane, or <Ctrl-c> to close the pane.

We feel this is a new and powerful way to interact with the command line.

Zellij Edit

It's possible to open your default editor pointed at a file in a new Zellij pane.

This can be useful to save time instead of opening a new pane and starting your default editor inside it manually.

eg.

$ zellij edit ./main.rs # open main.rs in a new pane
$ zellij edit --floating ./main.rs # open main.rs in a new floating pane
$ zellij edit ./main.rs --line-number 10 # open main.rs pointed at line number 10

Possible Options:

-b, --borderless <BORDERLESS>      start this pane without a border (warning: will make it
                                   impossible to move with the mouse) [possible values: true,
                                   false]
    --border-style <BORDER_STYLE>  Border line style, eg. "double" or
                                   "top:double,left:single,rounded"
    --close-replaced-pane          Close the replaced pane instead of suspending it (only
                                   effective with --in-place)
    --cwd <CWD>                    Change the working directory of the editor
-d, --direction <DIRECTION>        Direction to open the new pane in
-f, --floating                     Open the new pane in floating mode
-h, --help                         Print help information
    --height <HEIGHT>              The height if the pane is floating as a bare integer (eg. 1)
                                   or percent (eg. 10%)
-i, --in-place                     Open the new pane in place of the current pane, temporarily
                                   suspending it
-l, --line-number <LINE_NUMBER>    Open the file in the specified line number
    --near-current-pane            if set, will open the pane near the current one rather than
                                   following the user's focus
    --no-focus                     Open the pane without changing the focus of any client
    --pinned <PINNED>              Whether to pin a floating pane so that it is always on top
    --tab-id <TAB_ID>              Open the pane in the tab with this id (conflicts with
                                   --in-place and --near-current-pane)
    --width <WIDTH>                The width if the pane is floating as a bare integer (eg. 1)
                                   or percent (eg. 10%)
-x, --x <X>                        The x coordinates if the pane is floating as a bare integer
                                   (eg. 1) or percent (eg. 10%)
-y, --y <Y>                        The y coordinates if the pane is floating as a bare integer
                                   (eg. 1) or percent (eg. 10%)

About --border-style: see set-pane-border-style for the format.

Note: The default editor is anything set in $EDITOR or $VISUAL - alternatively, it can be set explicitly with the scrollback_editor configuration option.

Another Note: To shorten this command, see Cli Completions

CLI Actions

A note about pane ids: Since terminal panes and plugin panes can have overlapping IDs, they are differentiated by prefixing the pane type, eg. terminal_1 is a different pane than plugin_1. The ID of terminal panes is the same one that can be discovered through the ZELLIJ_PANE_ID environment variable. When a --pane-id flag accepts a pane id, it can be specified as terminal_1, plugin_2, or just 3 (equivalent to terminal_3).

• apply-floating-swap-layout
• apply-tiled-swap-layout
• are-floating-panes-visible
• change-floating-pane-coordinates
• clear
• close-pane
• close-tab
• close-tab-by-id
• current-tab-info
• detach
• dismiss-info-popups
• dump-layout
• dump-screen
• edit
• edit-scrollback
• focus-last-pane
• focus-next-pane
• focus-pane-id
• focus-previous-pane
• go-to-next-attention
• go-to-next-session
• go-to-next-tab
• go-to-previous-session
• go-to-previous-tab
• go-to-tab
• go-to-tab-by-id
• go-to-tab-name
• half-page-scroll-down
• half-page-scroll-up
• hide-bars
• hide-floating-panes
• ignore-pane-output
• launch-or-focus-plugin
• launch-plugin
• list-clients
• list-panes
• list-tabs
• mark-all-seen
• mark-pane-seen
• move-focus
• move-focus-or-tab
• move-pane
• move-pane-backwards
• move-tab
• mute-pane
• mute-session
• mute-tab
• new-pane
• new-tab
• next-swap-layout
• open-context-menu
• override-layout
• page-scroll-down
• page-scroll-up
• paste
• pipe
• previous-swap-layout
• query-tab-names
• rename-pane
• rename-session
• rename-tab
• rename-tab-by-id
• resize
• save-session
• scroll-down
• scroll-to-bottom
• scroll-to-top
• scroll-up
• send-keys
• set-dark-theme
• set-light-theme
• set-pane-border-style
• set-pane-borderless
• set-pane-color
• set-pane-frame-style
• set-resurrect-command
• show-bars
• show-floating-panes
• stack-panes
• start-or-reload-plugin
• switch-mode
• switch-session
• toggle-active-sync-tab
• toggle-bars
• toggle-floating-panes
• toggle-fullscreen
• toggle-mirror-resize
• toggle-no-ui-fullscreen
• toggle-pane-borderless
• toggle-pane-embed-or-floating
• toggle-pane-frames
• toggle-pane-pinned
• toggle-session
• toggle-stack-list-orientation
• toggle-theme
• toggle-tray-icon
• undo-rename-pane
• undo-rename-tab
• watch-pane
• write
• write-chars

apply-floating-swap-layout

Apply the floating swap layout with the given name. The visibility of floating panes and the focus are left unchanged. Exits with status 1 if no floating swap layout with that name fits the current number of panes.

ARGS: The name of the floating swap layout, as declared in the layout file

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by ID

eg.

$ zellij action apply-floating-swap-layout spread
$ zellij action apply-floating-swap-layout spread --tab-id 3

apply-tiled-swap-layout

Apply the tiled swap layout with the given name. The visibility of floating panes and the focus are left unchanged. Exits with status 1 if no tiled swap layout with that name fits the current number of panes.

Unlike next-swap-layout, which moves through the swap layouts in order, this selects one directly.

ARGS: The name of the tiled swap layout, as declared in the layout file (eg. swap_tiled_layout name="vertical")

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by ID

eg.

$ zellij action apply-tiled-swap-layout vertical
$ zellij action apply-tiled-swap-layout stacked --tab-id 3

are-floating-panes-visible

Check if floating panes are visible in the specified tab (or active tab). Prints "true" to stdout and exits 0 if visible. Prints "false" to stdout and exits 1 if not visible.

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by ID

eg.

$ zellij action are-floating-panes-visible
$ zellij action are-floating-panes-visible --tab-id 3

change-floating-pane-coordinates

Given a pane id, and coordinates, will change the coordinates of this pane.

ARGS: The pane id (see example below - these can be discovered through the $ZELLIJ_PANE_ID env var) OPTIONS:

    -b, --borderless <BORDERLESS>  Change the border state of the pane
        --border-style <STYLE>     Border line style, eg. "double" or "top:double,left:single,rounded"
        --height <HEIGHT>          The height if the pane is floating as a bare integer (eg. 1) or
                                   percent (eg. 10%)
    -p, --pane-id <PANE_ID>        The pane_id of the floating pane, eg.  terminal_1, plugin_2 or 3
                                   (equivalent to terminal_3)
        --pinned <PINNED>          Whether to pin a floating pane so that it is always on top
        --width <WIDTH>            The width if the pane is floating as a bare integer (eg. 1) or
                                   percent (eg. 10%)
    -x, --x <X>                    The x coordinates if the pane is floating as a bare integer (eg. 1)
                                   or percent (eg. 10%)
    -y, --y <Y>                    The y coordinates if the pane is floating as a bare integer (eg. 1)
                                   or percent (eg. 10%)

eg.

zellij action change-floating-pane-coordinates --pane-id terminal_15 --height 10 --width 10 -x 10 -y 10
zellij action change-floating-pane-coordinates --pane-id terminal_15 --border-style double

The format of --border-style is described under set-pane-border-style.

clear

Clear all buffers for a focused pane

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID (eg. terminal_1, plugin_2 or 3)

eg.

$ zellij action clear
$ zellij action clear --pane-id terminal_3

close-pane

Close the focused pane

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID (eg. terminal_1, plugin_2 or 3)

eg.

$ zellij action close-pane
$ zellij action close-pane --pane-id terminal_3

close-tab

Close the current tab

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by stable ID

eg.

$ zellij action close-tab
$ zellij action close-tab --tab-id 5

close-tab-by-id

Close a tab by its stable ID

ARGS: The tab ID (integer)

eg.

$ zellij action close-tab-by-id 5

current-tab-info

Get information about the currently active tab. Returns the tab name and ID by default.

OPTIONS:

    -j, --json    Output as JSON with full TabInfo

eg.

$ zellij action current-tab-info

Sample output:

name: Tab #1
id: 0
position: 0

With --json:

$ zellij action current-tab-info --json

Sample output:

{
  "position": 0,
  "name": "Tab #1",
  "active": true,
  "panes_to_hide": 0,
  "is_fullscreen_active": false,
  "is_sync_panes_active": false,
  "are_floating_panes_visible": false,
  "other_focused_clients": [],
  "active_swap_layout_name": "default",
  "is_swap_layout_dirty": false,
  "viewport_rows": 24,
  "viewport_columns": 80,
  "display_area_rows": 26,
  "display_area_columns": 80,
  "selectable_tiled_panes_count": 2,
  "selectable_floating_panes_count": 0,
  "tab_id": 0,
  "has_bell_notification": false,
  "is_flashing_bell": false
}

detach

Detach from the current session, leaving it running in the background

eg.

$ zellij action detach

dismiss-info-popups

Close the information popups that do not take the keyboard, such as the notices opened by zellij prompt notify.

eg.

$ zellij action dismiss-info-popups

dump-layout

Dumps the current Layout of the session to STDOUT

eg.

$ zellij action dump-layout

dump-screen

Dumps the viewport of a pane to a file or to STDOUT. Optionally includes the full scrollback.

OPTIONS:

        --path <PATH>          File path to dump content to (if omitted, prints to STDOUT)
    -f, --full                 Dump the pane with full scrollback
    -p, --pane-id <PANE_ID>    Target a specific pane by ID (if not specified, dumps the focused pane)
    -a, --ansi                 Preserve ANSI styling in the dump output

eg.

$ zellij action dump-screen --path /tmp/screen-dump.txt
$ zellij action dump-screen --full --ansi
$ zellij action dump-screen --pane-id terminal_3 --full

edit

Open the specified file in a new zellij pane with your default EDITOR. Returns the created pane ID.

ARGS: The path to the file to open (eg. /tmp/my-file.rs)

OPTIONS:

    -d, --direction <DIRECTION>    Direction to open [right|down] (conflicts with --floating)
    -f, --floating                 Open in floating mode
    -i, --in-place                 Open in place of the focused pane
        --close-replaced-pane      Close the replaced pane instead of suspending (requires --in-place)
    -l, --line-number <LINE_NUMBER>
        --cwd <CWD>               Working directory for the editor pane
    -x, --x <X>                    X coordinate for floating pane (requires --floating)
    -y, --y <Y>                    Y coordinate for floating pane (requires --floating)
        --width <WIDTH>            Width for floating pane (requires --floating)
        --height <HEIGHT>          Height for floating pane (requires --floating)
        --pinned <PINNED>          Pin the floating pane (requires --floating)
        --near-current-pane        Open near the current pane rather than following focus
        --no-focus                 Open the pane without changing the focus of any client
        --tab-id <TAB_ID>         Target a specific tab by ID (conflicts with --in-place, --near-current-pane)
    -b, --borderless <BORDERLESS>  Start without a border
        --border-style <STYLE>     Border line style, eg. "double" or "top:double,left:single,rounded"

eg.

$ zellij action edit ./my-file.rs -f
$ zellij action edit ./my-file.rs --in-place
$ zellij action edit ./my-file.rs -f --border-style "heavy,rounded"

The format of --border-style is described under set-pane-border-style.

Note: it is also possible to issue this action without the action prefix:

eg.

$ zellij edit ./my-file.rs -f

edit-scrollback

Open the pane scrollback in your default editor

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID
    -a, --ansi                 Preserve ANSI styling in the scrollback dump

eg.

$ zellij action edit-scrollback
$ zellij action edit-scrollback --pane-id terminal_3 --ansi

focus-last-pane

Change focus back to the pane that was focused before the currently focused one. Works across floating and tiled panes, and swaps the pane in place when the focused pane is fullscreen.

eg.

$ zellij action focus-last-pane

focus-next-pane

Change focus to the next pane

eg.

$ zellij action focus-next-pane

focus-pane-id

Focus a specific pane by its ID.

ARGS: The pane ID (eg. terminal_1, plugin_2, or 3 which is equivalent to terminal_3)

eg.

$ zellij action focus-pane-id terminal_1
$ zellij action focus-pane-id 3

focus-previous-pane

Change focus to the previous pane

eg.

$ zellij action focus-previous-pane

go-to-next-attention

Jump to the next pane that needs attention in any running session, switching session if needed. See the inbox for how panes come to need attention.

eg.

$ zellij action go-to-next-attention

go-to-next-session

Go forward in this client's session history (the sessions it switched between). Use after go-to-previous-session.

eg.

$ zellij action go-to-next-session

go-to-next-tab

Go to the next tab

eg.

$ zellij action go-to-next-tab

go-to-previous-session

Go back to the previous session in this client's session history (the sessions it switched between).

eg.

$ zellij action go-to-previous-session

go-to-previous-tab

Go to the previous tab

eg.

$ zellij action go-to-previous-tab

go-to-tab

Go to tab with index [index]

ARGS: The tab index (eg. 1)

eg.

$ zellij action go-to-tab 1

go-to-tab-by-id

Go to a tab by its stable ID

ARGS: The tab ID (integer)

eg.

$ zellij action go-to-tab-by-id 5

go-to-tab-name

Go to tab with name [name]. When --create is used and a tab is created, outputs the new tab ID.

ARGS: The tab name (eg. "Tab #1")

OPTIONS:

    -c, --create        Create a tab if one does not exist

eg.

$ zellij action go-to-tab-name "Tab #1"

half-page-scroll-down

Scroll down half page in focus pane

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action half-page-scroll-down

half-page-scroll-up

Scroll up half page in focus pane

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action half-page-scroll-up

hide-bars

Hide UI bars (eg. the tab-bar and status-bar) in every tab of the session. The bars can be shown again with show-bars or toggle-bars.

ARGS (optional): The bars to hide: tab-bar, status-bar, compact-bar, a plugin alias or plugin location, or all. If none are given, all bars are hidden.

eg.

$ zellij action hide-bars
$ zellij action hide-bars tab-bar
$ zellij action hide-bars tab-bar status-bar

See also the bars_hidden_on_start, hidden_bars_notification and mode_hints_when_bars_hidden options.

hide-floating-panes

Hide all floating panes in the specified tab (or active tab). Returns exit code 0 if changed, 2 if already hidden, 1 if the tab was not found.

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by ID

eg.

$ zellij action hide-floating-panes
$ zellij action hide-floating-panes --tab-id 3

ignore-pane-output

Stop reporting new output of a pane as something that needs attention, or start reporting it again (toggle). Defaults to the focused pane. See the inbox.

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID (eg. terminal_1 or 3)

eg.

$ zellij action ignore-pane-output
$ zellij action ignore-pane-output --pane-id terminal_3

launch-or-focus-plugin

Launch a plugin if it is not loaded somewhere in the session, focus it if it is. Returns the plugin pane ID.

ARGS: The plugin URL (eg. file:/path/to/my/plugin.wasm)

OPTIONS:

    -f, --floating                 Open in floating mode when launching
    -i, --in-place                 Open in place of the focused pane when launching
        --close-replaced-pane      Close the replaced pane (requires --in-place)
    -m, --move-to-focused-tab      Move the plugin to the focused tab if already running
    -c, --configuration <CONFIG>   Plugin configuration (key=value pairs)
    -s, --skip-plugin-cache        Skip the plugin cache and force reloading
        --tab-id <TAB_ID>          Target a specific tab by ID (conflicts with --in-place)

eg.

zellij action launch-or-focus-plugin zellij:strider --floating
zellij action launch-or-focus-plugin zellij:strider --in-place --move-to-focused-tab

launch-plugin

Launch a new plugin instance. Unlike launch-or-focus-plugin, this always launches a new instance. Returns the plugin pane ID.

ARGS: The plugin URL (eg. file:/path/to/my/plugin.wasm)

OPTIONS:

    -f, --floating                 Open in floating mode
    -i, --in-place                 Open in place of the focused pane
        --close-replaced-pane      Close the replaced pane (requires --in-place)
    -c, --configuration <CONFIG>   Plugin configuration (key=value pairs)
    -s, --skip-plugin-cache        Skip the plugin cache and force reloading
        --tab-id <TAB_ID>          Target a specific tab by ID (conflicts with --in-place)
        --no-focus                 Open the plugin pane without changing the focus of any client

eg.

zellij action launch-plugin file:/path/to/plugin.wasm --floating
zellij action launch-plugin zellij:session-manager --no-focus

list-clients

List all clients connected to the current session, their focused pane id and their running program (if it's not the default shell and if Zellij can detect it).

eg.

$ zellij action list-clients

CLIENT_ID ZELLIJ_PANE_ID RUNNING_COMMAND
1         plugin_2       zellij:session-manager
2         terminal_3     vim /tmp/my-file.txt

list-panes

List all panes in the current session with optional detail fields.

OPTIONS:

    -t, --tab          Include tab information
    -c, --command      Include running command information
    -s, --state        Include pane state (focused, floating, exited, etc.)
    -g, --geometry     Include geometry (position, size)
    -a, --all          Include all available fields
    -j, --json         Output as JSON

eg.

$ zellij action list-panes

Sample output (default):

PANE_ID      TYPE      TITLE
terminal_1   terminal  /bin/bash
plugin_0     plugin    tab-bar
terminal_2   terminal  vim main.rs

With --all:

$ zellij action list-panes --all

Sample output:

TAB_ID  TAB_POS  TAB_NAME  PANE_ID      TYPE      TITLE          COMMAND        CWD                      FOCUSED  FLOATING  EXITED  X  Y   ROWS  COLS
0       0        Tab #1    terminal_1   terminal  /bin/bash      bash           /home/user/project       true     false     false   0  1   24    80
0       0        Tab #1    plugin_0     plugin    tab-bar        zellij:tab-bar -                        false    false     false   0  0   1     80
1       1        Tab #2    terminal_2   terminal  vim main.rs    vim main.rs    /home/user/project/src   true     false     false   0  1   24    80

With --json:

$ zellij action list-panes --json

Sample output:

[
  {
    "id": 1,
    "is_plugin": false,
    "is_focused": true,
    "is_fullscreen": false,
    "is_floating": false,
    "is_suppressed": false,
    "title": "/bin/bash",
    "exited": false,
    "exit_status": null,
    "is_held": false,
    "pane_x": 0,
    "pane_content_x": 1,
    "pane_y": 1,
    "pane_content_y": 2,
    "pane_rows": 24,
    "pane_content_rows": 22,
    "pane_columns": 80,
    "pane_content_columns": 78,
    "cursor_coordinates_in_pane": [0, 5],
    "terminal_command": null,
    "plugin_url": null,
    "is_selectable": true,
    "tab_id": 0,
    "tab_position": 0,
    "tab_name": "Tab #1",
    "pane_command": "bash",
    "pane_cwd": "/home/user/project"
  },
  {
    "id": 0,
    "is_plugin": true,
    "is_focused": false,
    "is_fullscreen": false,
    "is_floating": false,
    "is_suppressed": false,
    "title": "tab-bar",
    "exited": false,
    "exit_status": null,
    "is_held": false,
    "pane_x": 0,
    "pane_content_x": 0,
    "pane_y": 0,
    "pane_content_y": 0,
    "pane_rows": 1,
    "pane_content_rows": 1,
    "pane_columns": 80,
    "pane_content_columns": 80,
    "cursor_coordinates_in_pane": null,
    "terminal_command": null,
    "plugin_url": "zellij:tab-bar",
    "is_selectable": false,
    "tab_id": 0,
    "tab_position": 0,
    "tab_name": "Tab #1"
  }
]

list-tabs

List all tabs with their information.

OPTIONS:

    -s, --state         Include state information (active, fullscreen, sync, floating visibility)
    -d, --dimensions    Include dimension information
    -p, --panes         Include pane counts
    -l, --layout        Include layout information (swap layout name and dirty state)
    -a, --all           Include all available fields
    -j, --json          Output as JSON

eg.

$ zellij action list-tabs

Sample output (default):

TAB_ID  POSITION  NAME
0       0         Tab #1
1       1         editor
2       2         logs

With --all:

$ zellij action list-tabs --all

Sample output:

TAB_ID  POSITION  NAME    ACTIVE  FULLSCREEN  SYNC_PANES  FLOATING_VIS  VP_ROWS  VP_COLS  DA_ROWS  DA_COLS  TILED_PANES  FLOAT_PANES  HIDDEN_PANES  SWAP_LAYOUT  LAYOUT_DIRTY
0       0         Tab #1  true    false       false       false         24       80       26       80       2            0            0             default      false
1       1         editor  false   false       false       false         24       80       26       80       1            0            0             -            false
2       2         logs    false   false       false       true          24       80       26       80       1            1            0             default      true

With --json:

$ zellij action list-tabs --json

Sample output:

[
  {
    "position": 0,
    "name": "Tab #1",
    "active": true,
    "panes_to_hide": 0,
    "is_fullscreen_active": false,
    "is_sync_panes_active": false,
    "are_floating_panes_visible": false,
    "other_focused_clients": [],
    "active_swap_layout_name": "default",
    "is_swap_layout_dirty": false,
    "viewport_rows": 24,
    "viewport_columns": 80,
    "display_area_rows": 26,
    "display_area_columns": 80,
    "selectable_tiled_panes_count": 2,
    "selectable_floating_panes_count": 0,
    "tab_id": 0,
    "has_bell_notification": false,
    "is_flashing_bell": false
  },
  {
    "position": 1,
    "name": "editor",
    "active": false,
    "panes_to_hide": 0,
    "is_fullscreen_active": false,
    "is_sync_panes_active": false,
    "are_floating_panes_visible": false,
    "other_focused_clients": [],
    "active_swap_layout_name": null,
    "is_swap_layout_dirty": false,
    "viewport_rows": 24,
    "viewport_columns": 80,
    "display_area_rows": 26,
    "display_area_columns": 80,
    "selectable_tiled_panes_count": 1,
    "selectable_floating_panes_count": 0,
    "tab_id": 1,
    "has_bell_notification": false,
    "is_flashing_bell": false
  }
]

mark-all-seen

Mark every pane of every running session as seen, clearing their past events. See the inbox.

OPTIONS:

        --this-session    Only mark the panes of the current session

eg.

$ zellij action mark-all-seen
$ zellij action mark-all-seen --this-session

mark-pane-seen

Mark a pane as seen, clearing its past events. Defaults to the focused pane. See the inbox.

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID (eg. terminal_1 or 3)

eg.

$ zellij action mark-pane-seen
$ zellij action mark-pane-seen --pane-id terminal_3

move-focus

Move the focused pane in the specified direction.

ARGS: The direction to move [right|left|up|down]

eg.

$ zellij action move-focus left

move-focus-or-tab

Move focus to the pane or tab (if on screen edge) in the specified direction

ARGS: The direction to move [right|left|up|down]

eg.

$ zellij action move-focus-or-tab left

move-pane

Change the location of the focused pane in the specified direction

ARGS (optional): The direction to move [right|left|up|down]

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action move-pane left
$ zellij action move-pane --pane-id terminal_3 right

move-pane-backwards

Rotate the location of the focused pane backwards in the layout order

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action move-pane-backwards

move-tab

Move the focused tab in the specified direction.

ARGS: The direction to move [right|left]

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by ID

eg.

$ zellij action move-tab right
$ zellij action move-tab left --tab-id 3

mute-pane

Mute or unmute the attention status of a pane (toggle). Defaults to the focused pane. See the inbox.

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID (eg. terminal_1 or 3)

eg.

$ zellij action mute-pane
$ zellij action mute-pane --pane-id terminal_3

mute-session

Mute or unmute the attention status of the whole session (toggle). See the inbox.

eg.

$ zellij action mute-session

mute-tab

Mute or unmute the attention status of all panes in a tab (toggle). Defaults to the active tab. See the inbox.

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by its ID

eg.

$ zellij action mute-tab
$ zellij action mute-tab --tab-id 2

new-pane

Open a new pane in the specified direction or as a floating pane. If no direction is specified, will try to use the biggest available space. Returns the created pane ID.

ARGS (optional): the command to run inside the pane in place of the default shell (must be preceded by a double-dash --)

OPTIONS:

    -c, --close-on-exit                Close the pane immediately when its command exits
        --cwd <CWD>                    Change the working directory of the new pane
    -d, --direction <DIRECTION>        Direction to open the new pane in (conflicts with --floating)
    -f, --floating                     Open the new pane in floating mode
    -i, --in-place                     Open in place of the focused pane (conflicts with --floating/--direction)
        --close-replaced-pane          Close the replaced pane instead of suspending (requires --in-place)
    -n, --name <NAME>                  Name of the new pane
    -p, --plugin <PLUGIN>              Plugin URL to load (conflicts with command and --direction)
        --configuration <CONFIG>       Plugin configuration (requires --plugin)
        --skip-plugin-cache            Skip the plugin cache (requires --plugin)
    -s, --start-suspended              Start the command suspended
        --notify                       Watch the pane: notify each time its command finishes or its
                                       output goes quiet, until the watch is turned off (requires a command)
    -x, --x <X>                        X coordinate for floating pane (requires --floating)
    -y, --y <Y>                        Y coordinate for floating pane (requires --floating)
        --width <WIDTH>                Width for floating pane (requires --floating)
        --height <HEIGHT>              Height for floating pane (requires --floating)
        --pinned <PINNED>              Pin the floating pane (requires --floating)
        --stacked                      Open in stacked mode (conflicts with --floating/--direction)
        --tab-id <TAB_ID>             Target a specific tab by ID (conflicts with --in-place, --near-current-pane)
        --pane-id <PANE_ID>            The pane to replace when using --in-place (default: the focused pane)
    -b, --blocking                     Block until the pane exits
        --block-until-exit-success     Block until the command exits with status 0
        --block-until-exit-failure     Block until the command exits with non-zero status
        --block-until-exit             Block until the command exits regardless of status
        --near-current-pane            Open near the current pane rather than following focus
        --no-focus                     Open the pane without changing the focus of any client
        --borderless <BORDERLESS>      Start without a border
        --border-style <STYLE>         Border line style, eg. "double" or "top:double,left:single,rounded"

eg.

$ zellij action new-pane -f # open a new floating pane with the default shell
$ zellij action new-pane --name "follow this log!" -- tail -f /tmp/my-log-file
$ zellij action new-pane --stacked
$ zellij action new-pane --in-place -- htop
$ zellij action new-pane --in-place --pane-id terminal_4 -- htop
$ zellij action new-pane --plugin zellij:strider --floating
$ zellij action new-pane --no-focus -- tail -f /tmp/my-log-file
$ zellij action new-pane --notify -- cargo build
$ zellij action new-pane --floating --border-style "double,rounded"

Note about --notify: the new pane is watched as with watch-pane. A notification is sent each time its command finishes or its output goes quiet, until the watch is turned off. See the inbox for where these notifications appear.

Note about --border-style: the format is described under set-pane-border-style.

Note about --no-focus: the pane is opened without changing the focus of any connected client. Its placement is relative to the pane the command was issued from rather than to the focused pane.

Note: This can also be shortened to zellij run

eg.

$ zellij run -- tail -f /tmp/my-log-file

new-tab

Create a new tab, optionally with a specified tab layout and name. Returns the created tab's ID.

Specifying a path to a layout file with --layout will start that tab with the specified layout.

If the --cwd flag is included with the --layout flag, all relative paths in that layout will start from this cwd. Replacing the global cwd in the layout if it exists. See layout CWD composition for more info.

ARGS (optional): A command to run in the initial pane (must be preceded by a double-dash --, conflicts with --initial-plugin)

OPTIONS:

    -c, --cwd <CWD>                    Working directory for the new tab
    -l, --layout <LAYOUT>              Layout to use
        --layout-dir <LAYOUT_DIR>      Default folder for layouts (requires --layout)
        --layout-string <LAYOUT_STRING>  Raw KDL layout string to use directly (conflicts with --layout)
    -n, --name <NAME>                  Name of the new tab
        --initial-plugin <PLUGIN>      Plugin to load in the initial pane (conflicts with command)
        --close-on-exit                Close the initial pane when its command exits (requires command)
        --start-suspended              Start the command suspended (requires command)
        --block-until-exit-success     Block until the command exits with status 0
        --block-until-exit-failure     Block until the command exits with non-zero status
        --block-until-exit             Block until the command exits regardless of status
        --no-focus                     Create the tab without changing the focus of any client

eg.

$ zellij action new-tab --layout /path/to/layout.kdl --name "my tab"
$ zellij action new-tab -- htop
$ zellij action new-tab --no-focus --name "background tab"

Note about --no-focus: the new tab is created in the background without changing the focus of any connected client. When a layout is used, its focus properties are suppressed as well.

next-swap-layout

Switch to the next swap layout for the current tab

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by ID

eg.

$ zellij action next-swap-layout

To select a swap layout by name, see apply-tiled-swap-layout and apply-floating-swap-layout.

open-context-menu

Open the right-click menu for the focused pane, at that pane's position. See the right-click menu.

eg.

$ zellij action open-context-menu

override-layout

Override the layout of the active tab with the specified layout file.

ARGS (optional): Path to the layout file - either this or --layout-string must be provided

OPTIONS:

        --layout-dir <LAYOUT_DIR>              Default folder for layouts
        --layout-string <LAYOUT_STRING>        Raw KDL layout string to use directly (conflicts with layout path arg)
        --retain-existing-terminal-panes       Retain existing terminal panes that do not fit the new layout
        --retain-existing-plugin-panes         Retain existing plugin panes that do not fit the new layout
        --apply-only-to-active-tab             Only apply the layout to the active tab

eg.

$ zellij action override-layout /path/to/layout.kdl
$ zellij action override-layout /path/to/layout.kdl --retain-existing-terminal-panes --apply-only-to-active-tab
$ zellij action override-layout --layout-string 'layout { pane; pane; }'

Note: layouts provided with --layout-string (here and in new-tab / switch-session) are parsed and validated before being sent to the session, so syntax errors are reported immediately.

page-scroll-down

Scroll down one page in focus pane

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action page-scroll-down

page-scroll-up

Scroll up one page in focus pane

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action page-scroll-up

paste

Paste text to the terminal using bracketed paste mode

ARGS: The text to paste

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action paste "Hello, World!"

pipe

Send data to one or more plugins via a pipe. Plugins will be launched if they are not already running.

ARGS (optional): Payload data to send. If blank, listens on STDIN.

OPTIONS:

    -n, --name <NAME>                        Name of the pipe
    -a, --args <ARGS>                        Arguments for the pipe (key=value pairs)
    -p, --plugin <PLUGIN>                    Plugin URL to direct the pipe to
    -c, --plugin-configuration <CONFIG>      Plugin configuration (key=value pairs)
    -l, --force-launch-plugin                Launch a new plugin even if one is already running
    -s, --skip-plugin-cache                  Skip the plugin cache and force reloading
    -f, --floating-plugin <BOOL>             Whether the launched plugin should be floating
    -i, --in-place-plugin <BOOL>             Launch plugin in place (conflicts with --floating-plugin)
    -w, --plugin-cwd <CWD>                   Working directory for the launched plugin
    -t, --plugin-title <TITLE>               Pane title for the launched plugin
        --popup <PLACEMENT>                  Open the launched plugin as a popup (conflicts with
                                             --floating-plugin and --in-place-plugin)
        --popup-no-focus                     The popup does not take key focus (requires --popup)
        --popup-capture-all-keys             Send every key to the popup, including keys bound to
                                             Zellij actions (requires --popup)
        --popup-outside-click <BEHAVIOR>     What a click outside the popup does: block or close
                                             (requires --popup)

eg.

$ zellij action pipe --name "my-pipe" --plugin "file:/path/to/plugin.wasm" "some payload"
$ echo "data from stdin" | zellij action pipe --name "my-pipe" --plugin "my-plugin-alias"
$ zellij action pipe --plugin "file:/path/to/plugin.wasm" --popup center --popup-outside-click close

The --popup* flags are described in Opening plugins as popups. The exit status of this command can be set by the plugin, see Zellij Pipe.

previous-swap-layout

Switch to the previous swap layout for the current tab

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by ID

eg.

$ zellij action previous-swap-layout

query-tab-names

Query all tab names (receive a textual list on the command line)

eg.

$ zellij action query-tab-names

rename-pane

Renames the focused pane (title will appear on the pane frame)

ARGS: the pane name

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action rename-pane "alice the cat"
$ zellij action rename-pane --pane-id terminal_3 "my pane"

rename-session

Rename the current session

ARGS: The new session name

eg.

$ zellij action rename-session "my-new-session-name"

rename-tab

Renames the focused tab

ARGS: the tab name

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by ID

eg.

$ zellij action rename-tab "alice the cat"
$ zellij action rename-tab --tab-id 3 "my tab"

rename-tab-by-id

Rename a tab by its stable ID

ARGS: The tab ID (integer) followed by the new name (string)

eg.

$ zellij action rename-tab-by-id 5 "my new tab name"

resize

Resize the focused pane in the specified direction.

ARGS: The resize direction [right|left|up|down|+|-]

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action resize left
$ zellij action resize --pane-id terminal_3 +

save-session

Save the current session state to disk immediately. Useful for triggering a manual serialization outside the automatic interval.

eg.

$ zellij action save-session

scroll-down

Scroll down 1 line in the focused pane

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action scroll-down

scroll-to-bottom

Scroll down to bottom in the focused pane

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action scroll-to-bottom

scroll-to-top

Scroll up to top in the focused pane

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action scroll-to-top

scroll-up

Scroll up 1 line in the focused pane

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action scroll-up

send-keys

Send one or more keys to the terminal. Keys are specified as space-separated names (eg. "Ctrl a", "F1", "Alt Shift b").

ARGS: One or more key names (space-separated)

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action send-keys "Ctrl a"
$ zellij action send-keys --pane-id terminal_3 "Alt b" "Enter"

set-dark-theme

Switch the theme to dark (uses the configured theme_dark).

eg.

$ zellij action set-dark-theme

set-light-theme

Switch the theme to light (uses the configured theme_light).

eg.

$ zellij action set-light-theme

set-pane-border-style

Change the border line style of an existing pane. Leaving out --border-style returns the pane to the default border.

OPTIONS:

    -p, --pane-id <PANE_ID>          Target pane by ID (required), eg. terminal_1, plugin_2 or 3
        --border-style <STYLE>       Border line style, eg. "double" or "top:double,left:single,rounded"

The --border-style value (here and in new-pane, edit, run, plugin and change-floating-pane-coordinates) is a comma-separated list of:

• A line style on its own, which applies to all four sides (eg. double)
• <side>:<line style> or <side>=<line style>, where <side> is one of all, top, right, bottom or left (eg. top:double)
• rounded for rounded corners, or rounded:true / rounded:false

The line styles are single, double, heavy (also accepted as bold or thick), dashed and heavy_dashed.

eg.

$ zellij action set-pane-border-style --pane-id terminal_3 --border-style double
$ zellij action set-pane-border-style --pane-id terminal_3 --border-style "top:double,left:single,rounded"
$ zellij action set-pane-border-style --pane-id terminal_3

set-pane-borderless

Set the borderless state of a specific pane

OPTIONS (required):

    -p, --pane-id <PANE_ID>        Target pane by ID (required)
    -b, --borderless <BORDERLESS>  Whether the pane should be borderless (required)

eg.

$ zellij action set-pane-borderless --pane-id terminal_3 --borderless true

set-pane-frame-style

Set the style of the pane frames for the whole session at runtime. This is the runtime equivalent of the pane_frame_style configuration option.

ARGS: The frame style - one of full (a full border around each pane), titles (a single title line above each pane) or none (no frames)

eg.

$ zellij action set-pane-frame-style titles
$ zellij action set-pane-frame-style full
$ zellij action set-pane-frame-style none

set-pane-color

Set the default foreground and/or background color of a pane. Colors can be specified as hex (eg. "#00e000") or rgb notation (eg. "rgb:00/e0/00").

OPTIONS:

    -p, --pane-id <PANE_ID>    Target pane by ID (defaults to $ZELLIJ_PANE_ID)
        --fg <FG>              Foreground color (eg. "#00e000", "rgb:00/e0/00")
        --bg <BG>              Background color (eg. "#001a3a", "rgb:00/1a/3a")
        --reset                Reset pane colors to terminal defaults (conflicts with --fg, --bg)

eg.

$ zellij action set-pane-color --fg "#00e000" --bg "#001a3a"
$ zellij action set-pane-color --pane-id terminal_3 --reset

set-resurrect-command

Set the command a terminal pane will be resurrected with, instead of the command Zellij detects running in it. This lets a program that knows how to resume itself (eg. by a session id) register the exact command to run when the session is resurrected.

The command set this way takes the place of the detected command and is not passed through the post_command_discovery_hook. It stays in effect until it is removed with --clear or until the pane is closed. It can only be set for terminal panes.

ARGS: The command and its arguments (must be preceded by a double-dash --). Required unless --clear is given.

OPTIONS:

    -p, --pane-id <PANE_ID>    The terminal pane, eg. terminal_1 or 3 (defaults to $ZELLIJ_PANE_ID)
        --cwd <CWD>            Working directory to resurrect the pane in (conflicts with --clear)
        --clear                Remove a previously set resurrect command (conflicts with a command)

A relative --cwd is resolved from the folder the command is run in.

eg.

$ zellij action set-resurrect-command -- opencode -s ses_abc
$ zellij action set-resurrect-command --pane-id terminal_3 --cwd /home/user/project -- htop
$ zellij action set-resurrect-command --clear

show-bars

Show all hidden UI bars. See hide-bars.

eg.

$ zellij action show-bars

show-floating-panes

Show all floating panes in the specified tab (or active tab). Returns exit code 0 if changed, 2 if already visible, 1 if the tab was not found.

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by ID

eg.

$ zellij action show-floating-panes
$ zellij action show-floating-panes --tab-id 3

start-or-reload-plugin

Launch a plugin if it is not loaded or reload it (skipping cache) if it is. Mostly useful for plugin development.

ARGS: The plugin URL (eg. file:/path/to/my/plugin.wasm)

OPTIONS:

    -c, --configuration <CONFIG>    Plugin configuration (key=value pairs)

eg.

zellij action start-or-reload-plugin zellij:strider
zellij action start-or-reload-plugin file:/path/to/plugin.wasm -c "key=value"

stack-panes

Given a list of pane ids, turns them into a stack. (pane ids can be discovered through the $ZELLIJ_PANE_ID env var).

ARGS: A list of panes (see example below)

eg.

# This will create a stack of 3 panes (terminal with ID 1, plugin with ID 1 and terminal with ID 2)
$ zellij action stack-panes -- terminal_1 plugin_1 terminal_2

switch-mode

Switch input mode of all connected clients

ARGS: The mode to switch to [locked|pane|tab|resize|move|search|session|tmux]

eg.

$ zellij action switch-mode locked

switch-session

Switch to a different session

ARGS: The session name to switch to

OPTIONS:

        --tab-position <TAB_POSITION>    Tab position to focus after switching
        --pane-id <PANE_ID>              Pane ID to focus after switching
    -l, --layout <LAYOUT>                Layout to apply when switching
        --layout-dir <LAYOUT_DIR>        Default folder for layouts (requires --layout)
        --layout-string <LAYOUT_STRING>  Raw KDL layout string to use directly (conflicts with --layout)
    -c, --cwd <CWD>                      Working directory when switching
        --close-current                  Close the current session after switching, if no command
                                         has been run in it and no other client is attached

eg.

$ zellij action switch-session my-other-session
$ zellij action switch-session my-session --tab-position 2 --layout /path/to/layout.kdl
$ zellij action switch-session my-other-session --close-current

To move between the sessions this client has visited, see toggle-session, go-to-previous-session and go-to-next-session.

toggle-active-sync-tab

Toggle between sending text input to all panes in the current tab and just to the focused pane (the default)

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by ID

eg.

$ zellij action toggle-active-sync-tab

toggle-bars

If any UI bars are hidden, show all of them. Otherwise hide the named bars (all bars if none are named), as hide-bars does.

ARGS (optional): The bars to hide: tab-bar, status-bar, compact-bar, a plugin alias or plugin location, or all

eg.

$ zellij action toggle-bars
$ zellij action toggle-bars status-bar

toggle-floating-panes

Toggle the visibility of all floating panes in the current Tab, open one if none exist

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by ID

eg.

$ zellij action toggle-floating-panes

toggle-fullscreen

Toggle between fullscreen focus pane and normal layout

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action toggle-fullscreen

toggle-mirror-resize

Toggle whether the live view of a pane shown inside the focused plugin pane resizes the program of the pane it shows. See also the mirror_resizes_source_pane option.

eg.

$ zellij action toggle-mirror-resize

toggle-no-ui-fullscreen

Toggle between fullscreen focus pane and normal layout, with the pane taking up the entire display - including the space normally occupied by the UI bars (eg. the tab-bar and status-bar). This is unlike toggle-fullscreen, which keeps the UI bars visible.

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID
    -t, --tab-id <TAB_ID>      Target a specific tab by ID

eg.

$ zellij action toggle-no-ui-fullscreen
$ zellij action toggle-no-ui-fullscreen --pane-id terminal_3

toggle-pane-borderless

Toggle the borderless state of a specific pane

OPTIONS (required):

    -p, --pane-id <PANE_ID>    Target pane by ID (required)

eg.

$ zellij action toggle-pane-borderless --pane-id terminal_3

toggle-pane-embed-or-floating

Embed focused pane if floating or float focused pane if embedded

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action toggle-pane-embed-or-floating

toggle-pane-frames

Toggle frames around panes in the UI

Note: Zellij relies on frames to display parts of the UI, removing them might make certain things a little confusing to those not used to the app.

eg.

$ zellij action toggle-pane-frames

toggle-pane-pinned

If the current pane is a floating pane, toggle its pinned state (always on top).

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action toggle-pane-pinned

toggle-session

Switch to the session this client was in before. Running it again returns to the first session. If there is no previous session, switch to the next running session.

eg.

$ zellij action toggle-session

toggle-stack-list-orientation

Switch a stack between showing its pane titles in a column (vertical) and in a row (horizontal). Defaults to the focused stack. See also the stacked_pane_list_orientation option.

OPTIONS:

    -p, --pane-id <PANE_ID>    Target the stack holding a specific pane by ID (eg. terminal_1, plugin_2, or 3)

eg.

$ zellij action toggle-stack-list-orientation
$ zellij action toggle-stack-list-orientation --pane-id terminal_3

toggle-theme

Toggle between the dark and light themes (uses the configured theme_dark and theme_light).

eg.

$ zellij action toggle-theme

toggle-tray-icon

Show or hide the tray / menu-bar icon of the desktop app until the app restarts. Sessions and notifications continue either way. This action is sent to the desktop app rather than to a session. It exits with status 1 and prints "The Zellij desktop app is not running." if the app is not running.

eg.

$ zellij action toggle-tray-icon

undo-rename-pane

Remove a previously set pane name

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action undo-rename-pane

undo-rename-tab

Remove a previously set tab name

OPTIONS:

    -t, --tab-id <TAB_ID>    Target a specific tab by ID

eg.

$ zellij action undo-rename-tab

watch-pane

Watch a pane: a notification is sent each time its command finishes or its output goes quiet, until the watch is turned off by running this action again (toggle). Defaults to the focused pane. A pane can also be watched from the start with zellij run --notify or zellij action new-pane --notify. See the inbox.

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID (eg. terminal_1 or 3)

eg.

$ zellij action watch-pane
$ zellij action watch-pane --pane-id terminal_3

write

Write bytes to the focused pane

ARGS: An array of bytes to write

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action write 102 111 111

write-chars

Write characters to the focused pane

ARGS: A string of characters to write

OPTIONS:

    -p, --pane-id <PANE_ID>    Target a specific pane by ID

eg.

$ zellij action write-chars "Hi there!"

Zellij Plugin & Pipe

• Zellij Plugin - Load a plugin from a local or remote wasm file into a new pane
• Zellij Pipe - Send messages and data to one or more plugins, launching them if needed

Zellij Plugin

Zellij includes a top-level plugin cli command that can be used to launch a new Zellij plugin instance from a local or remote wasm file

eg.

$ zellij plugin -- https://path/to/my/plugin.wasm

USAGE:

    zellij plugin [OPTIONS] [--] <URL>

ARGS:

    <URL>    Plugin URL, can either start with http(s), file: or zellij:

OPTIONS:

    -b, --borderless <BORDERLESS>
            Start this pane without a border (warning: will make it impossible to move with the
            mouse) [possible values: true, false]

        --border-style <BORDER_STYLE>
            Border line style, eg. "double" or "top:double,left:single,rounded"

        --close-replaced-pane
            Close the replaced pane instead of suspending it (only effective with --in-place)

    -c, --configuration <CONFIGURATION>
            Plugin configuration

    -f, --floating
            Open the new pane in floating mode

    -h, --help
            Print help information

        --height <HEIGHT>
            The height if the pane is floating as a bare integer (eg. 1) or percent (eg. 10%)

    -i, --in-place
            Open the new pane in place of the current pane, temporarily suspending it

        --no-focus
            Open the plugin pane without changing the focus of any client

        --pinned <PINNED>
            Whether to pin a floating pane so that it is always on top [possible values: true,
            false]

    -s, --skip-plugin-cache
            Skip the plugin cache and force reloading of the plugin (good for development)

        --tab-id <TAB_ID>
            Open the plugin pane in the tab with this id (conflicts with --in-place)

        --width <WIDTH>
            The width if the pane is floating as a bare integer (eg. 1) or percent (eg. 10%)

    -x, --x <X>
            The x coordinates if the pane is floating as a bare integer (eg. 1) or percent (eg. 10%)

    -y, --y <Y>
            The y coordinates if the pane is floating as a bare integer (eg. 1) or percent (eg. 10%)

The format of --border-style is described under set-pane-border-style.

Zellij Pipe

Zellij pipes provide a way to send messages to one or more plugins, launching them on first-message if they are not running.

eg.

$ zellij pipe --name my_pipe_name -- my_arbitrary_data

USAGE:

zellij pipe [OPTIONS] [--] <PAYLOAD>

* Send data to a specific plugin:

zellij pipe --plugin file:/path/to/my/plugin.wasm --name my_pipe_name -- my_arbitrary_data

* To all running plugins (that are listening):

zellij pipe --name my_pipe_name -- my_arbitrary_data

* Pipe data into this command's STDIN and get output from the plugin on this command's STDOUT

tail -f /tmp/my-live-logfile | zellij pipe --name logs --plugin https://example.com/my-plugin.wasm | wc -l

ARGS:

    <PAYLOAD>    The data to send down this pipe (if blank, will listen to STDIN)

OPTIONS:

    -n, --name <NAME>
            The name of the pipe

    -a, --args <ARGS>
            The args of the pipe

    -p, --plugin <PLUGIN>
            The plugin url (eg. file:/tmp/my-plugin.wasm) to direct this pipe to, if not specified,
            will be sent to all plugins, if specified and is not running, the plugin will be
            launched

    -c, --plugin-configuration <PLUGIN_CONFIGURATION>
            The plugin configuration (note: the same plugin with different configuration is
            considered a different plugin for the purposes of determining the pipe destination)

    -h, --help
            Print help information

zellij action pipe takes more options, for controlling how a launched plugin is opened, including opening it as a popup. See pipe and Opening Plugins as Popups.

Exit status

zellij pipe (and zellij action pipe) exits with status 0 once the plugin has handled the message. A plugin can choose a different exit status with the set_cli_pipe_exit_code command before it unblocks the pipe, so a script can tell the outcome:

$ zellij pipe --plugin file:/path/to/my/plugin.wasm --name check -- my_data && echo "ok"

If Zellij reports an error for the pipe, the command exits with status 2.

Zellij Subscribe

Zellij provides a top-level subscribe command that streams the rendered output of one or more panes to stdout in real time. This is useful for monitoring, scripting, and building external tooling around Zellij sessions.

• Usage - Command syntax
• Options - Available flags and parameters
• Output Formats - Raw text and JSON (NDJSON) output modes
• Behavior - How initial delivery, change detection, and exit work
• Subscribing to a Different Session - Monitoring panes in background or remote sessions
• Examples - Common usage patterns including jq and awk filtering

Usage

zellij [--session <SESSION_NAME>] subscribe [OPTIONS] --pane-id <PANE_ID>...

Options

-p, --pane-id <PANE_ID>    One or more pane IDs to subscribe to (required, repeatable).
                           Accepts terminal_N, plugin_N, or bare integer N
                           (equivalent to terminal_N).
-s, --scrollback [<LINES>] Include scrollback in the initial delivery. If specified
                           without a value, all scrollback is included. If a number
                           is provided, that many lines of scrollback are included.
-f, --format <FORMAT>      Output format: "raw" (default) or "json"
    --ansi                 Preserve ANSI styling escape sequences in the output

Output Formats

Raw (default)

Viewport lines are printed to stdout each time the pane content changes, followed by a flush. On the initial delivery, scrollback lines (if requested) precede the viewport lines.

JSON

Output is delivered as NDJSON (one JSON object per line). Two event types are emitted:

Pane update:

{"event":"pane_update","pane_id":"terminal_1","viewport":["line1","line2"],"scrollback":null,"is_initial":true}

Pane closed:

{"event":"pane_closed","pane_id":"terminal_1"}

This format is well suited for piping into jq for structured processing:

$ zellij subscribe --pane-id terminal_1 --format json | jq 'select(.event == "pane_update") | .viewport[]'

Behavior

• On subscription, the full current viewport (and scrollback if requested) is delivered immediately with is_initial: true.
• Subsequent deliveries occur only when the viewport content changes. Only changed viewports are sent (no scrollback on subsequent deliveries).
• The client exits automatically when all subscribed panes have been closed or the session ends.

Subscribing to a Different Session

To subscribe to panes in a session other than the current one, use the global --session flag:

$ zellij --session my-background-session subscribe --pane-id terminal_1

This is especially useful when combined with background sessions.

Examples

Subscribe to a single pane:

$ zellij subscribe --pane-id terminal_1

Subscribe to multiple panes with ANSI styling preserved:

$ zellij subscribe --pane-id terminal_1 --pane-id plugin_2 --ansi

Include the last 100 lines of scrollback on initial delivery:

$ zellij subscribe --pane-id terminal_1 --scrollback 100