--- 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 ` or `zellij -s ` | | List sessions | `zellij list-sessions` | | Kill session | `zellij kill-session ` | | Delete session | `zellij delete-session ` | ### Tabs | Task | Command | |------|---------| | New tab | `zellij action new-tab` | | New tab with name | `zellij action new-tab --name ` | | New tab with cwd | `zellij action new-tab --cwd ` | | New tab with layout | `zellij action new-tab --layout ` | | Close tab | `zellij action close-tab` | | Rename tab | `zellij action rename-tab ` | | Go to tab by name | `zellij action go-to-tab-name ` | | Go to tab by index | `zellij action go-to-tab ` | ### 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 -- ` | | Close pane | `zellij action close-pane` | | Rename pane | `zellij action rename-pane ` | ### Common Patterns **New tab for specific task:** ```bash zellij action new-tab --name "backend" --cwd ~\/api ``` **Split pane and run command:** ```bash zellij action new-pane --direction down -- npm run dev ``` **New pane with guaranteed working directory:** ```bash # 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:** ```bash 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 ```bash # ❌ 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%`)