Getting started
Introduction
Zellij is a terminal workspace with panes, tabs, and sessions that keep running after you disconnect.
- Documentation (zellij.dev)
- Keybindings (zellij.dev)
- Configuration (zellij.dev)
- Layouts (zellij.dev)
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
| Keys | Mode |
|---|---|
C-p | Pane mode |
C-t | Tab mode |
C-s | Scroll mode |
C-o | Session mode |
C-n | Resize mode |
C-h | Move mode |
C-b | Tmux mode |
C- is Ctrl; M- is Alt.
See: Keybindings
Quit and detach
| Keys | Action |
|---|---|
C-q | Quit |
C-o d | Detach; the session keeps running |
C-g | Lock or unlock |
Enter, Esc | Back to Normal mode |
C-q ends the session; C-o d leaves it running for zellij a.
See: Keybindings
Panes
Pane mode
| Keys | Action |
|---|---|
C-p n | New pane |
C-p d | New pane below |
C-p r | New pane right |
C-p a | Floating pane |
C-p s | Stack a pane |
C-p p | Switch focus |
C-p ; | Previous focus |
Most pane actions return to Normal mode when they finish.
See: Keybindings
Move and resize
| Keys | Action |
|---|---|
C-p h | Focus left |
C-p j | Focus down |
C-p k | Focus up |
C-p l | Focus right |
M-h | Focus left or previous tab |
M-l | Focus right or next tab |
M-= | Grow |
M-- | Shrink |
C-n h | Grow the left edge |
C-n H | Shrink the left edge |
C-n opens Resize mode; j/k/l grow the other edges.
See: Keybindings
Fullscreen and floating
| Keys | Action |
|---|---|
C-p f | Fullscreen the focused pane |
C-p Shift-f | Fullscreen without the UI bars |
C-p z | Toggle pane frames |
C-p Shift-z | Toggle bars |
C-p w | Toggle floating panes |
C-p e | Float or embed the pane |
M-f | Toggle floating panes |
C-p i | Pin the pane |
M-f toggles every floating pane except in Locked mode.
See: Keybindings
Close, rename, and stack
| Keys | Action |
|---|---|
C-p x | Close the pane |
C-p c | Rename the pane |
C-p s | Stack a new pane |
C-p Shift-s | Change stack title direction |
M-p | Toggle the pane group |
M-Shift-p | Toggle group marking |
See: Keybindings
Tabs
Tab mode
| Keys | Action |
|---|---|
C-t n | New tab |
C-t x | Close tab |
C-t r | Rename tab |
C-t h/l | Previous / next tab |
C-t 1-9 | Jump to tab |
C-t Tab | Last tab |
C-t s | Sync input to every pane |
C-t opens Tab mode; most tab actions return to Normal mode.
See: Keybindings
Break and swap
| Keys | Action |
|---|---|
C-t b | Break pane into a tab |
C-t [ | Break pane left |
C-t ] | Break pane right |
C-t Space | Next swap layout |
C-t Shift-Space | Previous swap layout |
M-i | Move tab left |
M-o | Move tab right |
Break a pane into a tab, or cycle the tab's swap layout.
See: Keybindings
Scrolling and search
Scroll mode
| Keys | Action |
|---|---|
C-s | Scroll mode |
j / Down | Scroll down |
k / Up | Scroll up |
C-f / PageDown | Page down |
C-b / PageUp | Page up |
d | Half page down |
u | Half page up |
[ | Previous prompt |
] | Next prompt |
C-c | Scroll to bottom |
C-s enters and leaves Scroll mode; Esc also returns.
See: Keybindings
Search and copy
| Keys | Action |
|---|---|
C-s s | Search forward |
n | Next match |
p | Previous match |
c | Case sensitivity |
w | Wrap |
o | Whole word |
C-s e | Edit scrollback |
C-s c | Copy last command output |
c, w, and o toggle search options.
See: Keybindings
Mouse wheel
| Input | Action |
|---|---|
ScrollUp / ScrollDown | Scroll three lines |
Alt ScrollUp | Previous prompt |
Alt ScrollDown | Next prompt |
Ctrl ScrollUp | Grow |
Ctrl ScrollDown | Shrink |
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
| Keys | Action |
|---|---|
C-o d | Detach |
C-o r | Rename session |
C-o Tab | Switch session |
C-o Left | Previous session |
C-o Right | Next session |
C-o n | Next pane needing attention |
C-o w | Session 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
| Flag | Description |
|---|---|
-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, --debug | Emit debug output |
Flags come from zellij --help; subcommands have their own --help.
See: Documentation
0 Comments for this cheatsheet. Write yours!