zellij

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%)