Plugin API - Commands

Zellij exports functions that allow plugins to control Zellij or change its behavior. All functions listed below are available via use zellij_tile::prelude::*;.

For the complete type definitions referenced below, see the Type Reference. For additional details, see the zellij-tile API documentation.

Table of Contents


Subscription Management


subscribe

#![allow(unused)]
fn main() {
fn subscribe(event_types: &[EventType])
}

Subscribe to a list of Events represented by their EventTypes. Once subscribed, the plugin's update method will be called with matching events and their payloads.

Parameters:

ParameterTypeDescription
event_types&[EventType]Slice of event types to subscribe to

Example:

#![allow(unused)]
fn main() {
use zellij_tile::prelude::*;

fn load(&mut self, _configuration: BTreeMap<String, String>) {
    subscribe(&[
        EventType::TabUpdate,
        EventType::PaneUpdate,
        EventType::ModeUpdate,
    ]);
}
}

unsubscribe

#![allow(unused)]
fn main() {
fn unsubscribe(event_types: &[EventType])
}

Unsubscribe from a list of previously subscribed Events.

Parameters:

ParameterTypeDescription
event_types&[EventType]Slice of event types to unsubscribe from

Example:

#![allow(unused)]
fn main() {
unsubscribe(&[EventType::TabUpdate]);
}

Plugin Settings & Permissions


set_selectable

#![allow(unused)]
fn main() {
fn set_selectable(selectable: bool)
}

Set whether the plugin pane is selectable by the user. Unselectable plugins might be desired when they do not accept user input (e.g., status bars).

Parameters:

ParameterTypeDescription
selectablebooltrue to make selectable, false to make unselectable

Example:

#![allow(unused)]
fn main() {
set_selectable(false);
}

show_cursor

#![allow(unused)]
fn main() {
fn show_cursor(cursor_position: Option<(usize, usize)>)
}

Show the cursor at specific coordinates within the plugin pane, or hide it.

Parameters:

ParameterTypeDescription
cursor_positionOption<(usize, usize)>Some((x, y)) to show cursor at coordinates, None to hide

Example:

#![allow(unused)]
fn main() {
show_cursor(Some((5, 10)));

show_cursor(None);
}

request_permission

#![allow(unused)]
fn main() {
fn request_permission(permissions: &[PermissionType])
}

Request permissions from the user. This should be called in the load method of the plugin lifecycle. The user will be prompted to grant or deny the requested permissions. Results are delivered via the PermissionRequestResult event.

Parameters:

ParameterTypeDescription
permissions&[PermissionType]Slice of permissions to request

Example:

#![allow(unused)]
fn main() {
fn load(&mut self, _configuration: BTreeMap<String, String>) {
    request_permission(&[
        PermissionType::ReadApplicationState,
        PermissionType::ChangeApplicationState,
        PermissionType::OpenFiles,
    ]);
    subscribe(&[EventType::PermissionRequestResult]);
}
}

set_self_mouse_selection_support

#![allow(unused)]
fn main() {
fn set_self_mouse_selection_support(selection_support: bool)
}

Enable or disable mouse selection support for the plugin pane.

Parameters:

ParameterTypeDescription
selection_supportbooltrue to enable, false to disable

set_self_collapsed

#![allow(unused)]
fn main() {
fn set_self_collapsed(collapsed: bool)
}

Give this plugin's space in the layout back to its neighbors while it has nothing to draw, or take it again when it does. Meant for plugins mounted in a layout as a bar whose content is sometimes empty: without this, the row the layout reserves for the bar stays reserved and shows as a blank line.

While collapsed, the pane keeps its place and its size in the layout and simply takes no space, so expanding restores exactly the geometry the layout asked for. A collapse also survives entering and leaving fullscreen. Calling it with the state the pane is already in does nothing. It has no effect on a floating pane.

Unlike hide_self, which suppresses the pane and later brings it back by splitting another pane, a collapsed pane comes back in its original position.

The PaneInfo of a collapsed pane has is_collapsed set to true.

Parameters:

ParameterTypeDescription
collapsedbooltrue to give the space back, false to take it again

Example:

#![allow(unused)]
fn main() {
fn render(&mut self, rows: usize, cols: usize) {
    set_self_collapsed(self.items.is_empty());
    for item in &self.items {
        println!("{}", item);
    }
}
}

set_soft_keyboard

#![allow(unused)]
fn main() {
fn set_soft_keyboard(on: bool)
}

Required Permission: ChangeApplicationState

Show or hide the on-screen (soft) keyboard of the client that is displaying this plugin. This is only relevant for clients connected through the web client on a mobile device - other clients ignore it.

Changes to the visibility of the soft keyboard (including ones the user makes) are reported through the SoftKeyboardVisibilityChanged event.

Parameters:

ParameterTypeDescription
onbooltrue to show the soft keyboard, false to hide it

Query / Information Retrieval


get_plugin_ids

#![allow(unused)]
fn main() {
fn get_plugin_ids() -> PluginIds
}

Returns the unique Zellij pane ID for the plugin as well as the Zellij process ID.

Returns: PluginIds - containing plugin_id, zellij_pid, initial_cwd, and client_id

Example:

#![allow(unused)]
fn main() {
let ids = get_plugin_ids();
eprintln!("Plugin ID: {}, Zellij PID: {}", ids.plugin_id, ids.zellij_pid);
}

get_zellij_version

#![allow(unused)]
fn main() {
fn get_zellij_version() -> String
}

Returns the version string of the running Zellij instance. Useful for checking plugin compatibility.

Returns: String - the Zellij version (e.g., "0.42.0")

Example:

#![allow(unused)]
fn main() {
let version = get_zellij_version();
eprintln!("Running on Zellij {}", version);
}

generate_random_name

#![allow(unused)]
fn main() {
fn generate_random_name() -> String
}

Required Permission: ReadApplicationState

Generate a random human-readable name using Zellij's curated word lists. Returns a name in the format AdjectiveNoun (e.g., "BraveRustacean", "ZippyWeasel"). This uses the same word lists as session name generation, providing approximately 4,096 unique combinations.

Returns: String - a random name


get_layout_dir

#![allow(unused)]
fn main() {
fn get_layout_dir() -> String
}

Required Permission: ReadApplicationState

Returns the absolute path to the layout directory. This is where Zellij looks for layout files. It can be:

  • The directory specified via the CLI --layout-dir flag
  • The directory specified in the config file
  • The directory specified via ZELLIJ_LAYOUT_DIR environment variable
  • The default: ~/.config/zellij/layouts

Returns: String - absolute path to the layout directory (empty string if it cannot be determined)


get_session_environment_variables

#![allow(unused)]
fn main() {
fn get_session_environment_variables() -> BTreeMap<String, String>
}

Required Permission: ReadSessionEnvironmentVariables

Returns the environment variables that were present when the Zellij session was created.

Returns: BTreeMap<String, String> - environment variable name-value pairs


get_focused_pane_info

#![allow(unused)]
fn main() {
fn get_focused_pane_info() -> Result<(usize, PaneId), String>
}

Required Permission: ReadApplicationState

Returns the focused pane ID and its tab index for the client associated with this plugin.

Returns: Result<(usize, PaneId), String> - Ok((tab_index, pane_id)) on success

Example:

#![allow(unused)]
fn main() {
match get_focused_pane_info() {
    Ok((tab_index, pane_id)) => {
        eprintln!("Focused pane {:?} in tab {}", pane_id, tab_index);
    },
    Err(e) => eprintln!("Error: {}", e),
}
}

get_pane_info

#![allow(unused)]
fn main() {
fn get_pane_info(pane_id: PaneId) -> Option<PaneInfo>
}

Required Permission: ReadApplicationState

Query detailed information about a specific pane by its PaneId.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to query

Returns: Option<PaneInfo> - pane information, or None if the pane does not exist

Example:

#![allow(unused)]
fn main() {
if let Some(info) = get_pane_info(PaneId::Terminal(1)) {
    eprintln!("Pane title: {}, focused: {}", info.title, info.is_focused);
}
}

get_tab_info

#![allow(unused)]
fn main() {
fn get_tab_info(tab_id: usize) -> Option<TabInfo>
}

Required Permission: ReadApplicationState

Query detailed information about a specific tab by its stable ID.

Parameters:

ParameterTypeDescription
tab_idusizeThe stable tab identifier

Returns: Option<TabInfo> - tab information, or None if the tab does not exist


get_pane_pid

#![allow(unused)]
fn main() {
fn get_pane_pid(pane_id: PaneId) -> Result<i32, String>
}

Required Permission: ReadApplicationState

Get the PID of the process running inside a terminal pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to query (must be a terminal pane)

Returns: Result<i32, String> - the process ID on success


get_pane_running_command

#![allow(unused)]
fn main() {
fn get_pane_running_command(pane_id: PaneId) -> Result<Vec<String>, String>
}

Required Permission: ReadApplicationState

Get the current running command (argv) in a terminal pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to query

Returns: Result<Vec<String>, String> - the command and its arguments


get_pane_cwd

#![allow(unused)]
fn main() {
fn get_pane_cwd(pane_id: PaneId) -> Result<PathBuf, String>
}

Required Permission: ReadApplicationState

Get the current working directory of a pane's process.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to query

Returns: Result<PathBuf, String> - the working directory path


get_session_list

#![allow(unused)]
fn main() {
fn get_session_list() -> Result<SessionListSnapshot, String>
}

Required Permission: ReadApplicationState

Returns a one-shot snapshot of all live and resurrectable sessions on the local machine. Useful for plugins that want a point-in-time view of available sessions without subscribing to SessionUpdate.

Returns: Result<SessionListSnapshot, String>

  • live_sessions: Vec<SessionInfo> - all currently running sessions
  • resurrectable_sessions: Vec<(String, Duration)> - dead-but-resurrectable session names and how long ago they were last alive

Example:

#![allow(unused)]
fn main() {
match get_session_list() {
    Ok(snapshot) => {
        for session in snapshot.live_sessions {
            eprintln!("live: {}", session.name);
        }
    },
    Err(e) => eprintln!("Error: {}", e),
}
}

get_pane_scrollback

#![allow(unused)]
fn main() {
fn get_pane_scrollback(pane_id: PaneId, get_full_scrollback: bool) -> Result<PaneContents, String>
}

Required Permission: ReadPaneContents

Retrieve the scrollback buffer contents of a pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to read
get_full_scrollbackboolIf true, includes lines above and below the viewport

Returns: Result<PaneContents, String> - the pane contents

Example:

#![allow(unused)]
fn main() {
match get_pane_scrollback(PaneId::Terminal(1), false) {
    Ok(contents) => {
        for line in &contents.viewport {
            eprintln!("{}", line);
        }
    },
    Err(e) => eprintln!("Error: {}", e),
}
}

list_clients

#![allow(unused)]
fn main() {
fn list_clients()
}

Required Permission: ReadApplicationState

Request a list of connected clients. Results are delivered asynchronously via the ListClients event. The plugin must subscribe to this event before calling.

Example:

#![allow(unused)]
fn main() {
subscribe(&[EventType::ListClients]);
list_clients();
}

Session Management


save_session

#![allow(unused)]
fn main() {
fn save_session() -> Result<(), String>
}

Required Permission: ReadApplicationState

Save the current session state to disk immediately.

Returns: Result<(), String> - Ok(()) on success


current_session_last_saved_time

#![allow(unused)]
fn main() {
fn current_session_last_saved_time() -> Option<u64>
}

Required Permission: ReadApplicationState

Get the number of milliseconds elapsed since the last session save.

Returns: Option<u64> - milliseconds since last save, or None if never saved


switch_session

#![allow(unused)]
fn main() {
fn switch_session(name: Option<&str>)
}

Required Permission: ChangeApplicationState

Switch to a named session, or create a new session with a random name if None is provided.

Parameters:

ParameterTypeDescription
nameOption<&str>Session name to switch to, or None for a new session

Example:

#![allow(unused)]
fn main() {
switch_session(Some("my-project"));

switch_session(None);
}

switch_session_with_layout

#![allow(unused)]
fn main() {
fn switch_session_with_layout(
    name: Option<&str>,
    layout: LayoutInfo,
    cwd: Option<PathBuf>,
)
}

Required Permission: ChangeApplicationState

Switch to a session with a specific layout and optional working directory. If the session does not exist, it is created with the given layout.

Parameters:

ParameterTypeDescription
nameOption<&str>Session name, or None for a new session
layoutLayoutInfoLayout to apply
cwdOption<PathBuf>Working directory for the session

switch_session_with_cwd

#![allow(unused)]
fn main() {
fn switch_session_with_cwd(name: Option<&str>, cwd: Option<PathBuf>)
}

Required Permission: ChangeApplicationState

Switch to a session with a specific working directory.

Parameters:

ParameterTypeDescription
nameOption<&str>Session name, or None for a new session
cwdOption<PathBuf>Working directory for the session

switch_session_with_focus

#![allow(unused)]
fn main() {
fn switch_session_with_focus(
    name: &str,
    tab_position: Option<usize>,
    pane_id: Option<(u32, bool)>,
)
}

Required Permission: ChangeApplicationState

Switch to a session, focusing a specific pane or tab. The pane is prioritized over the tab position if both are provided.

Parameters:

ParameterTypeDescription
name&strSession name to switch to
tab_positionOption<usize>Tab position to focus
pane_idOption<(u32, bool)>Pane to focus: (id, is_plugin)

switch_session_with_options

#![allow(unused)]
fn main() {
fn switch_session_with_options(connect_to_session: ConnectToSession)
}

Required Permission: ChangeApplicationState

Switch to (or create) a session, with every option of ConnectToSession available at once: name, tab, pane, layout, working directory and switch context. Of the switch context, only startup_card and disconnect_others are taken from a plugin.

Parameters:

ParameterTypeDescription
connect_to_sessionConnectToSessionWhere to switch and how

