Controlling TUIs, Agent/Interactive CLIs, etc. with Zellij

This document covers controlling Zellij from the command line: actions, helpers like run and edit, shell completions, plugins, and pipes.

1. Controlling Zellij via CLI

You can control Zellij from inside a running session or from any shell that can reach the session.

Targeting the current session:

zellij action new-pane

Targeting a specific session:

zellij --session pretentious-cat action new-pane

Most interactive features (new panes, tabs, scrolling, focus, plugins, etc.) can be invoked via zellij action ….

Relevant sections in this guide:

• •CLI Actions: all zellij action … commands
• •Zellij Run: starting commands in a new pane via zellij run
• •Zellij Edit: opening files in your editor in a new pane via zellij edit
• •Zellij Plugin / Zellij Pipe: loading and controlling plugins

2. Shell Completions & Convenience Aliases

Zellij can generate shell completions (and some handy aliases) for common shells.

Generate completion scripts:

zellij setup --generate-completion fish
zellij setup --generate-completion bash
zellij setup --generate-completion zsh

Append the output to your shell’s config (e.g. ~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish). See your shell’s docs for exactly where and how to load completion files.

The generated completions also define convenience aliases for opening panes:

zr  tail -f /path/to/my/file   # new pane tailing this file
zrf htop                       # new floating pane with htop
ze  ./main.rs                  # new pane with your editor on ./main.rs

These aliases are thin wrappers around zellij run and zellij edit.

3. zellij run: Run Commands in a New Pane

zellij run opens a new Zellij pane and executes a command inside it.

Basic usage:

zellij run -- git diff

The -- separates zellij options from the command you want to run.

Behavior on exit

When the command exits:

• •The pane does not close immediately by default.
• •The pane frame shows its exit status.
• •Press <ENTER> to re-run the command in the same pane.
• •Press <Ctrl-c> to close the pane.

You can choose to close the pane automatically using --close-on-exit.

Options

-c, --close-on-exit            Close the pane immediately when its command exits
    --cwd <CWD>                Working directory of the new pane
-d, --direction <DIRECTION>    Direction to open the new pane in
-f, --floating                 Open the new pane in floating mode
    --height <HEIGHT>          Floating pane height
-i, --in-place                 Open in place of the current pane, temporarily suspending it
-n, --name <NAME>              Name of the new pane
-s, --start-suspended          Start command suspended; only runs after you press ENTER
    --width <WIDTH>            Floating pane width
-x, --x <X>                    Floating pane X coordinate
-y, --y <Y>                    Floating pane Y coordinate

For HEIGHT, WIDTH, X, and Y:

• •Accept bare integers (e.g. 1)
• •Or percentages (e.g. 10%) where applicable

Note: To avoid typing zellij run in full, use the shell aliases generated by completions (e.g. zr, zrf).

4. zellij edit: Open Files in Your Editor

zellij edit opens your default editor in a new Zellij pane, pointed at a given file.

Examples:

zellij edit ./main.rs                   # open main.rs in a new pane
zellij edit --floating ./main.rs        # open main.rs in a floating pane
zellij edit ./main.rs --line-number 10  # open main.rs at line 10

This saves you from manually creating a pane and then starting the editor yourself.

Options

    --cwd <CWD>                    Working directory of the editor
-d, --direction <DIRECTION>        Direction to open the new pane in
-f, --floating                     Open in floating mode
    --height <HEIGHT>              Floating pane height
-i, --in-place                     Open in place of the current pane, temporarily suspending it
-l, --line-number <LINE_NUMBER>    Open file at the given line number
    --width <WIDTH>                Floating pane width
-x, --x <X>                        Floating pane X coordinate
-y, --y <Y>                        Floating pane Y coordinate

HEIGHT, WIDTH, X, and Y support bare integers (e.g. 1) or percentages (e.g. 10%).

Default editor

The editor used by zellij edit is:

1. •$EDITOR, if set
2. •Else $VISUAL, if set
3. •Or explicitly configured via the scrollback_editor configuration option

To shorten command usage, use the ze alias from shell completions.

5. CLI Actions Reference

All of the following can be invoked via:

zellij action <action-name> [ARGS...]

Many of them mirror keybindings in the UI.

5.1 Pane Management

close-pane

Close the focused pane.

zellij action close-pane

new-pane

Open a new pane in the given direction or as floating. If no direction is given, Zellij uses the largest available space.

Optional ARGS: Command to run instead of the default shell, preceded by --.

Options:

-c, --close-on-exit            Close pane immediately when its command exits
    --cwd <CWD>                Working directory of the new pane
-d, --direction <DIRECTION>    Direction to open the new pane in
-f, --floating                 Open in floating mode
-n, --name <NAME>              Name of the new pane
-s, --start-suspended          Start command suspended; runs after ENTER

