MANPAGE(1)

📦 version 0.42.2, in alpine 3.24

💅 MANPAGE(1) — the general commands manual, but make it make sense

okay so real talk: this is the zellij page 💖 — that's the actual title of the command, zellij, sitting inside the General Commands Manual. Buckle up bestie, we're going in.

✨ NAME ✨

zellij — run zellij 🫶 (that's it. that's the whole name section. iconic brevity.)

🌸 DESCRIPTION 🌸

Zellij is a whole workspace, and it's aimed at developers, ops-oriented people, and honestly anyone who loves the terminal 💜. At its core it's a terminal multiplexer (think tmux and screen energy), but ngl — that's just the infrastructure layer, the scaffolding, the ~vibes layer~. 🦋

Zellij also ships a layout system, plus a plugin system that lets you create plugins in any language that compiles to WebAssembly 👑. Any language. That's not a drill.

Wanna see what's already running? Run this:

zellij list-sessions

Wanna slide into a session that's already alive? Run this:

zellij attach [session-name]

⭐ OPTIONS ⭐

Run zellij --help to see all the available flags and subcommamds 💀 (yes, "subcommamds" — that's literally how it's spelled in the source, we stan a typo queen 🙈).

🎀 CONFIGURATION 🎀

Zellij looks for the config file in this exact order, no skipping:

  1. the file provided with --config
  2. under the path provided in the ZELLIJ_CONFIG_FILE environment variable
  3. the default location (peep the FILES section below, iykyk)
  4. the system location

And to check whether your config is lowkey a mess, run:

zellij setup --check

That'll show you possible issues with the configuration ✨

🌈 LAYOUTS 🌈

Layouts are yaml files that Zellij can load on startup when the --layout flag is provided 💖. By default Zellij will load a layout called default.yaml, but you can change that with the default_layout: [LAYOUT_NAME] configuration option. easy peasy.

So like, a file that looks exactly like this:

---
direction: Vertical
parts:
    - direction: Horizontal
      split_size:
        Percent: 50
      parts:
        - direction: Vertical
          split_size:
            Percent: 50
        - direction: Vertical
          split_size:
            Percent: 50
    - direction: Horizontal
      split_size:
        Percent: 50

will tell Zellij to create this layout:

+-----+-----+|     |     |+-----+     ||     |     |+-----+-----+

(the ascii art is doing its best, okay, we love her 😭)

🧚 CREATING LAYOUTS 🧚

A layout file is a nested tree structure, periodt. Each node describes either a pane (a leaf 🌸), or a space in which its parts (children) will be created.

Each node has these fields:

  • direction: <Horizontal / Vertical> — node's children will be created by a split in the given direction.
  • split_size: — this indicates either a percentage of the node's parent's space or a fixed size of columns/rows from its parent's space.
    • Percent: <1-100>
    • Fixed: <lines_number/columns_number>
  • plugin: /path/to/plugin.wasm — optional path to a compiled Zellij plugin. If indicated, loads a plugin into the created space. For more info see the PLUGINS section, bestie.

💅 KEYBINDINGS 💅

Zellij comes with a default set of keybindings that aims to fit as many users as possible, but that behaviour can be overridden or modified in user configuration files 🔥. All the info about bindings lives in the keybinds section of the configuration.

So for example, if you wanna introduce a keybinding that creates a new tab and goes to tab 1 after pressing 'c', you write:

keybinds:
    normal:
        - action: [ NewTab, GoToTab: 1,]
          key: [ Char: 'c',]

where:

  • "normal" stands for a mode name (see MODES 👀)
  • "action" specifies the actions to be executed by Zellij (see ACTIONS 👀)
  • "key" lists the keys or key combinations bound to the given actions (see KEYS 👀)

The default keybinds can be unbound either for a specific mode, or for every mode 🌸. It supports either a list of keybinds, or a bool indicating that every keybind should be unbound:

keybinds:
    unbind: true

That will unbind every default binding. all of them. gone. 💀

keybinds:
    unbind: [ Ctrl: 'p']

That will unbind every default ^P binding for each mode.

keybinds:
    normal:
        - unbind: true

That will unbind every default keybind for the normal mode.

keybinds:
    normal:
        - unbind: [ Alt: 'n', Ctrl: 'g']

That will unbind every default keybind for n and ^g for the normal mode. slay 🎀

