Zellij Reference

Overview

Quick reference for Zellij CLI commands to manipulate running sessions. Covers session management, tabs, and panes.

When to Use

• Creating or attaching to Zellij sessions

• Managing tabs and panes programmatically

• Need CLI commands (not keybindings)

• Automating Zellij operations

When NOT to use:

• Looking for keybindings (this is CLI only)

• Layout file syntax

• Configuration options

Quick Reference

Sessions

Task Command

Create/attach session zellij attach --create <name> or zellij -s <name>

List sessions zellij list-sessions

Kill session zellij kill-session <name>

Delete session zellij delete-session <name>

Tabs

Task Command

New tab zellij action new-tab

New tab with name zellij action new-tab --name <name>

New tab with cwd zellij action new-tab --cwd <path>

New tab with layout zellij action new-tab --layout <layout>

Close tab zellij action close-tab

Rename tab zellij action rename-tab <name>

Go to tab by name zellij action go-to-tab-name <name>

Go to tab by index zellij action go-to-tab <index>

Panes

Task Command

New pane (auto) zellij action new-pane

Split right zellij action new-pane --direction right

Split down zellij action new-pane --direction down

Floating pane zellij action new-pane --floating

Floating with size zellij action new-pane --floating --width 80% --height 60%

Pane with command zellij action new-pane -- <command>

Close pane zellij action close-pane

Rename pane zellij action rename-pane <name>

Common Patterns

New tab for specific task:

zellij action new-tab --name "backend" --cwd ~/api

Split pane and run command:

zellij action new-pane --direction down -- npm run dev

New pane with guaranteed working directory:

For interactive shell with specific directory

zellij action new-pane --cwd /path/to/dir

For command that must run in specific directory

zellij action new-pane --cwd /path/to/dir -- sh -c 'cd /path/to/dir && your-command'

For nvim that must start in specific directory

zellij action new-pane --cwd /path/to/worktree -- sh -c 'cd /path/to/worktree && nvim'

Floating scratch terminal:

zellij action new-pane --floating --width 90% --height 90%

Common Mistakes

❌ Using new-pane --horizontal

Correct: --direction down (not --horizontal )

❌ Confusing toggle with create

• toggle-floating-panes = show/hide existing floating panes

• new-pane --floating = create NEW floating pane

❌ Forgetting action subcommand Wrong: zellij new-tab

Right: zellij action new-tab

❌ Pane not starting in correct directory Problem: Using --cwd alone doesn't always ensure the command runs in that directory

❌ Wrong - nvim might not start in the right directory

zellij action new-pane --cwd /path/to/worktree -- nvim

✅ Correct - explicitly cd first

zellij action new-pane --cwd /path/to/worktree -- sh -c 'cd /path/to/worktree && nvim'

Notes

• All zellij action commands work inside or outside a session

• Use -- to separate pane command from zellij options

• Direction options: right , left , up , down

• Size units: bare integers or percentages (e.g., 80% )