Examples:

# New floating pane with default shell
zellij action new-pane -f

# Named pane tailing a log
zellij action new-pane --name "follow this log!" -- tail -f /tmp/my-log-file

This is effectively the same operation as zellij run:

zellij run -- tail -f /tmp/my-log-file

move-pane

Move the focused pane in the given direction.

ARGS: direction [right|left|up|down]

zellij action move-pane left

resize

Resize the focused pane in the given direction.

ARGS: resize direction [right|left|up|down|+|-]

zellij action resize left

rename-pane

Set the name (title) of the focused pane.

ARGS: pane name

zellij action rename-pane "alice the cat"

undo-rename-pane

Remove the previously set name of the focused pane.

zellij action undo-rename-pane

toggle-fullscreen

Toggle between fullscreen focused pane and the normal layout.

zellij action toggle-fullscreen

toggle-pane-embed-or-floating

If the focused pane is floating, embed it. If it’s embedded, float it.

zellij action toggle-pane-embed-or-floating

toggle-pane-frames

Toggle frames around panes.

Note: Zellij uses frames to display UI elements. Hiding them can make things confusing if you’re not used to it.

zellij action toggle-pane-frames

toggle-pane-pinned

If the current pane is floating, toggle whether it is pinned (always on top).

zellij action toggle-pane-pinned

stack-panes

Create a stack from a list of pane IDs. Pane IDs can be obtained via the $ZELLIJ_PANE_ID env var.

ARGS: pane IDs (terminal or plugin, prefixed with terminal_ or plugin_)

# Stack 3 panes: terminal_1, plugin_1, terminal_2
zellij action stack-panes -- terminal_1 plugin_1 terminal_2

5.2 Focus & Navigation

focus-next-pane

Focus the next pane.

zellij action focus-next-pane

focus-previous-pane

Focus the previous pane.

zellij action focus-previous-pane

move-focus

Move the focused pane in the given direction.

ARGS: direction [right|left|up|down]

zellij action move-focus left

move-focus-or-tab

Move focus to the pane in the given direction, or to the next/previous tab if you are at the edge of the screen in that direction.

ARGS: direction [right|left|up|down]

zellij action move-focus-or-tab left

5.3 Tabs

close-tab

Close the current tab.

zellij action close-tab

new-tab

Create a new tab, optionally with a layout and name.

Options:

-c, --cwd <CWD>        Working directory for the new tab
-l, --layout <LAYOUT>  Path to a layout file
-n, --name <NAME>      Tab name

If --layout is given:

• •The tab starts with that layout.
• •If --cwd is also given, all relative paths in that layout are resolved from this cwd and override any global cwd in the layout. (See layout CWD composition in the main docs for details.)

go-to-next-tab

Go to the next tab.

zellij action go-to-next-tab

go-to-previous-tab

Go to the previous tab.

zellij action go-to-previous-tab

go-to-tab

Go to a tab by index.

ARGS: tab index (e.g. 1)

zellij action go-to-tab 1

go-to-tab-name

Go to a tab by name.

ARGS: tab name (e.g. "Tab #1")

Options:

-c, --create    Create the tab if it doesn’t exist

Example:

zellij action go-to-tab-name "Tab #1"

rename-tab

Set the name of the focused tab.

ARGS: tab name

zellij action rename-tab "alice the cat"

undo-rename-tab

Remove the previously set name of the focused tab.

zellij action undo-rename-tab

query-tab-names

Print a list of all tab names to the command line.

zellij action query-tab-names

5.4 Scrolling

All scrolling applies to the focused pane.

scroll-up

Scroll up 1 line.

zellij action scroll-up

scroll-down

Scroll down 1 line.

zellij action scroll-down

scroll-to-bottom

Scroll to the bottom.

zellij action scroll-to-bottom

page-scroll-up

Scroll up one page.

zellij action page-scroll-up

page-scroll-down

Scroll down one page.

zellij action page-scroll-down

half-page-scroll-up

Scroll up half a page.

zellij action half-page-scroll-up

half-page-scroll-down

Scroll down half a page.

zellij action half-page-scroll-down

dump-screen

Dump the pane scrollback to a file.

ARGS: path to output file (e.g. /tmp/screen-dump.txt)

zellij action dump-screen /tmp/screen-dump.txt

edit-scrollback

Open the pane scrollback in your default editor.

zellij action edit-scrollback

5.5 Editing Files via Actions

edit

Open a file in a new pane using your default $EDITOR (just like zellij edit, but as an action).

ARGS: path to the file to open (e.g. ./my-file.rs)

Options:

-d, --direction <DIRECTION> [right|down]   Direction to open the new pane in
-f, --floating                             Open in floating mode
-l, --line-number <LINE_NUMBER>           Open file at the given line number

