---

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

Tabs

Panes

Common Patterns

New tab for specific task:

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

Split pane and run command:

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

New pane with guaranteed working directory:

Copy# 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:

Copyzellij 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

Copy# ❌ 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%)