Getting started

Introduction

Zellij is a terminal workspace with panes, tabs, and sessions that keep running after you disconnect.

Start a session

zellij                      # Start a new session
zellij -s work              # Name it
zellij -l compact           # Load a layout
zellij -s work -l compact   # Both

-s names the session; -l loads a built-in or saved layout.

See: Documentation

Attach, list, and kill

zellij ls                    # List sessions
zellij ls -s                 # Names only
zellij list-sessions -s      # Long form
zellij a                     # Attach to last session
zellij a work                # Attach by name
zellij attach -c work        # Create if missing
zellij k work                # Kill a session

ls aliases list-sessions; a aliases attach.

See: Documentation

Mode keys

KeysMode
C-pPane mode
C-tTab mode
C-sScroll mode
C-oSession mode
C-nResize mode
C-hMove mode
C-bTmux mode

C- is Ctrl; M- is Alt.

See: Keybindings

Quit and detach

KeysAction
C-qQuit
C-o dDetach; the session keeps running
C-gLock or unlock
Enter, EscBack to Normal mode

C-q ends the session; C-o d leaves it running for zellij a.

See: Keybindings

Panes

Pane mode

KeysAction
C-p nNew pane
C-p dNew pane below
C-p rNew pane right
C-p aFloating pane
C-p sStack a pane
C-p pSwitch focus
C-p ;Previous focus

Most pane actions return to Normal mode when they finish.

See: Keybindings

Move and resize

KeysAction
C-p hFocus left
C-p jFocus down
C-p kFocus up
C-p lFocus right
M-hFocus left or previous tab
M-lFocus right or next tab
M-=Grow
M--Shrink
C-n hGrow the left edge
C-n HShrink the left edge

C-n opens Resize mode; j/k/l grow the other edges.

See: Keybindings

Fullscreen and floating

KeysAction
C-p fFullscreen the focused pane
C-p Shift-fFullscreen without the UI bars
C-p zToggle pane frames
C-p Shift-zToggle bars
C-p wToggle floating panes
C-p eFloat or embed the pane
M-fToggle floating panes
C-p iPin the pane

M-f toggles every floating pane except in Locked mode.

See: Keybindings

Close, rename, and stack

KeysAction
C-p xClose the pane
C-p cRename the pane
C-p sStack a new pane
C-p Shift-sChange stack title direction
M-pToggle the pane group
M-Shift-pToggle group marking

See: Keybindings

Tabs

Tab mode

KeysAction
C-t nNew tab
C-t xClose tab
C-t rRename tab
C-t h/lPrevious / next tab
C-t 1-9Jump to tab
C-t TabLast tab
C-t sSync input to every pane

C-t opens Tab mode; most tab actions return to Normal mode.

See: Keybindings

Break and swap

KeysAction
C-t bBreak pane into a tab
C-t [Break pane left
C-t ]Break pane right
C-t SpaceNext swap layout
C-t Shift-SpacePrevious swap layout
M-iMove tab left
M-oMove tab right

Break a pane into a tab, or cycle the tab's swap layout.

See: Keybindings

Scroll mode

KeysAction
C-sScroll mode
j / DownScroll down
k / UpScroll up
C-f / PageDownPage down
C-b / PageUpPage up
dHalf page down
uHalf page up
[Previous prompt
]Next prompt
C-cScroll to bottom

C-s enters and leaves Scroll mode; Esc also returns.

See: Keybindings

Search and copy

KeysAction
C-s sSearch forward
nNext match
pPrevious match
cCase sensitivity
wWrap
oWhole word
C-s eEdit scrollback
C-s cCopy last command output

c, w, and o toggle search options.

See: Keybindings

Mouse wheel

InputAction
ScrollUp / ScrollDownScroll three lines
Alt ScrollUpPrevious prompt
Alt ScrollDownNext prompt
Ctrl ScrollUpGrow
Ctrl ScrollDownShrink

Hold Shift to temporarily disable mouse handling.

See: Compatibility

Layouts

Built-in layouts

default

layout {
    pane size=1 borderless=true {
        plugin location="tab-bar"
    }
    pane
    pane size=1 borderless=true {
        plugin location="status-bar"
    }
}

compact

layout {
    pane
    pane size=1 borderless=true {
        plugin location="compact-bar"
    }
}

No built-in stacked layout in 0.46.0; use C-p s or zellij run --stacked.

See: Layouts

Custom layout

layout {
    pane split_direction="vertical" {
        pane
        pane
    }
    pane size=1 borderless=true {
        plugin location="compact-bar"
    }
}

Save under layout_dir or pass the path with --layout.

See: Layouts

Use layouts

zellij -l compact
zellij -s work -l ~/layouts/dev.kdl
zellij --layout-string 'layout { pane; }'
zellij -n compact     # New session
zellij action dump-layout

-l can add a tab when called inside a session.

See: Layouts

Sessions

Session keys

KeysAction
C-o dDetach
C-o rRename session
C-o TabSwitch session
C-o LeftPrevious session
C-o RightNext session
C-o nNext pane needing attention
C-o wSession manager

Detaching keeps programs running; reattach with zellij a.

See: Keybindings

Session commands

zellij a -c work       # Attach or create
zellij a -c -b work    # Create detached
zellij w work          # Watch read-only

See: Documentation

Run a command in a pane

zellij run -- <cmd>
zellij run -d down -- make
zellij run -f -- htop
zellij run -c -- sleep 5
zellij run -n build -- cargo build
zellij run --stacked -- tail -f log

run returns a pane ID; -d takes down, right, left, or up.

See: Documentation

Script actions

zellij action <subcommand>
zellij ac send-keys "Ctrl a"
zellij ac write-chars "echo hi"
zellij action focus-next-pane
zellij action go-to-tab 2
zellij action new-tab --layout compact
zellij action list-panes
zellij action dump-screen

ac aliases action; these commands target the active session.

See: GitHub repository

Configuration

Config file

zellij setup --check
zellij setup --dump-config
zellij setup --dump-keybinds default
zellij setup --dump-layout default

Config lives in ~/.config/zellij/config.kdl; setup --check prints its paths.

See: Configuration

Keybinds preset

keybinds preset="default" primary="Ctrl" secondary="Alt" {
    normal {
        bind "Alt y" { NewTab; }
    }
}

Bindings layer on the preset; add clear-defaults=true to replace it.

See: Configuration

Theme and layout defaults

theme_dark "nightfox"
theme_light "dayfox"
default_layout "compact"
layout_dir "/path/to/my/layout_dir"
mouse_mode false

Use theme to pin one theme; theme_dark and theme_light follow the host palette.

See: Configuration

CLI options

FlagDescription
-s, --session <NAME>Name a new session
-l, --layout <LAYOUT>Start with a layout
-c, --config <FILE>Use another config file
--max-panes <N>Cap visible panes
-d, --debugEmit debug output

Flags come from zellij --help; subcommands have their own --help.

See: Documentation

0 Comments for this cheatsheet. Write yours!