Examples:

zellij action edit ./my-file.rs -f

You can also use the top-level shorthand without action:

zellij edit ./my-file.rs -f

5.6 Modes, Sync, Floating Panes

switch-mode

Switch the input mode of all connected clients.

ARGS: mode [locked|pane|tab|resize|move|search|session|tmux]

zellij action switch-mode locked

toggle-active-sync-tab

Toggle between sending input to:

• •only the focused pane (default), or
• •all panes in the current tab

zellij action toggle-active-sync-tab

toggle-floating-panes

Toggle visibility of all floating panes in the current tab. If none exist, create one.

zellij action toggle-floating-panes

5.7 Plugins & Clients

launch-or-focus-plugin

Launch a plugin if it’s not running anywhere in the session, or focus it if it is.

ARGS: plugin URL (e.g. file:/path/to/my/plugin.wasm, zellij:strider)

Options:

-f, --floating    Use floating mode when launching the plugin (if not already running)

Example:

zellij action launch-or-focus-plugin zellij:strider --floating

start-or-reload-plugin

Launch a plugin if it’s not running, or reload it (skipping cache) if it is. Useful for plugin development.

ARGS: plugin URL (e.g. file:/path/to/my/plugin.wasm)

zellij action start-or-reload-plugin zellij:strider

list-clients

List clients connected to the current session, including their focused pane ID and running program (when detectable and not the default shell).

Pane IDs:

• •Terminal panes and plugin panes can share numeric IDs.
• •They are distinguished by prefixes like terminal_ or plugin_.
• •Terminal pane IDs match the value from $ZELLIJ_PANE_ID.

Example:

zellij action list-clients

CLIENT_ID ZELLIJ_PANE_ID RUNNING_COMMAND
1         plugin_2       zellij:session-manager
2         terminal_3     vim /tmp/my-file.txt

dump-layout

Dump the current layout of the session to STDOUT.

zellij action dump-layout

5.8 Writing to Panes

write

Write raw bytes to the focused pane.

ARGS: array of byte values (integers)

zellij action write 102 111 111   # writes "foo"

write-chars

Write a string of characters to the focused pane.

ARGS: string

zellij action write-chars "Hi there!"

6. zellij plugin: Launch Plugins

zellij plugin launches a plugin in a new pane from a local or remote WASM file.

Example:

zellij plugin -- https://path/to/my/plugin.wasm

Usage

zellij plugin [OPTIONS] [--] <URL>

ARGS:

<URL>    Plugin URL; can start with http(s):, file:, or zellij:

Options

-c, --configuration <CONFIGURATION>   Plugin configuration
-f, --floating                        Open plugin pane in floating mode
    --height <HEIGHT>                 Floating pane height
-i, --in-place                        Open in place of the current pane, temporarily suspending it
-s, --skip-plugin-cache               Skip memory and disk cache and force recompile (for development)
    --width <WIDTH>                   Floating pane width
-x, --x <X>                           Floating pane X coordinate
-y, --y <Y>                           Floating pane Y coordinate

HEIGHT, WIDTH, X, and Y accept bare integers or percentages just like zellij run.

7. zellij pipe: Communicate with Plugins

zellij pipe sends data to plugins via named “pipes.” If the target plugin isn’t running, Zellij can start it on first message.

Example (basic):

zellij plugin -- https://path/to/my/plugin.wasm

Usage

zellij pipe [OPTIONS] [--] <PAYLOAD>

ARGS:

<PAYLOAD>    Data to send down the pipe.
             If omitted, the command reads from STDIN.

Options

-n, --name <NAME>                            Name of the pipe
-a, --args <ARGS>                            Arguments for the pipe
-p, --plugin <PLUGIN>                        Plugin URL (e.g. file:/path/to/my/plugin.wasm)
                                             If omitted, data is sent to all listening plugins.
                                             If specified and plugin is not running, it will be launched.
-c, --plugin-configuration <PLUGIN_CONFIGURATION>
                                             Plugin configuration.
                                             The same plugin with different configurations is treated as
                                             a different plugin for pipe routing.

Usage patterns

1. Send data to a specific plugin:

zellij pipe \
  --plugin file:/path/to/my/plugin.wasm \
  --name my_pipe_name \
  -- my_arbitrary_data

2. Broadcast to all listening plugins:

zellij pipe --name my_pipe_name -- my_arbitrary_data

3. Stream data via STDIN/STDOUT:

Pipe data into zellij pipe and read what the plugin outputs:

tail -f /tmp/my-live-logfile \
  | zellij pipe --name logs --plugin https://example.com/my-plugin.wasm \
  | wc -l

This lets you integrate plugins into shell pipelines.