zellij

name	zellij
description	Use when manipulating Zellij sessions, creating tabs or panes, or looking up Zellij CLI commands for terminal multiplexer operations

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