👑 ACTIONS 👑

  • Quit — quits Zellij
  • SwitchToMode: <InputMode> — switches to the specified input mode. See the MODES section for possible values.
  • Resize: <Direction> — resizes the focused pane in the specified direction (one of: Left, Right, Up, Down).
  • FocusNextPane — switches focus to the next pane to the right or below if on screen edge.
  • FocusPreviousPane — switches focus to the next pane to the left or above if on screen edge.
  • SwitchFocus — left for legacy support. Switches focus to a pane with the next ID.
  • MoveFocus: <Direction> — moves focus in the specified direction (Left, Right, Up, Down).
  • Clear — clears current screen.
  • DumpScreen: <File> — dumps the screen in the specified file.
  • DumpLayout: <File> — dumps the screen in the specified or default file.
  • EditScrollback — replaces the current pane with the scrollback buffer.
  • ScrollUp — scrolls up 1 line in the focused pane.
  • ScrollDown — scrolls down 1 line in the focused pane.
  • PageScrollUp — scrolls up 1 page in the focused pane.
  • PageScrollDown — scrolls down 1 page in the focused pane.
  • ToggleFocusFullscreen — toggles between fullscreen focus pane and normal layout.
  • NewPane: <Direction> — opens a new pane in the specified direction (Left, Right, Up, Down) relative to focus.
  • CloseFocus — closes focused pane.
  • NewTab — creates a new tab.
  • GoToNextTab — goes to the next tab.
  • GoToPreviousTab — goes to previous tab.
  • CloseTab — closes current tab.
  • GoToTab: <Index> — goes to the tab with the specified index number.
  • Detach — detach session and exit.
  • ToggleActiveSyncTab — toggle between sending text commands to all panes on the current tab and normal mode.
  • UndoRenameTab — undoes the changed tab name and reverts to the previous name.
  • UndoRenamePane — undoes the changed pane name and reverts to the previous name.

🦋 KEYS 🦋

  • Char: <character> — a single character with no modifier.
  • Alt: <character> — a single character with Alt key as modifier.
  • Ctrl: <character> — a single character with Ctrl key as modifier.
  • F: <1-12> — one of F keys (usually at the top of the keyboard).
  • Backspace
  • Left / Right / Up / Down — arrow keys on the keyboard.
  • Home
  • End
  • PageUp / PageDown
  • BackTab — a backward Tab key.
  • Delete
  • Insert
  • Esc

🍓 MODES 🍓

  • normal — the default startup mode of Zellij. Provides the ability to switch to different modes, as well as some quick navigation shortcuts.
  • locked — disables all keybindings except the one that would switch the mode to normal (Ctrl+g by default). Super useful when Zellij's keybindings conflict with those of a chosen terminal app 🙈.
  • tmux — provides convenience keybindings emulating simple tmux behaviour.
  • pane — includes instructions that manipulate the panes (adding new panes, moving, closing).
  • tab — includes instructions that manipulate the tabs (adding new tabs, moving, closing).
  • resize — allows resizing of the focused pane.
  • scroll — allows scrolling within the focused pane.
  • renametab — is a "hidden" mode that can be passed to the SwitchToMode action. It will trigger renaming of a tab.
  • renamepane — is a "hidden" mode that can be passed to the SwitchToMode action. It will trigger renaming of a pane.
  • session — allows detaching from a session.

🧚 Theme 🧚

A color theme can be defined either in truecolor, 256 or hex color format 💜.

Truecolor:

fg: [0, 0, 0]

256:

fg: 0

Hex color:

fg: "#000000"
bg: "#000"

The color theme can be specified in the following way:

themes:
  default:
    fg: [0,0,0]
    bg: [0,0,0]
    black: [0,0,0]
    red: [0,0,0]
    green: [0,0,0]
    yellow: [0,0,0]
    blue: [0,0,0]
    magenta: [0,0,0]
    cyan: [0,0,0]
    white: [0,0,0]
    orange: [0,0,0]

If the theme is called default, then zellij will pick it on startup 👑. To specify a different theme, run zellij with:

zellij options --theme [NAME]

or put the name in the configuration file with theme: [NAME]. either way, works 💅

💖 PLUGINS 💖

Zellij has a plugin system based on WebAssembly ⭐. Any language that can run on WASI can be used to develop a plugin. To load a plugin, include it in a layout file. Zellij comes with default plugins included: status-bar, strider, tab-bar. built in, ready to go, no cap 🔥

🌸 FILES 🌸

Default user configuration directory location:

  • Linux: $XDG_HOME/zellij /home/alice/.config/zellij
  • macOS: /Users/Alice/Library/Application Support/com.Zellij-Contributors.zellij

Default user layout directory location:

  • Subdirectory called layouts inside of the configuration directory.
  • Linux: _$XDG_HOME/zellij/layouts /home/alice/.config/zellij/layouts
  • macOS: /Users/Alice/Library/Application/layouts Support/com.Zellij-Contributors.zellij/layouts

Default plugin directory location:

  • Linux: _$XDG_DATA_HOME/zellij/plugins /home/alice/.local/share/plugins

🎀 ENVIRONMENT 🎀

  • ZELLIJ_CONFIG_FILE — Path of Zellij config to load.
  • ZELLIJ_CONFIG_DIR — Path of the Zellij config directory.

⭐ NOTES ⭐

The manpage is meant to provide a concise offline reference 🫶. For more detailed instructions please visit:

https://zellij.dev/documentation

ok that's the whole page bestie, you're officially literate in zellij 💜

and like, a little sign-off: this whole thing lives in MANPAGE(1), the source/version line is literally just that — MANPAGE(1) — and there's no date on it, so we're matching energies with the void 😭✨ consider yourself informed, mwah 🎀

📦 where this page comes from