Example:

#![allow(unused)]
fn main() {
switch_session_with_options(ConnectToSession {
    name: Some("my-project".to_owned()),
    cwd: Some(PathBuf::from("/home/user/project")),
    ..Default::default()
});
}

switch_session_and_close_current

#![allow(unused)]
fn main() {
fn switch_session_and_close_current(
    name: &str,
    tab_position: Option<usize>,
    pane_id: Option<(u32, bool)>,
)
}

Required Permission: ChangeApplicationState

Switch to another session and close the current one if it was never used. The current session is killed only if no command was ever submitted in it and no other clients are attached to it. Otherwise this behaves like switch_session_with_focus.

Parameters:

ParameterTypeDescription
name&strSession name to switch to
tab_positionOption<usize>Tab position to focus
pane_idOption<(u32, bool)>Pane to focus: (id, is_plugin)

rename_session

#![allow(unused)]
fn main() {
fn rename_session(name: &str)
}

Required Permission: ChangeApplicationState

Rename the current session.

Parameters:

ParameterTypeDescription
name&strNew session name

delete_dead_session

#![allow(unused)]
fn main() {
fn delete_dead_session(name: &str) -> Result<(), String>
}

Required Permission: ChangeApplicationState

Permanently delete a resurrectable (dead) session with the given name. Blocks until the deletion has been acknowledged, so that subsequent session queries reflect it.

Parameters:

ParameterTypeDescription
name&strName of the dead session to delete

Returns: Result<(), String> - an error message if the session could not be deleted

Changed in 0.45.0: this function used to return () and was fire-and-forget. Plugins that ignore the result need to handle it (eg. with let _ = ...) in order to compile.


delete_all_dead_sessions

#![allow(unused)]
fn main() {
fn delete_all_dead_sessions() -> Result<(), String>
}

Required Permission: ChangeApplicationState

Permanently delete all resurrectable (dead) sessions on this machine. Blocks until the deletion has been acknowledged.

Returns: Result<(), String> - an error message if the sessions could not be deleted

Changed in 0.45.0: this function used to return () and was fire-and-forget.


kill_sessions

#![allow(unused)]
fn main() {
fn kill_sessions<S: AsRef<str>>(session_names: &[S]) -> Result<(), String>
}

Required Permission: ChangeApplicationState

Kill one or more sessions by name. Blocks until the sessions have been killed.

Parameters:

ParameterTypeDescription
session_names&[S]Slice of session names to kill

Returns: Result<(), String> - an error message if the sessions could not be killed

Example:

#![allow(unused)]
fn main() {
kill_sessions(&["old-session", "temp-session"])?;
}

Changed in 0.45.0: this function used to return () and was fire-and-forget.


detach

#![allow(unused)]
fn main() {
fn detach()
}

Required Permission: ChangeApplicationState

Detach the user from the active session.


disconnect_other_clients

#![allow(unused)]
fn main() {
fn disconnect_other_clients()
}

Required Permission: ChangeApplicationState

Disconnect all other clients from the current session.


quit_zellij

#![allow(unused)]
fn main() {
fn quit_zellij()
}

Required Permission: ChangeApplicationState

Completely quit Zellij for this and all other connected clients.


File Opening (Editor Panes)

All file opening commands open files in the user's default $EDITOR.


open_file

