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

| 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

| 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

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

安装