#![allow(unused)]
fn main() {
fn open_file(
    file_to_open: FileToOpen,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: OpenFiles

Open a file in the user's default $EDITOR in a new tiled pane.

Parameters:

ParameterTypeDescription
file_to_openFileToOpenFile path, optional line number, and optional cwd
contextBTreeMap<String, String>Arbitrary context returned in EditPaneOpened/EditPaneExited events

Returns: Option<PaneId> - the ID of the opened pane, if available

Example:

#![allow(unused)]
fn main() {
let file = FileToOpen {
    path: PathBuf::from("src/main.rs"),
    line_number: Some(42),
    cwd: None,
};
let pane_id = open_file(file, BTreeMap::new());
}

open_file_floating

#![allow(unused)]
fn main() {
fn open_file_floating(
    file_to_open: FileToOpen,
    coordinates: Option<FloatingPaneCoordinates>,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: OpenFiles

Open a file in the user's default $EDITOR in a new floating pane.

Parameters:

ParameterTypeDescription
file_to_openFileToOpenFile path, optional line number, and optional cwd
coordinatesOption<FloatingPaneCoordinates>Optional position and size
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the ID of the opened pane


open_file_in_place

#![allow(unused)]
fn main() {
fn open_file_in_place(
    file_to_open: FileToOpen,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: OpenFiles

Open a file in the user's default $EDITOR, temporarily replacing the focused pane.

Parameters:

ParameterTypeDescription
file_to_openFileToOpenFile to open
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the ID of the opened pane


open_file_near_plugin

#![allow(unused)]
fn main() {
fn open_file_near_plugin(
    file_to_open: FileToOpen,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: OpenFiles

Open a file in the user's default $EDITOR in the same tab as the plugin as a tiled pane, regardless of the user's focus.

Parameters:

ParameterTypeDescription
file_to_openFileToOpenFile to open
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the ID of the opened pane


open_file_floating_near_plugin

#![allow(unused)]
fn main() {
fn open_file_floating_near_plugin(
    file_to_open: FileToOpen,
    coordinates: Option<FloatingPaneCoordinates>,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: OpenFiles

Open a file in the user's default $EDITOR in the same tab as the plugin as a floating pane, regardless of the user's focus.

Parameters:

ParameterTypeDescription
file_to_openFileToOpenFile to open
coordinatesOption<FloatingPaneCoordinates>Optional position and size
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the ID of the opened pane


open_file_in_place_of_plugin

#![allow(unused)]
fn main() {
fn open_file_in_place_of_plugin(
    file_to_open: FileToOpen,
    close_plugin_after_replace: bool,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: OpenFiles

Open a file in the user's default $EDITOR, replacing the plugin pane itself, regardless of the user's focus.

Parameters:

ParameterTypeDescription
file_to_openFileToOpenFile to open
close_plugin_after_replaceboolIf true, close the plugin pane after replacement
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the ID of the opened pane


open_edit_pane_in_place_of_pane_id

#![allow(unused)]
fn main() {
fn open_edit_pane_in_place_of_pane_id(
    pane_id: PaneId,
    file_to_open: FileToOpen,
    close_replaced_pane: bool,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: OpenFiles

Open a file in the user's default $EDITOR, replacing an arbitrary pane by its ID.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to replace
file_to_openFileToOpenFile to open
close_replaced_paneboolIf true, close the replaced pane; if false, suppress it
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the ID of the opened pane


Terminal Pane Opening


open_terminal

#![allow(unused)]
fn main() {
fn open_terminal<P: AsRef<Path>>(path: P) -> Option<PaneId>
}

Required Permission: OpenTerminalsOrPlugins

Open a new terminal pane at the specified working directory.

Parameters:

ParameterTypeDescription
pathimpl AsRef<Path>Working directory for the new terminal

Returns: Option<PaneId> - the ID of the opened pane

Example:

#![allow(unused)]
fn main() {
let pane_id = open_terminal("/home/user/project");
}

open_terminal_near_plugin

#![allow(unused)]
fn main() {
fn open_terminal_near_plugin<P: AsRef<Path>>(path: P) -> Option<PaneId>
}

Required Permission: OpenTerminalsOrPlugins

Open a new tiled terminal in the tab where the plugin resides, regardless of the user's focus.

Parameters:

ParameterTypeDescription
pathimpl AsRef<Path>Working directory for the new terminal

Returns: Option<PaneId> - the ID of the opened pane


open_terminal_floating

#![allow(unused)]
fn main() {
fn open_terminal_floating<P: AsRef<Path>>(
    path: P,
    coordinates: Option<FloatingPaneCoordinates>,
) -> Option<PaneId>
}

Required Permission: OpenTerminalsOrPlugins

Open a new floating terminal pane at the specified working directory.

Parameters:

ParameterTypeDescription
pathimpl AsRef<Path>Working directory for the new terminal
coordinatesOption<FloatingPaneCoordinates>Optional position and size

Returns: Option<PaneId> - the ID of the opened pane


open_terminal_floating_near_plugin

#![allow(unused)]
fn main() {
fn open_terminal_floating_near_plugin<P: AsRef<Path>>(
    path: P,
    coordinates: Option<FloatingPaneCoordinates>,
) -> Option<PaneId>
}

Required Permission: OpenTerminalsOrPlugins

Open a new floating terminal in the tab where the plugin resides, regardless of the user's focus.

Parameters:

ParameterTypeDescription
pathimpl AsRef<Path>Working directory for the new terminal
coordinatesOption<FloatingPaneCoordinates>Optional position and size

Returns: Option<PaneId> - the ID of the opened pane


open_terminal_in_place

#![allow(unused)]
fn main() {
fn open_terminal_in_place<P: AsRef<Path>>(path: P) -> Option<PaneId>
}

Required Permission: OpenTerminalsOrPlugins

Open a new terminal pane, temporarily replacing the focused pane.

Parameters:

ParameterTypeDescription
pathimpl AsRef<Path>Working directory for the new terminal

Returns: Option<PaneId> - the ID of the opened pane


open_terminal_in_place_of_plugin

#![allow(unused)]
fn main() {
fn open_terminal_in_place_of_plugin<P: AsRef<Path>>(
    path: P,
    close_plugin_after_replace: bool,
) -> Option<PaneId>
}

Required Permission: OpenTerminalsOrPlugins

Open a new terminal pane, replacing the plugin pane, regardless of the user's focus.

Parameters:

ParameterTypeDescription
pathimpl AsRef<Path>Working directory for the new terminal
close_plugin_after_replaceboolIf true, close the plugin; if false, suppress it

Returns: Option<PaneId> - the ID of the opened pane


open_terminal_pane_in_place_of_pane_id

#![allow(unused)]
fn main() {
fn open_terminal_pane_in_place_of_pane_id<P: AsRef<Path>>(
    pane_id: PaneId,
    cwd: P,
    close_replaced_pane: bool,
) -> Option<PaneId>
}

Required Permission: OpenTerminalsOrPlugins

Open a new terminal pane, replacing an arbitrary pane by its ID.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to replace
cwdimpl AsRef<Path>Working directory for the new terminal
close_replaced_paneboolIf true, close the replaced pane; if false, suppress it

Returns: Option<PaneId> - the ID of the opened pane


Command Pane Opening

Command panes allow the user to control the command, re-run it, and see its exit status through the Zellij UI.


open_command_pane

#![allow(unused)]
fn main() {
fn open_command_pane(
    command_to_run: CommandToRun,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: RunCommands

Open a new command pane with the specified command and arguments.

Parameters:

ParameterTypeDescription
command_to_runCommandToRunCommand path, args, and optional cwd
contextBTreeMap<String, String>Arbitrary context returned in CommandPaneOpened/CommandPaneExited events

Returns: Option<PaneId> - the ID of the opened pane

Example:

#![allow(unused)]
fn main() {
let cmd = CommandToRun {
    path: PathBuf::from("cargo"),
    args: vec!["test".to_string()],
    cwd: Some(PathBuf::from("/home/user/project")),
};
let pane_id = open_command_pane(cmd, BTreeMap::new());
}

open_command_pane_near_plugin

#![allow(unused)]
fn main() {
fn open_command_pane_near_plugin(
    command_to_run: CommandToRun,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: RunCommands

Open a new command pane in the same tab as the plugin, regardless of the user's focus.

Parameters:

ParameterTypeDescription
command_to_runCommandToRunCommand to execute
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the ID of the opened pane


open_command_pane_floating

#![allow(unused)]
fn main() {
fn open_command_pane_floating(
    command_to_run: CommandToRun,
    coordinates: Option<FloatingPaneCoordinates>,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: RunCommands

Open a new floating command pane.

Parameters:

ParameterTypeDescription
command_to_runCommandToRunCommand to execute
coordinatesOption<FloatingPaneCoordinates>Optional position and size
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the ID of the opened pane


open_command_pane_floating_near_plugin

#![allow(unused)]
fn main() {
fn open_command_pane_floating_near_plugin(
    command_to_run: CommandToRun,
    coordinates: Option<FloatingPaneCoordinates>,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: RunCommands

Open a new floating command pane in the same tab as the plugin, regardless of the user's focus.

Parameters:

ParameterTypeDescription
command_to_runCommandToRunCommand to execute
coordinatesOption<FloatingPaneCoordinates>Optional position and size
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the ID of the opened pane


open_command_pane_in_place

#![allow(unused)]
fn main() {
fn open_command_pane_in_place(
    command_to_run: CommandToRun,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: RunCommands

Open a new command pane, temporarily replacing the focused pane.

Parameters:

ParameterTypeDescription
command_to_runCommandToRunCommand to execute
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the ID of the opened pane


open_command_pane_in_place_of_plugin

#![allow(unused)]
fn main() {
fn open_command_pane_in_place_of_plugin(
    command_to_run: CommandToRun,
    close_plugin_after_replace: bool,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: RunCommands

Open a new command pane, replacing the plugin pane, regardless of the user's focus.

Parameters:

ParameterTypeDescription
command_to_runCommandToRunCommand to execute
close_plugin_after_replaceboolIf true, close the plugin; if false, suppress it
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the ID of the opened pane


open_command_pane_in_place_of_pane_id

#![allow(unused)]
fn main() {
fn open_command_pane_in_place_of_pane_id(
    pane_id: PaneId,
    command_to_run: CommandToRun,
    close_replaced_pane: bool,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: RunCommands

Open a new command pane, replacing an arbitrary pane by its ID.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to replace
command_to_runCommandToRunCommand to execute
close_replaced_paneboolIf true, close the replaced pane; if false, suppress it
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the ID of the opened pane


open_command_pane_background

#![allow(unused)]
fn main() {
fn open_command_pane_background(
    command_to_run: CommandToRun,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: RunCommands

Open a new hidden (background/suppressed) command pane. The pane runs but is not visible in the UI.

Parameters:

ParameterTypeDescription
command_to_runCommandToRunCommand to execute
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the ID of the opened pane


rerun_command_pane

#![allow(unused)]
fn main() {
fn rerun_command_pane(terminal_pane_id: u32)
}

Required Permission: ChangeApplicationState

Re-run the command in an existing command pane.

Parameters:

ParameterTypeDescription
terminal_pane_idu32The terminal pane ID of the command pane

New Tab Opening


new_tab

#![allow(unused)]
fn main() {
fn new_tab<S: AsRef<str>>(name: Option<S>, cwd: Option<S>) -> Option<usize>
}

Required Permission: ChangeApplicationState

Open a new tab with the default layout.

Parameters:

ParameterTypeDescription
nameOption<impl AsRef<str>>Optional name for the new tab
cwdOption<impl AsRef<str>>Optional working directory

Returns: Option<usize> - the tab ID of the new tab

Example:

#![allow(unused)]
fn main() {
let tab_id = new_tab(Some("build"), Some("/home/user/project"));
}

new_tabs_with_layout

#![allow(unused)]
fn main() {
fn new_tabs_with_layout(layout: &str) -> Vec<usize>
}

Required Permission: ChangeApplicationState

Apply a stringified KDL layout to the current session. If the layout defines multiple tabs, all are opened.

Parameters:

ParameterTypeDescription
layout&strKDL layout string

Returns: Vec<usize> - the tab IDs of all created tabs

Example:

#![allow(unused)]
fn main() {
let tab_ids = new_tabs_with_layout(r#"
layout {
    tab name="code" {
        pane
        pane split_direction="vertical" {
            pane command="cargo" { args "watch"; }
        }
    }
}
"#);
}

new_tabs_with_layout_info

#![allow(unused)]
fn main() {
fn new_tabs_with_layout_info<L: AsRef<LayoutInfo>>(layout_info: L) -> Vec<usize>
}

Required Permission: ChangeApplicationState

Apply a LayoutInfo to the current session in new tabs.

Parameters:

ParameterTypeDescription
layout_infoimpl AsRef<LayoutInfo>Layout specification

Returns: Vec<usize> - the tab IDs of all created tabs


open_command_pane_in_new_tab

#![allow(unused)]
fn main() {
fn open_command_pane_in_new_tab(
    command_to_run: CommandToRun,
    context: BTreeMap<String, String>,
) -> (Option<usize>, Option<PaneId>)
}

Required Permission: RunCommands

Open a new tab with a command pane running the specified command.

Changed in 0.45.0: this function used to require ChangeApplicationState.

Parameters:

ParameterTypeDescription
command_to_runCommandToRunCommand to execute
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: (Option<usize>, Option<PaneId>) - the tab ID and pane ID of the created tab and pane


open_plugin_pane_in_new_tab

#![allow(unused)]
fn main() {
fn open_plugin_pane_in_new_tab(
    plugin_url: impl ToString,
    configuration: BTreeMap<String, String>,
    context: BTreeMap<String, String>,
) -> (Option<usize>, Option<PaneId>)
}

Required Permission: ChangeApplicationState

Open a new tab with a plugin pane loaded from the specified URL.

Parameters:

ParameterTypeDescription
plugin_urlimpl ToStringPlugin URL (e.g., "file:/path/to/plugin.wasm" or a named alias)
configurationBTreeMap<String, String>Plugin configuration key-value pairs
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: (Option<usize>, Option<PaneId>) - the tab ID and pane ID


open_plugin_pane_floating

#![allow(unused)]
fn main() {
fn open_plugin_pane_floating(
    plugin_url: &str,
    configuration: BTreeMap<String, String>,
    coordinates: Option<FloatingPaneCoordinates>,
    context: BTreeMap<String, String>,
) -> Option<PaneId>
}

Required Permission: OpenTerminalsOrPlugins

Open a new floating plugin pane loaded from the specified URL.

Parameters:

ParameterTypeDescription
plugin_url&strPlugin URL (e.g., "file:/path/to/plugin.wasm" or a named alias)
configurationBTreeMap<String, String>Plugin configuration key-value pairs
coordinatesOption<FloatingPaneCoordinates>Optional position and size for the floating pane
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Option<PaneId> - the pane ID of the created plugin pane, if successful


open_editor_pane_in_new_tab

#![allow(unused)]
fn main() {
fn open_editor_pane_in_new_tab(
    file_to_open: FileToOpen,
    context: BTreeMap<String, String>,
) -> (Option<usize>, Option<PaneId>)
}

Required Permission: OpenFiles

Open a new tab with an editor pane for the specified file.

Changed in 0.45.0: this function used to require ChangeApplicationState.

Parameters:

ParameterTypeDescription
file_to_openFileToOpenFile to open
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: (Option<usize>, Option<PaneId>) - the tab ID and pane ID


new_tab_unfocused

#![allow(unused)]
fn main() {
fn new_tab_unfocused(name: Option<String>, cwd: Option<PathBuf>) -> Option<usize>
}

Required Permission: ChangeApplicationState

Open a new tab in the background, without changing the focus of any client. To open a new tab and focus it, see new_tab.

Parameters:

ParameterTypeDescription
nameOption<String>Optional name for the new tab
cwdOption<PathBuf>Optional working directory for the new tab

Returns: Option<usize> - the id of the created tab, if successful


new_tiled_pane_in_tab

#![allow(unused)]
fn main() {
fn new_tiled_pane_in_tab(tab_position: usize) -> Option<PaneId>
}

Required Permission: OpenTerminalsOrPlugins

Open a new tiled pane running the default shell in the tab at the given position.

Parameters:

ParameterTypeDescription
tab_positionusizeThe position of the tab in which to open the pane

Returns: Option<PaneId> - the id of the created pane, if successful


new_pane

#![allow(unused)]
fn main() {
fn new_pane()
}

Required Permission: ChangeApplicationState

Open a new tiled pane running the default shell in the focused tab.


Tab Navigation & Management


switch_tab_to

#![allow(unused)]
fn main() {
fn switch_tab_to(tab_idx: u32)
}

Required Permission: ChangeApplicationState

Change the focused tab to the specified index. Tab indices correspond to the default tab names, starting at 1. An index of 0 is treated as 1.

Parameters:

ParameterTypeDescription
tab_idxu32Tab index (1-based)

go_to_next_tab

#![allow(unused)]
fn main() {
fn go_to_next_tab()
}

Required Permission: ChangeApplicationState

Switch to the next tab, wrapping around to the first tab if at the end.


go_to_previous_tab

#![allow(unused)]
fn main() {
fn go_to_previous_tab()
}

Required Permission: ChangeApplicationState

Switch to the previous tab, wrapping around to the last tab if at the beginning.


go_to_tab_name

#![allow(unused)]
fn main() {
fn go_to_tab_name(tab_name: &str)
}

Required Permission: ChangeApplicationState

Switch to the tab with the specified name.

Parameters:

ParameterTypeDescription
tab_name&strName of the tab to focus

focus_or_create_tab

#![allow(unused)]
fn main() {
fn focus_or_create_tab(tab_name: &str) -> Option<usize>
}

Required Permission: ChangeApplicationState

Focus the tab with the specified name, or create it if it does not exist.

Parameters:

ParameterTypeDescription
tab_name&strName of the tab to focus or create

Returns: Option<usize> - the tab ID


go_to_tab

#![allow(unused)]
fn main() {
fn go_to_tab(tab_index: u32)
}

Required Permission: ChangeApplicationState

Switch to a tab by its index.

Parameters:

ParameterTypeDescription
tab_indexu32Tab index

toggle_tab

#![allow(unused)]
fn main() {
fn toggle_tab()
}

Required Permission: ChangeApplicationState

Toggle to the previously focused tab (regardless of tab position).


close_focused_tab

#![allow(unused)]
fn main() {
fn close_focused_tab()
}

Required Permission: ChangeApplicationState

Close the currently focused tab.


close_tab_with_index

#![allow(unused)]
fn main() {
fn close_tab_with_index(tab_index: usize)
}

Required Permission: ChangeApplicationState

Close a tab by its position index.

Parameters:

ParameterTypeDescription
tab_indexusizeTab position index

close_tab_with_id

#![allow(unused)]
fn main() {
fn close_tab_with_id(tab_id: u64)
}

Required Permission: ChangeApplicationState

Close a tab by its stable ID.

Parameters:

ParameterTypeDescription
tab_idu64Stable tab identifier

rename_tab

#![allow(unused)]
fn main() {
fn rename_tab<S: AsRef<str>>(tab_position: u32, new_name: S)
}

Required Permission: ChangeApplicationState

Rename a tab by its position.

Parameters:

ParameterTypeDescription
tab_positionu32Tab position
new_nameimpl AsRef<str>New tab name

rename_tab_with_id

#![allow(unused)]
fn main() {
fn rename_tab_with_id<S: AsRef<str>>(tab_id: u64, new_name: S)
}

Required Permission: ChangeApplicationState

Rename a tab by its stable ID.

Parameters:

ParameterTypeDescription
tab_idu64Stable tab identifier
new_nameimpl AsRef<str>New tab name

undo_rename_tab

#![allow(unused)]
fn main() {
fn undo_rename_tab()
}

Required Permission: ChangeApplicationState

Undo the last tab rename, reverting to the previous name.


toggle_active_tab_sync

#![allow(unused)]
fn main() {
fn toggle_active_tab_sync()
}

Required Permission: ChangeApplicationState

Toggle STDIN synchronization for the current tab. When active, input is broadcast to all panes in the tab.


break_panes_to_new_tab

#![allow(unused)]
fn main() {
fn break_panes_to_new_tab(
    pane_ids: &[PaneId],
    new_tab_name: Option<String>,
    should_change_focus_to_new_tab: bool,
) -> Option<usize>
}

Required Permission: ChangeApplicationState

Move the specified panes to a new tab.

Parameters:

ParameterTypeDescription
pane_ids&[PaneId]Panes to move
new_tab_nameOption<String>Optional name for the new tab
should_change_focus_to_new_tabboolWhether to switch focus to the new tab

Returns: Option<usize> - the tab ID of the new tab


break_panes_to_tab_with_index

#![allow(unused)]
fn main() {
fn break_panes_to_tab_with_index(
    pane_ids: &[PaneId],
    tab_index: usize,
    should_change_focus_to_new_tab: bool,
) -> Option<usize>
}

Required Permission: ChangeApplicationState

Move the specified panes to an existing tab by index.

Parameters:

ParameterTypeDescription
pane_ids&[PaneId]Panes to move
tab_indexusizeTarget tab position index
should_change_focus_to_new_tabboolWhether to switch focus to the target tab

Returns: Option<usize> - the tab ID


break_panes_to_tab_with_id

#![allow(unused)]
fn main() {
fn break_panes_to_tab_with_id(
    pane_ids: &[PaneId],
    tab_id: usize,
    should_change_focus_to_target_tab: bool,
) -> Option<usize>
}

Required Permission: ChangeApplicationState

Move the specified panes to an existing tab by its stable ID.

Parameters:

ParameterTypeDescription
pane_ids&[PaneId]Panes to move
tab_idusizeTarget tab stable ID
should_change_focus_to_target_tabboolWhether to switch focus to the target tab

Returns: Option<usize> - the tab ID


Pane Focus & Visibility


hide_self

#![allow(unused)]
fn main() {
fn hide_self()
}

Hide (suppress) the plugin pane from the UI. The plugin continues running in the background.

A hidden plugin is not rendered, but it keeps receiving the ModeUpdate, TabUpdate, PaneUpdate and InputReceived events it is subscribed to, so it can decide when to show itself again with show_self. The same is true for plugins hidden with hide_pane_with_id or hide_slot.

To give a bar's row in the layout back while it is empty, and get it back in the same position later, use set_self_collapsed instead.


show_self

#![allow(unused)]
fn main() {
fn show_self(should_float_if_hidden: bool)
}

Show the plugin pane (unsuppress it if suppressed), focus it, and switch to its tab.

Parameters:

ParameterTypeDescription
should_float_if_hiddenboolIf true, show as a floating pane when unsuppressing

close_self

#![allow(unused)]
fn main() {
fn close_self()
}

Close this plugin pane entirely.


hide_pane_with_id

#![allow(unused)]
fn main() {
fn hide_pane_with_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Hide (suppress) a specific pane from the UI.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to hide

show_pane_with_id

#![allow(unused)]
fn main() {
fn show_pane_with_id(
    pane_id: PaneId,
    should_float_if_hidden: bool,
    should_focus_pane: bool,
)
}

Required Permission: ChangeApplicationState

Show a specific pane (unsuppress it if suppressed), optionally focusing it and switching to its tab.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to show
should_float_if_hiddenboolIf true, show as floating when unsuppressing
should_focus_paneboolIf true, focus the pane after showing

focus_next_pane

#![allow(unused)]
fn main() {
fn focus_next_pane()
}

Required Permission: ChangeApplicationState

Move focus to the next pane in chronological order.


focus_previous_pane

#![allow(unused)]
fn main() {
fn focus_previous_pane()
}

Required Permission: ChangeApplicationState

Move focus to the previous pane in chronological order.


focus_last_pane

#![allow(unused)]
fn main() {
fn focus_last_pane()
}

Required Permission: None

Move focus back to the pane that was focused before the currently focused one. Takes floating panes into account, and swaps the pane in place when the focused pane is fullscreen.


focus_host_session

#![allow(unused)]
fn main() {
fn focus_host_session()
}

Required Permission: ChangeApplicationState

When this session is running inside another Zellij session (see nested sessions), move focus up to the host (outer) session. Has no effect when the session is not nested.


move_focus

#![allow(unused)]
fn main() {
fn move_focus(direction: Direction)
}

Required Permission: ChangeApplicationState

Move focus to the pane in the specified direction.

Parameters:

ParameterTypeDescription
directionDirectionLeft, Right, Up, or Down

move_focus_or_tab

#![allow(unused)]
fn main() {
fn move_focus_or_tab(direction: Direction)
}

Required Permission: ChangeApplicationState

Move focus in the specified direction. If the focused pane is at the edge of the screen, the next or previous tab is focused instead.

Parameters:

ParameterTypeDescription
directionDirectionLeft, Right, Up, or Down

focus_terminal_pane

#![allow(unused)]
fn main() {
fn focus_terminal_pane(
    terminal_pane_id: u32,
    should_float_if_hidden: bool,
    should_be_in_place_if_hidden: bool,
)
}

Required Permission: ChangeApplicationState

Focus a specific terminal pane by its ID, unsuppressing it if necessary and switching to its tab.

Parameters:

ParameterTypeDescription
terminal_pane_idu32Terminal pane ID
should_float_if_hiddenboolShow as floating when unsuppressing
should_be_in_place_if_hiddenboolShow in-place (replacing the focused pane) when unsuppressing

focus_plugin_pane

#![allow(unused)]
fn main() {
fn focus_plugin_pane(
    plugin_pane_id: u32,
    should_float_if_hidden: bool,
    should_be_in_place_if_hidden: bool,
)
}

Required Permission: ChangeApplicationState

Focus a specific plugin pane by its ID, unsuppressing it if necessary and switching to its tab.

Parameters:

ParameterTypeDescription
plugin_pane_idu32Plugin pane ID
should_float_if_hiddenboolShow as floating when unsuppressing
should_be_in_place_if_hiddenboolShow in-place when unsuppressing

focus_pane_with_id

#![allow(unused)]
fn main() {
fn focus_pane_with_id(
    pane_id: PaneId,
    should_float_if_hidden: bool,
    should_be_in_place_if_hidden: bool,
)
}

Required Permission: ChangeApplicationState

Focus any pane by its PaneId. This is a convenience wrapper around focus_terminal_pane and focus_plugin_pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to focus
should_float_if_hiddenboolShow as floating when unsuppressing
should_be_in_place_if_hiddenboolShow in-place when unsuppressing

show_floating_panes

#![allow(unused)]
fn main() {
fn show_floating_panes(tab_id: Option<usize>) -> Result<bool, String>
}

Required Permission: ChangeApplicationState

Show all floating panes in the specified tab, or the active tab if None.

Parameters:

ParameterTypeDescription
tab_idOption<usize>Tab ID, or None for the active tab

Returns: Result<bool, String> - whether floating panes are now visible


hide_floating_panes

#![allow(unused)]
fn main() {
fn hide_floating_panes(tab_id: Option<usize>) -> Result<bool, String>
}

Required Permission: ChangeApplicationState

Hide all floating panes in the specified tab, or the active tab if None.

Parameters:

ParameterTypeDescription
tab_idOption<usize>Tab ID, or None for the active tab

Returns: Result<bool, String> - whether floating panes are now hidden


toggle_floating_panes

#![allow(unused)]
fn main() {
fn toggle_floating_panes(tab_id: Option<u64>)
}

Required Permission: ChangeApplicationState

Toggle the visibility of the floating panes in the specified tab, or the active tab if None.

Parameters:

ParameterTypeDescription
tab_idOption<u64>Tab ID, or None for the active tab

Pane Manipulation


close_focus

#![allow(unused)]
fn main() {
fn close_focus()
}

Required Permission: ChangeApplicationState

Close the currently focused pane.


close_terminal_pane

#![allow(unused)]
fn main() {
fn close_terminal_pane(terminal_pane_id: u32)
}

Required Permission: ChangeApplicationState

Close a terminal pane by its ID.

Parameters:

ParameterTypeDescription
terminal_pane_idu32Terminal pane ID to close

close_plugin_pane

#![allow(unused)]
fn main() {
fn close_plugin_pane(plugin_pane_id: u32)
}

Required Permission: ChangeApplicationState

Close a plugin pane by its ID.

Parameters:

ParameterTypeDescription
plugin_pane_idu32Plugin pane ID to close

close_pane_with_id

#![allow(unused)]
fn main() {
fn close_pane_with_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Close any pane by its PaneId. Convenience wrapper around close_terminal_pane and close_plugin_pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to close

close_multiple_panes

#![allow(unused)]
fn main() {
fn close_multiple_panes(pane_ids: Vec<PaneId>)
}

Required Permission: ChangeApplicationState

Close multiple panes at once.

Parameters:

ParameterTypeDescription
pane_idsVec<PaneId>Panes to close

rename_terminal_pane

#![allow(unused)]
fn main() {
fn rename_terminal_pane<S: AsRef<str>>(terminal_pane_id: u32, new_name: S)
}

Required Permission: ChangeApplicationState

Rename a terminal pane (changes the title displayed in the UI).

Parameters:

ParameterTypeDescription
terminal_pane_idu32Terminal pane ID
new_nameimpl AsRef<str>New name

rename_plugin_pane

#![allow(unused)]
fn main() {
fn rename_plugin_pane<S: AsRef<str>>(plugin_pane_id: u32, new_name: S)
}

Required Permission: ChangeApplicationState

Rename a plugin pane (changes the title displayed in the UI).

Parameters:

ParameterTypeDescription
plugin_pane_idu32Plugin pane ID
new_nameimpl AsRef<str>New name

rename_pane_with_id

#![allow(unused)]
fn main() {
fn rename_pane_with_id<S: AsRef<str>>(pane_id: PaneId, new_name: S)
}

Required Permission: ChangeApplicationState

Rename any pane by its PaneId. Convenience wrapper around rename_terminal_pane and rename_plugin_pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to rename
new_nameimpl AsRef<str>New name

undo_rename_pane

#![allow(unused)]
fn main() {
fn undo_rename_pane()
}

Required Permission: ChangeApplicationState

Undo the last pane rename, reverting to the previous name.


toggle_focus_fullscreen

#![allow(unused)]
fn main() {
fn toggle_focus_fullscreen()
}

Required Permission: ChangeApplicationState

Toggle the focused pane to be fullscreen or normal sized.


toggle_focus_no_ui_fullscreen

#![allow(unused)]
fn main() {
fn toggle_focus_no_ui_fullscreen()
}

Required Permission: ChangeApplicationState

Toggle the focused pane to be fullscreen or normal sized, with the fullscreen pane covering the entire display - including the space normally occupied by the UI bars (eg. the tab-bar and status-bar). Unlike toggle_focus_fullscreen, which keeps them visible.


toggle_pane_id_fullscreen

#![allow(unused)]
fn main() {
fn toggle_pane_id_fullscreen(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Toggle a specific pane to be fullscreen or normal sized.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to toggle

toggle_pane_frames

#![allow(unused)]
fn main() {
fn toggle_pane_frames()
}

Required Permission: ChangeApplicationState

Toggle the UI pane frames on or off globally.


set_pane_frame_style

#![allow(unused)]
fn main() {
fn set_pane_frame_style(pane_frame_style: PaneFrameStyle)
}

Required Permission: ChangeApplicationState

Set the style of the pane frames for the whole session (see the pane_frame_style option).

Parameters:

ParameterTypeDescription
pane_frame_stylePaneFrameStyleFull, Titles or None

Example:

#![allow(unused)]
fn main() {
set_pane_frame_style(PaneFrameStyle::Titles);
}

toggle_bars

#![allow(unused)]
fn main() {
fn toggle_bars(bar_names: Vec<String>)
}

Required Permission: ChangeApplicationState

If any bars are hidden, show all bars. Otherwise hide the named bars, or all bars if bar_names is empty.

Parameters:

ParameterTypeDescription
bar_namesVec<String>Bars to hide: tab-bar, status-bar, compact-bar, a plugin alias or location, or all

hide_bars

#![allow(unused)]
fn main() {
fn hide_bars(bar_names: Vec<String>)
}

Required Permission: ChangeApplicationState

Hide the named bars in every tab, or all bars if bar_names is empty. The space of a hidden bar goes to the panes around it. The bars that are currently hidden are reported in the hidden_bars field of ModeInfo.

Parameters:

ParameterTypeDescription
bar_namesVec<String>Bars to hide: tab-bar, status-bar, compact-bar, a plugin alias or location, or all

Example:

#![allow(unused)]
fn main() {
hide_bars(vec!["status-bar".to_owned()]);
}

show_bars

#![allow(unused)]
fn main() {
fn show_bars()
}

Required Permission: ChangeApplicationState

Show all hidden bars.


toggle_pane_embed_or_eject

#![allow(unused)]
fn main() {
fn toggle_pane_embed_or_eject()
}

Required Permission: ChangeApplicationState

Toggle the focused pane between floating and tiled (embedded) mode.


toggle_pane_embed_or_eject_for_pane_id

#![allow(unused)]
fn main() {
fn toggle_pane_embed_or_eject_for_pane_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Toggle a specific pane between floating and tiled (embedded) mode. This is the same as calling toggle_pane_embed_or_eject_for_pane_id_with_focus with show_and_focus set to false.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to toggle

toggle_pane_embed_or_eject_for_pane_id_with_focus

#![allow(unused)]
fn main() {
fn toggle_pane_embed_or_eject_for_pane_id_with_focus(pane_id: PaneId, show_and_focus: bool)
}

Required Permission: ChangeApplicationState

Toggle a specific pane between floating and tiled (embedded) mode. With show_and_focus set to true, the pane is also shown and focused for the user who triggered the plugin, the same way as when the user moves the focused pane between layers.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to toggle
show_and_focusboolWhether to show and focus the pane after moving it

set_pane_border_style

#![allow(unused)]
fn main() {
fn set_pane_border_style(pane_id: PaneId, border_style: BorderStyleOverride)
}

Required Permission: ChangeApplicationState

Set the line style of a pane's border, side by side. This replaces any override set before for the same pane. Sides left as None use the configured border style, so an empty override returns the pane to the configured style.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to change
border_styleBorderStyleOverrideThe line styles to use

Example:

#![allow(unused)]
fn main() {
set_pane_border_style(
    PaneId::Terminal(1),
    BorderStyleOverride {
        all: Some(LineStyle::Double),
        ..Default::default()
    },
);
}

toggle_pane_borderless

#![allow(unused)]
fn main() {
fn toggle_pane_borderless(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Toggle the borderless state for a pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to toggle

set_pane_borderless

#![allow(unused)]
fn main() {
fn set_pane_borderless(pane_id: PaneId, borderless: bool)
}

Required Permission: ChangeApplicationState

Explicitly set the borderless state for a pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to modify
borderlessbooltrue for borderless, false for bordered

move_pane

#![allow(unused)]
fn main() {
fn move_pane()
}

Required Permission: ChangeApplicationState

Switch the position of the focused pane with another pane.


move_pane_with_direction

#![allow(unused)]
fn main() {
fn move_pane_with_direction(direction: Direction)
}

Required Permission: ChangeApplicationState

Switch the position of the focused pane with the pane in the specified direction.

Parameters:

ParameterTypeDescription
directionDirectionLeft, Right, Up, or Down

move_pane_with_pane_id

#![allow(unused)]
fn main() {
fn move_pane_with_pane_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Switch the position of the specified pane with another pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to move

move_pane_with_pane_id_in_direction

#![allow(unused)]
fn main() {
fn move_pane_with_pane_id_in_direction(pane_id: PaneId, direction: Direction)
}

Required Permission: ChangeApplicationState

Move a specific pane in the specified direction.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to move
directionDirectionDirection to move

replace_pane_with_existing_pane

#![allow(unused)]
fn main() {
fn replace_pane_with_existing_pane(
    pane_id_to_replace: PaneId,
    existing_pane_id: PaneId,
    suppress_replaced_pane: bool,
)
}

Required Permission: ChangeApplicationState

Replace one pane with another existing pane.

Parameters:

ParameterTypeDescription
pane_id_to_replacePaneIdPane to be replaced
existing_pane_idPaneIdPane to place in the replaced position
suppress_replaced_paneboolIf true, suppress (hide) the replaced pane instead of closing it

set_floating_pane_pinned

#![allow(unused)]
fn main() {
fn set_floating_pane_pinned(pane_id: PaneId, should_be_pinned: bool)
}

Required Permission: ChangeApplicationState

Pin or unpin a floating pane. Pinned floating panes remain visible when toggling floating pane visibility.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe floating pane
should_be_pinnedbooltrue to pin, false to unpin

stack_panes

#![allow(unused)]
fn main() {
fn stack_panes(pane_ids: Vec<PaneId>)
}

Required Permission: ChangeApplicationState

Stack multiple panes together into a pane stack.

Parameters:

ParameterTypeDescription
pane_idsVec<PaneId>Panes to stack

change_floating_panes_coordinates

#![allow(unused)]
fn main() {
fn change_floating_panes_coordinates(
    pane_ids_and_coordinates: Vec<(PaneId, FloatingPaneCoordinates)>,
)
}

Required Permission: ChangeApplicationState

Change the position and size of floating panes.

Parameters:

ParameterTypeDescription
pane_ids_and_coordinatesVec<(PaneId, FloatingPaneCoordinates)>Pairs of pane IDs and their new coordinates

float_multiple_panes

#![allow(unused)]
fn main() {
fn float_multiple_panes(pane_ids: Vec<PaneId>)
}

Required Permission: ChangeApplicationState

Convert multiple tiled panes to floating panes.

Parameters:

ParameterTypeDescription
pane_idsVec<PaneId>Panes to float

embed_multiple_panes

#![allow(unused)]
fn main() {
fn embed_multiple_panes(pane_ids: Vec<PaneId>)
}

Required Permission: ChangeApplicationState

Convert multiple floating panes to tiled (embedded) panes.

Parameters:

ParameterTypeDescription
pane_idsVec<PaneId>Panes to embed

group_and_ungroup_panes

#![allow(unused)]
fn main() {
fn group_and_ungroup_panes(
    pane_ids_to_group: Vec<PaneId>,
    pane_ids_to_ungroup: Vec<PaneId>,
    for_all_clients: bool,
)
}

Required Permission: ChangeApplicationState

Group and/or ungroup panes for bulk selection actions.

Parameters:

ParameterTypeDescription
pane_ids_to_groupVec<PaneId>Panes to add to a group
pane_ids_to_ungroupVec<PaneId>Panes to remove from a group
for_all_clientsboolApply to all clients, not just the current one

highlight_and_unhighlight_panes

#![allow(unused)]
fn main() {
fn highlight_and_unhighlight_panes(
    pane_ids_to_highlight: Vec<PaneId>,
    pane_ids_to_unhighlight: Vec<PaneId>,
)
}

Required Permission: ChangeApplicationState

Highlight or unhighlight panes in the UI.

Parameters:

ParameterTypeDescription
pane_ids_to_highlightVec<PaneId>Panes to highlight
pane_ids_to_unhighlightVec<PaneId>Panes to unhighlight

set_pane_color

#![allow(unused)]
fn main() {
fn set_pane_color(pane_id: PaneId, fg: Option<String>, bg: Option<String>)
}

Required Permission: ChangeApplicationState

Set the default foreground and/or background color of a pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to modify
fgOption<String>Foreground color (e.g., "#00e000")
bgOption<String>Background color (e.g., "#001a3a")

Pane Resize & Scroll


resize_focused_pane

#![allow(unused)]
fn main() {
fn resize_focused_pane(resize: Resize)
}

Required Permission: ChangeApplicationState

Increase or decrease the size of the focused pane.

Parameters:

ParameterTypeDescription
resizeResizeIncrease or Decrease

resize_focused_pane_with_direction

#![allow(unused)]
fn main() {
fn resize_focused_pane_with_direction(resize: Resize, direction: Direction)
}

Required Permission: ChangeApplicationState

Resize the focused pane in a specific direction.

Parameters:

ParameterTypeDescription
resizeResizeIncrease or Decrease
directionDirectionDirection to resize towards

resize_pane_with_id

#![allow(unused)]
fn main() {
fn resize_pane_with_id(resize_strategy: ResizeStrategy, pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Resize a specific pane using a full resize strategy.

Parameters:

ParameterTypeDescription
resize_strategyResizeStrategyResize parameters
pane_idPaneIdThe pane to resize

scroll_up

#![allow(unused)]
fn main() {
fn scroll_up()
}

Required Permission: ChangeApplicationState

Scroll the focused pane up 1 line.


scroll_down

#![allow(unused)]
fn main() {
fn scroll_down()
}

Required Permission: ChangeApplicationState

Scroll the focused pane down 1 line.


scroll_to_top

#![allow(unused)]
fn main() {
fn scroll_to_top()
}

Required Permission: ChangeApplicationState

Scroll the focused pane to the top of the scroll buffer.


scroll_to_bottom

#![allow(unused)]
fn main() {
fn scroll_to_bottom()
}

Required Permission: ChangeApplicationState

Scroll the focused pane to the bottom of the scroll buffer.


page_scroll_up

#![allow(unused)]
fn main() {
fn page_scroll_up()
}

Required Permission: ChangeApplicationState

Scroll the focused pane up one page.


page_scroll_down

#![allow(unused)]
fn main() {
fn page_scroll_down()
}

Required Permission: ChangeApplicationState

Scroll the focused pane down one page.


scroll_up_in_pane_id

#![allow(unused)]
fn main() {
fn scroll_up_in_pane_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Scroll a specific pane up 1 line.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to scroll

scroll_down_in_pane_id

#![allow(unused)]
fn main() {
fn scroll_down_in_pane_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Scroll a specific pane down 1 line.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to scroll

scroll_to_top_in_pane_id

#![allow(unused)]
fn main() {
fn scroll_to_top_in_pane_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Scroll a specific pane to the top of the scroll buffer.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to scroll

scroll_to_bottom_in_pane_id

#![allow(unused)]
fn main() {
fn scroll_to_bottom_in_pane_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Scroll a specific pane to the bottom of the scroll buffer.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to scroll

page_scroll_up_in_pane_id

#![allow(unused)]
fn main() {
fn page_scroll_up_in_pane_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Scroll a specific pane up one page.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to scroll

page_scroll_down_in_pane_id

#![allow(unused)]
fn main() {
fn page_scroll_down_in_pane_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Scroll a specific pane down one page.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to scroll

edit_scrollback

#![allow(unused)]
fn main() {
fn edit_scrollback()
}

Required Permission: ChangeApplicationState

Open the scroll buffer of the focused pane in the user's default $EDITOR.


edit_scrollback_for_pane_with_id

#![allow(unused)]
fn main() {
fn edit_scrollback_for_pane_with_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Open the scroll buffer of a specific pane in the user's default $EDITOR. Currently only works for terminal panes.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane whose scrollback to edit

clear_screen

#![allow(unused)]
fn main() {
fn clear_screen()
}

Required Permission: ChangeApplicationState

Clear the scroll buffer of the focused pane.


clear_screen_for_pane_id

#![allow(unused)]
fn main() {
fn clear_screen_for_pane_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Clear the scroll buffer of a specific pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to clear

Writing to Panes & Signals


write

#![allow(unused)]
fn main() {
fn write(bytes: Vec<u8>)
}

Required Permission: WriteToStdin

Write raw bytes to the STDIN of the focused pane.

Parameters:

ParameterTypeDescription
bytesVec<u8>Raw bytes to write

write_chars

#![allow(unused)]
fn main() {
fn write_chars(chars: &str)
}

Required Permission: WriteToStdin

Write characters to the STDIN of the focused pane.

Parameters:

ParameterTypeDescription
chars&strCharacters to write

Example:

#![allow(unused)]
fn main() {
write_chars("ls -la\n");
}

write_to_pane_id

#![allow(unused)]
fn main() {
fn write_to_pane_id(bytes: Vec<u8>, pane_id: PaneId)
}

Required Permission: WriteToStdin

Write raw bytes to the STDIN of a specific pane.

Parameters:

ParameterTypeDescription
bytesVec<u8>Raw bytes to write
pane_idPaneIdTarget pane

write_chars_to_pane_id

#![allow(unused)]
fn main() {
fn write_chars_to_pane_id(chars: &str, pane_id: PaneId)
}

Required Permission: WriteToStdin

Write characters to the STDIN of a specific pane.

Parameters:

ParameterTypeDescription
chars&strCharacters to write
pane_idPaneIdTarget pane

copy_to_clipboard

#![allow(unused)]
fn main() {
fn copy_to_clipboard(text: impl Into<String>)
}

Required Permission: WriteToClipboard

Copy arbitrary text to the user's clipboard. Respects the user's configured clipboard destination (system clipboard or primary selection).

Parameters:

ParameterTypeDescription
textimpl Into<String>Text to copy

send_sigint_to_pane_id

#![allow(unused)]
fn main() {
fn send_sigint_to_pane_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Send SIGINT to the process running inside a terminal pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdTarget terminal pane

send_sigkill_to_pane_id

#![allow(unused)]
fn main() {
fn send_sigkill_to_pane_id(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Send SIGKILL to the process running inside a terminal pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdTarget terminal pane

Input Mode & Key Management


switch_to_input_mode

#![allow(unused)]
fn main() {
fn switch_to_input_mode(mode: &InputMode)
}

Required Permission: ChangeApplicationState

Switch to the specified input mode (e.g., Normal, Tab, Pane).

Parameters:

ParameterTypeDescription
mode&InputModeThe input mode to switch to

Example:

#![allow(unused)]
fn main() {
switch_to_input_mode(&InputMode::Normal);
}

rebind_keys

#![allow(unused)]
fn main() {
fn rebind_keys(
    keys_to_unbind: Vec<(InputMode, KeyWithModifier)>,
    keys_to_rebind: Vec<(InputMode, KeyWithModifier, Vec<Action>)>,
    write_config_to_disk: bool,
)
}

Required Permission: Reconfigure

Rebind and/or unbind keys for the current session.

Parameters:

ParameterTypeDescription
keys_to_unbindVec<(InputMode, KeyWithModifier)>Keys to remove bindings for
keys_to_rebindVec<(InputMode, KeyWithModifier, Vec<Action>)>Keys to bind to new actions
write_config_to_diskboolIf true, persist changes to the config file

intercept_key_presses

#![allow(unused)]
fn main() {
fn intercept_key_presses()
}

Required Permission: InterceptInput

Start intercepting key presses. Intercepted keys are delivered via the InterceptedKeyPress event rather than being processed by Zellij.


clear_key_presses_intercepts

#![allow(unused)]
fn main() {
fn clear_key_presses_intercepts()
}

Required Permission: InterceptInput

Stop intercepting key presses, returning to normal key handling.


Layout Management


dump_layout

#![allow(unused)]
fn main() {
fn dump_layout(layout_name: &str) -> Result<String, String>
}

Required Permission: ReadApplicationState

Get a layout's KDL content by name. Supports both built-in layouts (e.g., "default", "compact", "welcome") and custom layouts from the layout directory.

Parameters:

ParameterTypeDescription
layout_name&strName of the layout

Returns: Result<String, String> - the KDL layout string on success


dump_session_layout

#![allow(unused)]
fn main() {
fn dump_session_layout() -> Result<(String, Option<LayoutMetadata>), String>
}

Required Permission: ReadApplicationState

Get the current session layout as a KDL string, along with optional metadata. The requesting plugin is removed from the dumped layout.

Returns: Result<(String, Option<LayoutMetadata>), String>


dump_session_layout_for_tab

#![allow(unused)]
fn main() {
fn dump_session_layout_for_tab(
    tab_index: usize,
) -> Result<(String, Option<LayoutMetadata>), String>
}

Required Permission: ReadApplicationState

Get the layout for a specific tab as a KDL string.

Parameters:

ParameterTypeDescription
tab_indexusizeTab position index

Returns: Result<(String, Option<LayoutMetadata>), String>


parse_layout

#![allow(unused)]
fn main() {
fn parse_layout(layout_string: &str) -> Result<LayoutMetadata, LayoutParsingError>
}

Required Permission: ReadApplicationState

Parse a KDL layout string and return its metadata without applying it.

Parameters:

ParameterTypeDescription
layout_string&strKDL layout string to parse

Returns: Result<LayoutMetadata, LayoutParsingError>


save_layout

#![allow(unused)]
fn main() {
fn save_layout<S: AsRef<str>>(
    layout_name: S,
    layout_kdl: S,
    overwrite: bool,
) -> Result<(), String>
}

Required Permission: ChangeApplicationState

Save a KDL layout to the user's layout directory.

Parameters:

ParameterTypeDescription
layout_nameimpl AsRef<str>Name for the layout file
layout_kdlimpl AsRef<str>KDL layout content
overwriteboolIf true, overwrite existing file; if false, fail if file exists

Returns: Result<(), String> - Ok(()) on success


delete_layout

#![allow(unused)]
fn main() {
fn delete_layout<S: AsRef<str>>(layout_name: S) -> Result<(), String>
}

Required Permission: ChangeApplicationState

Delete a layout file from the user's layout directory.

Parameters:

ParameterTypeDescription
layout_nameimpl AsRef<str>Name of the layout to delete

Returns: Result<(), String> - Ok(()) on success


rename_layout

#![allow(unused)]
fn main() {
fn rename_layout(
    old_layout_name: impl Into<String>,
    new_layout_name: impl Into<String>,
) -> Result<(), String>
}

Required Permission: ChangeApplicationState

Rename a layout file in the user's layout directory.

Parameters:

ParameterTypeDescription
old_layout_nameimpl Into<String>Current layout name
new_layout_nameimpl Into<String>New layout name

Returns: Result<(), String> - Ok(()) on success


edit_layout

#![allow(unused)]
fn main() {
fn edit_layout<S: AsRef<str>>(
    layout_name: S,
    context: BTreeMap<String, String>,
) -> Result<(), String>
}

Required Permission: ChangeApplicationState

Open a layout file in the user's default $EDITOR.

Parameters:

ParameterTypeDescription
layout_nameimpl AsRef<str>Name of the layout to edit
contextBTreeMap<String, String>Arbitrary context for event callbacks

Returns: Result<(), String> - Ok(()) on success


override_layout

#![allow(unused)]
fn main() {
fn override_layout<L: AsRef<LayoutInfo>>(
    layout_info: L,
    retain_existing_terminal_panes: bool,
    retain_existing_plugin_panes: bool,
    apply_only_to_active_tab: bool,
    context: BTreeMap<String, String>,
)
}

Required Permission: ChangeApplicationState

Override the current layout with a new one.

Parameters:

ParameterTypeDescription
layout_infoimpl AsRef<LayoutInfo>New layout to apply
retain_existing_terminal_panesboolKeep existing terminal panes
retain_existing_plugin_panesboolKeep existing plugin panes
apply_only_to_active_tabboolOnly apply to the active tab
contextBTreeMap<String, String>Arbitrary context

previous_swap_layout

#![allow(unused)]
fn main() {
fn previous_swap_layout()
}

Required Permission: ChangeApplicationState

Switch to the previous swap layout.


next_swap_layout

#![allow(unused)]
fn main() {
fn next_swap_layout()
}

Required Permission: ChangeApplicationState

Switch to the next swap layout.


apply_tiled_swap_layout

#![allow(unused)]
fn main() {
fn apply_tiled_swap_layout(layout_name: &str)
}

Required Permission: ChangeApplicationState

Apply the tiled swap layout with this name to the current tab. Floating pane visibility and focus do not change. A name that does not exist, or a layout that does not fit the current panes, does nothing.

Parameters:

ParameterTypeDescription
layout_name&strName of the tiled swap layout

apply_floating_swap_layout

#![allow(unused)]
fn main() {
fn apply_floating_swap_layout(layout_name: &str)
}

Required Permission: ChangeApplicationState

Apply the floating swap layout with this name to the current tab. Floating pane visibility and focus do not change. A name that does not exist, or a layout that does not fit the current panes, does nothing.

Parameters:

ParameterTypeDescription
layout_name&strName of the floating swap layout

Background Command Execution & Web Requests


run_command

#![allow(unused)]
fn main() {
fn run_command(cmd: &[&str], context: BTreeMap<String, String>)
}

Required Permission: RunCommands

Run a command in the background on the host machine. Results are delivered via the RunCommandResult event if subscribed.

Parameters:

ParameterTypeDescription
cmd&[&str]Command and arguments (first element is the command)
contextBTreeMap<String, String>Arbitrary context returned with the result event

Example:

#![allow(unused)]
fn main() {
subscribe(&[EventType::RunCommandResult]);
let mut context = BTreeMap::new();
context.insert("request_id".to_string(), "git-status".to_string());
run_command(&["git", "status", "--porcelain"], context);
}

run_command_with_env_variables_and_cwd

#![allow(unused)]
fn main() {
fn run_command_with_env_variables_and_cwd(
    cmd: &[&str],
    env_variables: BTreeMap<String, String>,
    cwd: PathBuf,
    context: BTreeMap<String, String>,
)
}

Required Permission: RunCommands

Run a command in the background with specific environment variables and working directory.

Parameters:

ParameterTypeDescription
cmd&[&str]Command and arguments
env_variablesBTreeMap<String, String>Environment variables for the command
cwdPathBufWorking directory
contextBTreeMap<String, String>Arbitrary context returned with the result event

web_request

#![allow(unused)]
fn main() {
fn web_request<S: AsRef<str>>(
    url: S,
    verb: HttpVerb,
    headers: BTreeMap<String, String>,
    body: Vec<u8>,
    context: BTreeMap<String, String>,
)
}

Required Permission: WebAccess

Make an HTTP request. Results are delivered via the WebRequestResult event if subscribed.

Parameters:

ParameterTypeDescription
urlimpl AsRef<str>Request URL
verbHttpVerbHTTP method (Get, Post, Put, Delete)
headersBTreeMap<String, String>Request headers
bodyVec<u8>Request body
contextBTreeMap<String, String>Arbitrary context returned with the result event

Example:

#![allow(unused)]
fn main() {
subscribe(&[EventType::WebRequestResult]);
let mut headers = BTreeMap::new();
headers.insert("Accept".to_string(), "application/json".to_string());
let mut context = BTreeMap::new();
context.insert("request_id".to_string(), "api-call".to_string());
web_request(
    "https://api.example.com/data",
    HttpVerb::Get,
    headers,
    vec![],
    context,
);
}

set_timeout

#![allow(unused)]
fn main() {
fn set_timeout(secs: f64)
}

Set a timer. After the specified duration, the plugin's update method will be called with the Timer event. The plugin must subscribe to EventType::Timer beforehand.

Parameters:

ParameterTypeDescription
secsf64Duration in seconds (supports fractions, e.g., 0.5)

Example:

#![allow(unused)]
fn main() {
subscribe(&[EventType::Timer]);
set_timeout(2.0);
}

Plugin Communication


post_message_to

#![allow(unused)]
fn main() {
fn post_message_to(plugin_message: PluginMessage)
}

Post a message to one of this plugin's workers. See Workers for Async Tasks for details.

Parameters:

ParameterTypeDescription
plugin_messagePluginMessageMessage with worker name, message name, and payload

Example:

#![allow(unused)]
fn main() {
post_message_to(PluginMessage {
    name: "fetch_data".to_string(),
    payload: "https://example.com".to_string(),
    worker_name: Some("background_worker".to_string()),
});
}

post_message_to_plugin

#![allow(unused)]
fn main() {
fn post_message_to_plugin(plugin_message: PluginMessage)
}

Post a message back to this plugin's update method as a CustomMessage event. Typically used by workers to send results back to the main plugin.

Parameters:

ParameterTypeDescription
plugin_messagePluginMessageMessage with name and payload

pipe_message_to_plugin

#![allow(unused)]
fn main() {
fn pipe_message_to_plugin(message_to_plugin: MessageToPlugin)
}

Required Permission: MessageAndLaunchOtherPlugins

Send a message to another plugin. If the target plugin is not running, it will be launched.

Parameters:

ParameterTypeDescription
message_to_pluginMessageToPluginMessage specification including target plugin URL/ID, message content, and launch configuration

Example:

#![allow(unused)]
fn main() {
pipe_message_to_plugin(MessageToPlugin {
    plugin_url: Some("file:/path/to/other-plugin.wasm".to_string()),
    destination_plugin_id: None,
    plugin_config: BTreeMap::new(),
    message_name: "process_data".to_string(),
    message_payload: Some("payload content".to_string()),
    message_args: BTreeMap::new(),
    new_plugin_args: None,
    floating_pane_coordinates: None,
});
}

report_panic

#![allow(unused)]
fn main() {
fn report_panic(info: &std::panic::PanicHookInfo)
}

Report a panic to Zellij for error display. Typically used inside a custom panic hook.

Parameters:

ParameterTypeDescription
info&std::panic::PanicHookInfoThe panic information

Example:

#![allow(unused)]
fn main() {
std::panic::set_hook(Box::new(|info| {
    report_panic(info);
}));
}

CLI Pipe Management

For more details, see Pipes for communicating with and between plugins.


unblock_cli_pipe_input

#![allow(unused)]
fn main() {
fn unblock_cli_pipe_input(pipe_name: &str)
}

Required Permission: ReadCliPipes

Unblock the input side of a pipe, requesting the next message to be sent if one is available.

Parameters:

ParameterTypeDescription
pipe_name&strName of the pipe

block_cli_pipe_input

#![allow(unused)]
fn main() {
fn block_cli_pipe_input(pipe_name: &str)
}

Required Permission: ReadCliPipes

Block the input side of a pipe. The pipe will remain blocked until explicitly unblocked by this or another plugin.

Parameters:

ParameterTypeDescription
pipe_name&strName of the pipe

cli_pipe_output

#![allow(unused)]
fn main() {
fn cli_pipe_output(pipe_name: &str, output: &str)
}

Required Permission: ReadCliPipes

Send output to the output side of a pipe. This does not affect the input side of the same pipe.

Parameters:

ParameterTypeDescription
pipe_name&strName of the pipe
output&strOutput content

set_cli_pipe_exit_code

#![allow(unused)]
fn main() {
fn set_cli_pipe_exit_code(pipe_name: &str, exit_code: i32)
}

Required Permission: ReadCliPipes

Set the exit code that the waiting zellij pipe command exits with once the pipe is released. This lets a plugin report success or failure to the shell script that piped to it.

Parameters:

ParameterTypeDescription
pipe_name&strName (CLI pipe id) of the pipe
exit_codei32Exit code for the zellij pipe process

Example:

#![allow(unused)]
fn main() {
fn pipe(&mut self, pipe_message: PipeMessage) -> bool {
    if let PipeSource::Cli(pipe_id) = &pipe_message.source {
        if pipe_message.payload.is_none() {
            set_cli_pipe_exit_code(pipe_id, 1);
            unblock_cli_pipe_input(pipe_id);
        }
    }
    false
}
}

Popups & Prompts

A popup is a plugin pane drawn above everything else in the tab, for one user, and closed when it is no longer needed (eg. with close_self). See also the zellij prompt command, which uses the same popups from the command line.


open_plugin_popup

#![allow(unused)]
fn main() {
fn open_plugin_popup(
    plugin_url: impl Into<String>,
    configuration: BTreeMap<String, String>,
    line: usize,
    column: usize,
    width: usize,
    height: usize,
)
}

Required Permission: ChangeApplicationState

Open a plugin as a popup for the user who triggered this plugin. The popup's top left corner is placed at line and column, relative to this plugin's content area, and is moved as needed to fit on the screen. This is the same as open_plugin_popup_with_options with PopupOptions::default(): the popup takes key focus, closes other open menus, and closes when the user clicks outside of it.

Parameters:

ParameterTypeDescription
plugin_urlimpl Into<String>URL or alias of the plugin to open
configurationBTreeMap<String, String>Configuration for the popup plugin
lineusizeLine (relative to this plugin) for the popup's top edge
columnusizeColumn (relative to this plugin) for the popup's left edge
widthusizeWidth in columns
heightusizeHeight in rows

Example:

#![allow(unused)]
fn main() {
open_plugin_popup(
    "file:/path/to/menu.wasm",
    BTreeMap::new(),
    1,
    self.menu_button_column,
    30,
    10,
);
}

open_plugin_popup_with_options

#![allow(unused)]
fn main() {
fn open_plugin_popup_with_options(
    plugin_url: impl Into<String>,
    configuration: BTreeMap<String, String>,
    line: usize,
    column: usize,
    width: usize,
    height: usize,
    options: PopupOptions,
)
}

Required Permission: ChangeApplicationState

Same as open_plugin_popup, with control over how the popup behaves:

  • focused: true (default) opens a menu-like popup: it takes key focus, replaces other open menus of the same user, and by default closes on a click outside of it.
  • focused: false opens an information popup: it does not take key focus, and by default ignores clicks outside of it.
  • corner places the popup in a corner of the screen instead of at line and column.
  • capture_all_keys sends every key to the popup, including the ones bound to Zellij actions.
  • outside_click chooses what a click outside the popup does: Block (ignore it) or Close.

A popup that is waiting for the user to answer a permission request takes focus until the request is answered, and an outside click cannot close it.

Parameters:

ParameterTypeDescription
plugin_urlimpl Into<String>URL or alias of the plugin to open
configurationBTreeMap<String, String>Configuration for the popup plugin
lineusizeLine (relative to this plugin) for the popup's top edge
columnusizeColumn (relative to this plugin) for the popup's left edge
widthusizeWidth in columns
heightusizeHeight in rows
optionsPopupOptionsHow the popup behaves

Example:

#![allow(unused)]
fn main() {
open_plugin_popup_with_options(
    "file:/path/to/notice.wasm",
    BTreeMap::new(),
    0,
    0,
    40,
    3,
    PopupOptions::default()
        .focused(false)
        .corner(PopupCorner::TopRight),
);
}

set_popup_size

#![allow(unused)]
fn main() {
fn set_popup_size(width: usize, height: usize)
}

Required Permission: ChangeApplicationState

Resize the popup this plugin is running in, eg. once it knows how much content it has.

Parameters:

ParameterTypeDescription
widthusizeNew width in columns
heightusizeNew height in rows

set_popup_focused

#![allow(unused)]
fn main() {
fn set_popup_focused(focused: bool)
}

Required Permission: ChangeApplicationState

Give key focus to the popup this plugin is running in, or take it away.

Parameters:

ParameterTypeDescription
focusedbooltrue to take key focus, false to give it back to the pane below

#![allow(unused)]
fn main() {
fn popup_to_floating_pane(coordinates: Option<FloatingPaneCoordinates>)
}

Required Permission: ChangeApplicationState

Turn the popup this plugin is running in into a regular floating pane, which stays open until it is closed like any other pane.

Parameters:

ParameterTypeDescription
coordinatesOption<FloatingPaneCoordinates>Position and size of the floating pane, or None for the default

prompt

#![allow(unused)]
fn main() {
fn prompt(request: PromptRequest) -> u64
}

Required Permission: OpenTerminalsOrPlugins

Ask the user something through the built-in prompt popup (zellij:prompt, see the prompt alias), and return the id of the request. By default the popup opens over this plugin's pane, for the user who triggered the plugin.

The answer arrives later as a PromptResult event carrying the same id. It is sent only to this plugin instance, which needs to subscribe to EventType::PromptResult. An invalid request (eg. a number prompt whose minimum is above its maximum) is answered at once with PromptResult::Error and opens no popup. If this plugin closes or reloads before the user answers, its open prompts close and no result is sent.

Parameters:

ParameterTypeDescription
requestPromptRequestWhat to ask and how to show it

Returns: u64 - the id of this request, repeated in its PromptResult event

Example:

#![allow(unused)]
fn main() {
fn load(&mut self, _configuration: BTreeMap<String, String>) {
    request_permission(&[PermissionType::OpenTerminalsOrPlugins]);
    subscribe(&[EventType::PromptResult]);
}

fn ask_before_closing(&mut self) {
    let request_id = prompt(PromptRequest::confirm("Close all panes?").yes("Close").no("Keep"));
    self.pending_close = Some(request_id);
}

fn update(&mut self, event: Event) -> bool {
    match event {
        Event::PromptResult(request_id, PromptResult::Confirmed(true))
            if Some(request_id) == self.pending_close =>
        {
            self.close_all_panes();
            true
        },
        _ => false,
    }
}
}

reply_to_prompt

#![allow(unused)]
fn main() {
fn reply_to_prompt(request_id: u64, result: PromptResult)
}

Required Permission: OpenTerminalsOrPlugins

Answer a prompt request received through a pipe message whose source is PipeSource::PromptRequest. Only the built-in zellij:prompt plugin may use this command; calls from any other plugin are ignored.

Parameters:

ParameterTypeDescription
request_idu64The request_id of the PipeSource::PromptRequest
resultPromptResultThe answer

Context Menu

See the context menu for the user-facing side of this feature.


open_context_menu

#![allow(unused)]
fn main() {
fn open_context_menu(target: ContextMenuTarget, line: usize, column: usize)
}

Required Permission: ChangeApplicationState

Open Zellij's own right-click menu for a tab or for this bar, at line and column relative to this plugin's content area. This is how bar plugins (eg. a tab bar) offer the same menu Zellij shows when the user right-clicks a tab.

Parameters:

ParameterTypeDescription
targetContextMenuTargetTab(tab_position) or Bar
lineusizeLine (relative to this plugin) to open the menu at
columnusizeColumn (relative to this plugin) to open the menu at

Example:

#![allow(unused)]
fn main() {
fn update(&mut self, event: Event) -> bool {
    if let Event::Mouse(Mouse::RightClick(line, column)) = event {
        if let Some(tab_position) = self.tab_at_column(column) {
            open_context_menu(ContextMenuTarget::Tab(tab_position), line as usize, column);
        }
    }
    false
}
}

run_context_menu_item

#![allow(unused)]
fn main() {
fn run_context_menu_item(index: usize)
}

Required Permission: RunActionsAsUser

Run the actions of entry index of the context menu that is currently open for the user. Only the plugin showing that menu as a popup (by default the built-in context-menu plugin) may do this; it receives the entries through the ContextMenu event.

Parameters:

ParameterTypeDescription
indexusizeIndex of the entry in the list received with the ContextMenu event

Settings Screen Entry

A plugin can add an entry to the plugins page of the settings screen, so that users can open the plugin's own settings from there.


register_settings_entry

#![allow(unused)]
fn main() {
fn register_settings_entry(title: &str)
}

Required Permission: ChangeApplicationState

List this plugin in the settings screen under title. Each plugin instance has at most one entry: calling this again changes the title. Instances of the same plugin (same location and configuration) with the same title are listed once. Titles are cut to 80 characters, and an empty title is ignored. The entry is removed when the plugin unloads, crashes or is reloaded.

When the user selects the entry, this plugin receives a pipe message named OPEN_PLUGIN_SETTINGS_MESSAGE ("zellij:open_plugin_settings"), with the id of the client that selected it in the OPEN_PLUGIN_SETTINGS_CLIENT_ID_ARG ("client_id") argument. The plugin then decides how to show its settings (eg. with show_self or a popup).

The list of all registered entries is available through the PluginSettingsEntries event.

Parameters:

ParameterTypeDescription
title&strThe title shown in the settings screen

Example:

#![allow(unused)]
fn main() {
fn load(&mut self, _configuration: BTreeMap<String, String>) {
    request_permission(&[PermissionType::ChangeApplicationState]);
    subscribe(&[EventType::PermissionRequestResult]);
}

fn update(&mut self, event: Event) -> bool {
    if let Event::PermissionRequestResult(PermissionStatus::Granted) = event {
        register_settings_entry("My Plugin");
    }
    false
}

fn pipe(&mut self, pipe_message: PipeMessage) -> bool {
    if pipe_message.name == OPEN_PLUGIN_SETTINGS_MESSAGE {
        self.showing_settings = true;
        show_self(true);
        return true;
    }
    false
}
}

unregister_settings_entry

#![allow(unused)]
fn main() {
fn unregister_settings_entry()
}

Required Permission: ChangeApplicationState

Remove this plugin's entry from the settings screen.


Shared Plugin Slots

These commands are meant for shared plugins, where one plugin instance serves many panes ("slots"). They are the slot forms of set_selectable, hide_self, show_self, close_self and set_self_collapsed.

A shared plugin may only use the "self" commands inside render and slot_added, where Zellij knows which slot is meant. Everywhere else it must use these slot commands.

All of them return Err with a message when the slot does not belong to the calling plugin. A plugin that is not shared may use them with its own plugin id. None of them require a permission.


set_selectable_slot

#![allow(unused)]
fn main() {
fn set_selectable_slot(slot_id: SlotId, selectable: bool) -> Result<(), String>
}

Set whether the pane of this slot can be selected by the user.

ParameterTypeDescription
slot_idSlotIdThe slot
selectablebooltrue to make selectable

hide_slot

#![allow(unused)]
fn main() {
fn hide_slot(slot_id: SlotId) -> Result<(), String>
}

Hide (suppress) the pane of this slot. As with hide_self, the plugin keeps receiving events.


show_slot

#![allow(unused)]
fn main() {
fn show_slot(slot_id: SlotId, should_float_if_hidden: bool) -> Result<(), String>
}

Show the pane of this slot (unsuppress it if hidden) and focus it.

ParameterTypeDescription
slot_idSlotIdThe slot
should_float_if_hiddenboolIf true, show it as a floating pane when unsuppressing

close_slot

#![allow(unused)]
fn main() {
fn close_slot(slot_id: SlotId) -> Result<(), String>
}

Close the pane of this slot and remove the slot from the plugin. The plugin's slot_removed method is called for it.


set_collapsed_slot

#![allow(unused)]
fn main() {
fn set_collapsed_slot(slot_id: SlotId, collapsed: bool) -> Result<(), String>
}

The slot form of set_self_collapsed, for a shared plugin that decides outside of render.

ParameterTypeDescription
slot_idSlotIdThe slot
collapsedbooltrue to give the space back, false to take it again

Nested Sessions

See nested sessions. A plugin in the host session can follow the input mode of a nested (guest) session through the NestedSessionModeUpdate event, and fetch its keybindings with the command below, for example to show the right hints while the user is typing into the guest.


get_nested_session_keybinds

#![allow(unused)]
fn main() {
fn get_nested_session_keybinds(pane_id: PaneId) -> NestedSessionKeybindsResponse
}

Required Permission: ReadApplicationState

Ask the nested Zellij session running in pane_id for its input mode and keybindings. The call waits for the answer for up to one second.

Fetch them again when a NestedSessionModeUpdate event arrives with a keybinds_generation different from the one of the last answer.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane the nested session runs in

Returns: NestedSessionKeybindsResponse - Ok(NestedSessionKeybinds), or an error explaining why the keybindings are not available (eg. NotANestedSession or Timeout)

Example:

#![allow(unused)]
fn main() {
fn update(&mut self, event: Event) -> bool {
    if let Event::NestedSessionModeUpdate { pane_id, keybinds_generation, .. } = event {
        if self.keybinds_generation != Some(keybinds_generation) {
            if let Ok(guest) = get_nested_session_keybinds(pane_id) {
                self.keybinds_generation = Some(guest.keybinds_generation);
                self.guest_keybinds = guest.keybinds;
                return true;
            }
        }
    }
    false
}
}

Other Sessions & Attention

These commands work with panes in any running session on the machine, by session name. They are the building blocks of the inbox. Attention state itself arrives through the PaneAttentionChanged and GlobalAttentionUpdate events.


mark_session_pane_seen

#![allow(unused)]
fn main() {
fn mark_session_pane_seen(session_name: &str, pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Mark the attention state of a pane as seen.

ParameterTypeDescription
session_name&strSession the pane is in
pane_idPaneIdThe pane

mark_all_seen

#![allow(unused)]
fn main() {
fn mark_all_seen(session_name: Option<&str>)
}

Required Permission: ChangeApplicationState

Mark the attention state of every pane in a session as seen, or in every session if None.


toggle_session_pane_mute

#![allow(unused)]
fn main() {
fn toggle_session_pane_mute(session_name: &str, pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Mute or unmute the attention status of a pane.


toggle_session_pane_ignore_output

#![allow(unused)]
fn main() {
fn toggle_session_pane_ignore_output(session_name: &str, pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Stop or start reporting new output of a pane.


toggle_session_pane_watch

#![allow(unused)]
fn main() {
fn toggle_session_pane_watch(session_name: &str, pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Start or stop watching a pane. A watched pane notifies each time its command finishes or its output goes quiet, until it is no longer watched.


focus_session_pane

#![allow(unused)]
fn main() {
fn focus_session_pane(session_name: &str, pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Focus a pane in a session.


write_to_session_pane

#![allow(unused)]
fn main() {
fn write_to_session_pane(session_name: &str, pane_id: PaneId, bytes: Vec<u8>)
}

Required Permission: WriteToStdin

Write bytes to the STDIN of a pane in a session, as if the user typed them.

ParameterTypeDescription
session_name&strSession the pane is in
pane_idPaneIdThe pane
bytesVec<u8>Bytes to write

send_key_to_session_pane

#![allow(unused)]
fn main() {
fn send_key_to_session_pane(session_name: &str, pane_id: PaneId, key: KeyWithModifier)
}

Required Permission: WriteToStdin

Send a key press to a pane in a session, encoded the way the program in the pane expects.

ParameterTypeDescription
session_name&strSession the pane is in
pane_idPaneIdThe pane
keyKeyWithModifierThe key to send

get_session_suggestions

#![allow(unused)]
fn main() {
fn get_session_suggestions(limit: usize)
}

Required Permission: ReadApplicationState

Ask for a ranked list of up to limit sessions (running and resurrectable) that the user is likely to want, based on the current folder, git repository and recent use. See session suggestions. The answer arrives as a SessionSuggestions event.


get_session_preview

#![allow(unused)]
fn main() {
fn get_session_preview(name: &str, tab_index: Option<usize>, pane_id: Option<(u32, bool)>)
}

Required Permission: ReadApplicationState (the answer needs ReadPaneContents)

Ask for a text preview of a running session, optionally of a specific tab or pane ((id, is_plugin)). The answer arrives as a SessionPreview event.


get_session_preview_with_history

#![allow(unused)]
fn main() {
fn get_session_preview_with_history(name: &str, tab_index: Option<usize>, pane_id: Option<(u32, bool)>)
}

Required Permission: ReadApplicationState (the answer needs ReadPaneContents)

Same as get_session_preview, with the preview anchored at the bottom of the pane's scrollback (PreviewAnchor::Bottom).


get_session_pane_preview

#![allow(unused)]
fn main() {
fn get_session_pane_preview(name: &str, pane_id: PaneId, anchor: PreviewAnchor)
}

Required Permission: ReadApplicationState (the answer needs ReadPaneContents)

Ask for a preview of one pane, anchored where it is most useful: the bottom, the output of the last command, or the start of new output. See PreviewAnchor. The answer arrives as a SessionPreview event.


get_saved_session_preview

#![allow(unused)]
fn main() {
fn get_saved_session_preview(name: &str)
}

Required Permission: ReadApplicationState

Ask for a preview of a saved (resurrectable) session: its folder, tabs and panes. The answer arrives as a SavedSessionPreview event.


open_session_terminal

#![allow(unused)]
fn main() {
fn open_session_terminal(session_name: &str, new_window: bool)
}

Required Permission: ChangeApplicationState

Open a session in a window of the Zellij terminal desktop app. With new_window set to false, a window already showing this session is reused. Nothing happens if the desktop app is not available.


open_session_pane_terminal

#![allow(unused)]
fn main() {
fn open_session_pane_terminal(session_name: &str, pane_id: PaneId, new_window: bool)
}

Required Permission: ChangeApplicationState

Same as open_session_terminal, focusing a specific pane.


open_new_session_terminal

#![allow(unused)]
fn main() {
fn open_new_session_terminal(session_name: Option<&str>, layout: Option<LayoutInfo>, cwd: Option<PathBuf>)
}

Required Permission: ChangeApplicationState

Create a new session in a new window of the Zellij terminal desktop app, optionally with a name, a layout and a working directory. Without a cwd, the plugin's working directory is used.


request_session_terminal

#![allow(unused)]
fn main() {
fn request_session_terminal(request: SessionTerminalRequest)
}

Required Permission: ChangeApplicationState

The general form of the three commands above. See SessionTerminalRequest.


request_desktop_integration

#![allow(unused)]
fn main() {
fn request_desktop_integration(request: &desktop_integration::Request)
}

Required Permission: ChangeApplicationState

Change how Zellij integrates with the desktop (eg. installing the desktop app). Only built-in plugins may make these requests: for any other plugin the answer is always an error. The answer arrives as a DesktopIntegration event.


Pane Mirror (Live View)

A plugin can show a live copy of another pane - in this session or another session on the machine - inside part of its own pane, and optionally let the user type into it.


set_live_view

#![allow(unused)]
fn main() {
fn set_live_view(view: Option<LiveView>)
}

Required Permissions: ReadPaneContents and WriteToStdin

Show a live view of the pane described by view, in the rectangle x, y, cols, rows of this plugin's content area (it is cut to fit the content area). Each user looking at the plugin has their own live view. Calling it again with a different rectangle moves or resizes the view, and with a different target switches to that pane. None removes the view.

Changes to the state of the view (connecting, live, closed, input captured or released) are reported with the LiveViewStateChanged event.

Parameters:

ParameterTypeDescription
viewOption<LiveView>What to show and where, or None to remove the view

Example:

#![allow(unused)]
fn main() {
fn render(&mut self, rows: usize, cols: usize) {
    if let Some(pane_id) = self.selected_pane {
        let target = PaneAddress::local(self.session_name.clone(), pane_id);
        set_live_view(Some(LiveView::new(target, 0, 1, cols, rows.saturating_sub(1))));
    } else {
        set_live_view(None);
    }
    println!("{}", self.header);
}
}

set_live_view_input

#![allow(unused)]
fn main() {
fn set_live_view_input(capture: bool)
}

Required Permissions: ReadPaneContents and WriteToStdin

With true, send the user's input to the mirrored pane instead of to this plugin. This is refused if the plugin pane is not focused or the view is view-only. Input is released again by the release key (the live_view_release_key option, reported in LiveViewStateChanged), by a click outside the view, when the plugin loses focus, or by calling this with false.


Plugin Lifecycle


start_or_reload_plugin

#![allow(unused)]
fn main() {
fn start_or_reload_plugin(url: &str)
}

Required Permission: OpenTerminalsOrPlugins

Start a plugin by URL, or reload it if already running.

Parameters:

ParameterTypeDescription
url&strPlugin URL (e.g., "file:/path/to/plugin.wasm")

reload_plugin_with_id

#![allow(unused)]
fn main() {
fn reload_plugin_with_id(plugin_id: u32)
}

Required Permission: OpenTerminalsOrPlugins

Reload a running plugin by its ID.

Parameters:

ParameterTypeDescription
plugin_idu32Plugin ID to reload

load_new_plugin

#![allow(unused)]
fn main() {
fn load_new_plugin<S: AsRef<str>>(
    url: S,
    config: BTreeMap<String, String>,
    load_in_background: bool,
    skip_plugin_cache: bool,
)
}

Required Permission: OpenTerminalsOrPlugins

Load a new plugin instance.

Parameters:

ParameterTypeDescription
urlimpl AsRef<str>Plugin URL
configBTreeMap<String, String>Plugin configuration
load_in_backgroundboolIf true, load suppressed (hidden)
skip_plugin_cacheboolIf true, force a fresh load

Configuration & Host


reconfigure

#![allow(unused)]
fn main() {
fn reconfigure(new_config: String, save_configuration_file: bool)
}

Required Permission: Reconfigure

Change the Zellij runtime configuration for the current session. The configuration is provided as a KDL string.

Parameters:

ParameterTypeDescription
new_configStringKDL configuration string
save_configuration_fileboolIf true, persist the configuration change to disk

Example:

#![allow(unused)]
fn main() {
reconfigure(r#"
    theme "catppuccin-mocha"
    pane_frames false
"#.to_string(), false);
}

change_host_folder

#![allow(unused)]
fn main() {
fn change_host_folder(new_host_folder: PathBuf)
}

Required Permission: ChangeApplicationState

Change the host folder (working directory) for the session.

Parameters:

ParameterTypeDescription
new_host_folderPathBufNew working directory path

scan_host_folder

#![allow(unused)]
fn main() {
fn scan_host_folder<S: AsRef<Path>>(folder_to_scan: &S)
}

Scan a specific folder in the host filesystem. This is a performance optimization to work around WASI runtime limitations. Does not follow symlinks.

Parameters:

ParameterTypeDescription
folder_to_scanimpl AsRef<Path>Folder path to scan

watch_filesystem

#![allow(unused)]
fn main() {
fn watch_filesystem()
}

Start watching the host folder for filesystem changes. File change events (FileSystemCreate, FileSystemUpdate, FileSystemDelete) will be delivered to the plugin.


Editing the Configuration

These commands are what the built-in settings screen uses to read and change the configuration of the user who triggered the plugin. Changes are made to the running configuration first (and marked as unsaved), and are written to the configuration file only when asked to. All of them require the Reconfigure permission.

Related events: ConfigChangesDropped, ConfigFileChangedSinceRead, ConfigWasWrittenToDisk, FailedToWriteConfigToDisk and AvailableKeybindPresets.


read_config

#![allow(unused)]
fn main() {
fn read_config() -> ConfigSnapshot
}

Required Permission: Reconfigure

Return a snapshot of the configuration: the saved and current value of each setting, the configuration blocks, the keybindings and mouse bindings and where each comes from, and the path of the configuration file.

Returns: ConfigSnapshot


revert_config

#![allow(unused)]
fn main() {
fn revert_config(key: Option<SettingKey>)
}

Required Permission: Reconfigure

Undo unsaved changes: set one setting (or all of them, with None) back to its saved value.

ParameterTypeDescription
keyOption<SettingKey>The setting to revert, or None for all settings

unset_config_setting

#![allow(unused)]
fn main() {
fn unset_config_setting(key: SettingKey)
}

Required Permission: Reconfigure

Remove a setting from the running configuration, so that its default applies. Like other changes, this is unsaved until save_config is called.

ParameterTypeDescription
keySettingKeyThe setting to remove

save_config

#![allow(unused)]
fn main() {
fn save_config()
}

Required Permission: Reconfigure

Write the unsaved changes to the configuration file, keeping its formatting and comments. If the file was changed by something else since Zellij read it, nothing is written and a ConfigFileChangedSinceRead event is sent instead, so the plugin can offer overwrite_config_file or reload_config_file.


overwrite_config_file

#![allow(unused)]
fn main() {
fn overwrite_config_file()
}

Required Permission: Reconfigure

Same as save_config, but write even if the file was changed since Zellij read it.


reload_config_file

#![allow(unused)]
fn main() {
fn reload_config_file()
}

Required Permission: Reconfigure

Read the configuration file again and apply it.


replace_config_blocks

#![allow(unused)]
fn main() {
fn replace_config_blocks(blocks: String)
}

Required Permission: Reconfigure

Replace configuration blocks (eg. plugins, load_plugins, env, themes or context_menu) in the running configuration with the ones in blocks, given as KDL text. The change is not written to disk.

ParameterTypeDescription
blocksStringOne or more configuration blocks, as KDL

reset_keys

#![allow(unused)]
fn main() {
fn reset_keys(keys: Vec<(InputMode, KeyWithModifier)>, write_config_to_disk: bool)
}

Required Permission: Reconfigure

Remove the user's own binding (or unbinding) of these keys, so that they go back to what the active keybinding preset binds them to.

ParameterTypeDescription
keysVec<(InputMode, KeyWithModifier)>The keys to reset, per mode
write_config_to_diskboolWhether to also save the change to the configuration file

reset_mousebinds

#![allow(unused)]
fn main() {
fn reset_mousebinds(triggers: Vec<(InputMode, MouseTrigger)>, write_config_to_disk: bool)
}

Required Permission: Reconfigure

The mouse binding form of reset_keys.

ParameterTypeDescription
triggersVec<(InputMode, MouseTrigger)>The mouse bindings to reset, per mode
write_config_to_diskboolWhether to also save the change to the configuration file

copy_keybind_preset

#![allow(unused)]
fn main() {
fn copy_keybind_preset(preset: &str, new_name: &str) -> Result<String, String>
}

Required Permission: Reconfigure

Copy a keybinding preset into the keybinds folder under a new name, so that the user can edit it.

Returns: Ok with the name of the new preset, or Err with a message (eg. when there is no keybinds folder)


save_keybinds_as_preset

#![allow(unused)]
fn main() {
fn save_keybinds_as_preset(new_name: &str) -> Result<String, String>
}

Required Permission: Reconfigure

Save the current keybindings as a new preset in the keybinds folder.

Returns: Ok with the name of the new preset, or Err with a message


write_theme_file

#![allow(unused)]
fn main() {
fn write_theme_file(name: &str, copy_from: Option<&str>, colours: &[String]) -> Result<String, String>
}

Required Permission: Reconfigure

With copy_from, create a new theme file named name in the theme folder as a copy of the theme copy_from (this fails if a theme called name already exists). Without it, write colours into the file in the theme folder that defines the theme name. The theme becomes available right away.

Returns: Ok with the path of the theme file, or Err with a message (eg. when there is no theme folder)


delete_theme_file

#![allow(unused)]
fn main() {
fn delete_theme_file(name: &str) -> Result<String, String>
}

Required Permission: Reconfigure

Delete the theme file of the theme name from the theme folder.

Returns: Ok with the path of the deleted file, or Err with a message


Web Server & Sharing


start_web_server

#![allow(unused)]
fn main() {
fn start_web_server()
}

Required Permission: StartWebServer

Start a local web server for serving Zellij sessions to web clients.


stop_web_server

#![allow(unused)]
fn main() {
fn stop_web_server()
}

Required Permission: StartWebServer

Stop the local web server.


query_web_server_status

#![allow(unused)]
fn main() {
fn query_web_server_status()
}

Required Permission: StartWebServer

Query the current status of the web server. Results are delivered via the WebServerStatus event.


share_current_session

#![allow(unused)]
fn main() {
fn share_current_session()
}

Required Permission: StartWebServer

Share the current session via the web server.


stop_sharing_current_session

#![allow(unused)]
fn main() {
fn stop_sharing_current_session()
}

Required Permission: StartWebServer

Stop sharing the current session.


generate_web_login_token

#![allow(unused)]
fn main() {
fn generate_web_login_token(
    token_label: Option<String>,
    read_only: bool,
) -> Result<String, String>
}

Required Permission: StartWebServer

Generate a web login token for authenticating web clients.

Parameters:

ParameterTypeDescription
token_labelOption<String>Optional label for the token
read_onlyboolIf true, the token grants read-only access

Returns: Result<String, String> - the generated token string


revoke_web_login_token

#![allow(unused)]
fn main() {
fn revoke_web_login_token(token_label: &str) -> Result<(), String>
}

Required Permission: StartWebServer

Revoke a web login token by its label.

Parameters:

ParameterTypeDescription
token_label&strLabel of the token to revoke

Returns: Result<(), String> - Ok(()) on success


list_web_login_tokens

#![allow(unused)]
fn main() {
fn list_web_login_tokens() -> Result<Vec<(String, String, bool)>, String>
}

Required Permission: StartWebServer

List all web login tokens.

Returns: Result<Vec<(String, String, bool)>, String> - list of (label, created_at, read_only) tuples


revoke_all_web_tokens

#![allow(unused)]
fn main() {
fn revoke_all_web_tokens() -> Result<(), String>
}

Required Permission: StartWebServer

Revoke all web login tokens.

Returns: Result<(), String> - Ok(()) on success


rename_web_token

#![allow(unused)]
fn main() {
fn rename_web_token(old_name: &str, new_name: &str) -> Result<(), String>
}

Required Permission: StartWebServer

Rename a web login token.

Parameters:

ParameterTypeDescription
old_name&strCurrent token label
new_name&strNew token label

Returns: Result<(), String> - Ok(()) on success


Regex Highlights


set_pane_regex_highlights

#![allow(unused)]
fn main() {
fn set_pane_regex_highlights(pane_id: PaneId, highlights: Vec<RegexHighlight>)
}

Required Permission: ChangeApplicationState

Set or update regex-based content highlights for a pane. Highlights are matched against the pane's terminal output and rendered with the specified styles. When the user clicks on a highlight, a HighlightClicked event is delivered.

Capture group support: If the regex pattern contains a capture group, only group 1 is used for the visual highlight extent and the matched_string returned in the HighlightClicked event. This allows patterns to require surrounding context (e.g., whitespace) without including it in the highlight. For example, the pattern (?:^|\s)(src/main\.rs)(?:\s|$) highlights only src/main.rs, not the adjacent spaces. Patterns without capture groups behave normally - the full match is used.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to apply highlights to
highlightsVec<RegexHighlight>Highlight specifications

Example:

#![allow(unused)]
fn main() {
set_pane_regex_highlights(PaneId::Terminal(1), vec![
    RegexHighlight {
        pattern: r"https?://\S+".to_string(),
        style: HighlightStyle::Emphasis0,
        layer: HighlightLayer::Hint,
        context: BTreeMap::new(),
        on_hover: false,
        bold: false,
        italic: false,
        underline: true,
        tooltip_text: Some("Click to open URL".to_string()),
    },
]);
}

clear_pane_highlights

#![allow(unused)]
fn main() {
fn clear_pane_highlights(pane_id: PaneId)
}

Required Permission: ChangeApplicationState

Remove all regex highlights that this plugin set on a pane.

Parameters:

ParameterTypeDescription
pane_idPaneIdThe pane to clear highlights from

Action Execution


run_action

#![allow(unused)]
fn main() {
fn run_action(action: Action, context: BTreeMap<String, String>)
}

Required Permission: RunActionsAsUser

Run an arbitrary Zellij Action programmatically. This provides access to the full set of Zellij actions, including those not exposed through dedicated plugin commands.

Parameters:

ParameterTypeDescription
actionActionThe action to execute
contextBTreeMap<String, String>Arbitrary context returned with the ActionComplete event

Example:

#![allow(unused)]
fn main() {
use zellij_tile::prelude::*;

run_action(Action::ToggleFloatingPanes, BTreeMap::new());

run_action(
    Action::SwitchToMode { input_mode: InputMode::Pane },
    BTreeMap::new(),
);
}

Utility Functions

These are local helper functions that do not communicate with the Zellij host. They operate on data already available to the plugin.


get_focused_tab

#![allow(unused)]
fn main() {
fn get_focused_tab(tab_infos: &Vec<TabInfo>) -> Option<TabInfo>
}

Extract the active (focused) tab from a list of tab information. This is a local helper that does not make a host call.

Parameters:

ParameterTypeDescription
tab_infos&Vec<TabInfo>List of tab information (from a TabUpdate event)

Returns: Option<TabInfo> - the focused tab, or None if none is focused

Example:

#![allow(unused)]
fn main() {
fn update(&mut self, event: Event) -> bool {
    match event {
        Event::TabUpdate(tabs) => {
            if let Some(focused) = get_focused_tab(&tabs) {
                eprintln!("Active tab: {}", focused.name);
            }
            true
        },
        _ => false,
    }
}
}

get_focused_pane

#![allow(unused)]
fn main() {
fn get_focused_pane(tab_position: usize, pane_manifest: &PaneManifest) -> Option<PaneInfo>
}

Extract the focused non-plugin pane from a pane manifest for a given tab. This is a local helper that does not make a host call.

Parameters:

ParameterTypeDescription
tab_positionusizeTab position (0-indexed)
pane_manifest&PaneManifestPane manifest (from a PaneUpdate event)

Returns: Option<PaneInfo> - the focused pane, or None


mouse_modifiers

#![allow(unused)]
fn main() {
fn mouse_modifiers() -> BTreeSet<KeyModifier>
}

Return the modifier keys (Shift, Ctrl, Alt) that were held during the Mouse event currently being handled. The set is empty for events without modifiers, and is reset with every new event, so read it inside update. This is a local helper that does not make a host call.

Returns: BTreeSet<KeyModifier> - the held modifiers

Example:

#![allow(unused)]
fn main() {
fn update(&mut self, event: Event) -> bool {
    match event {
        Event::Mouse(Mouse::LeftClick(line, column)) => {
            if mouse_modifiers().contains(&KeyModifier::Ctrl) {
                self.add_to_selection(line, column);
            } else {
                self.select_only(line, column);
            }
            true
        },
        _ => false,
    }
}
}