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
- Plugin Settings & Permissions
- Query / Information Retrieval
- Session Management
- File Opening (Editor Panes)
- Terminal Pane Opening
- Command Pane Opening
- New Tab Opening
- Tab Navigation & Management
- Pane Focus & Visibility
- Pane Manipulation
- Pane Resize & Scroll
- Writing to Panes & Signals
- Input Mode & Key Management
- Layout Management
- Background Command Execution & Web Requests
- Plugin Communication
- CLI Pipe Management
- Popups & Prompts
- Context Menu
- Settings Screen Entry
- Shared Plugin Slots
- Nested Sessions
- Other Sessions & Attention
- Pane Mirror (Live View)
- Plugin Lifecycle
- Configuration & Host
- Editing the Configuration
- Web Server & Sharing
- Regex Highlights
- Action Execution
- Utility Functions
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:
| Parameter | Type | Description |
|---|---|---|
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:
| Parameter | Type | Description |
|---|---|---|
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:
| Parameter | Type | Description |
|---|---|---|
selectable | bool | true 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:
| Parameter | Type | Description |
|---|---|---|
cursor_position | Option<(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:
| Parameter | Type | Description |
|---|---|---|
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:
| Parameter | Type | Description |
|---|---|---|
selection_support | bool | true 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:
| Parameter | Type | Description |
|---|---|---|
collapsed | bool | true 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:
| Parameter | Type | Description |
|---|---|---|
on | bool | true 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-dirflag - The directory specified in the config file
- The directory specified via
ZELLIJ_LAYOUT_DIRenvironment 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
tab_id | usize | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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 sessionsresurrectable_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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The pane to read |
get_full_scrollback | bool | If 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:
| Parameter | Type | Description |
|---|---|---|
name | Option<&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:
| Parameter | Type | Description |
|---|---|---|
name | Option<&str> | Session name, or None for a new session |
layout | LayoutInfo | Layout to apply |
cwd | Option<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:
| Parameter | Type | Description |
|---|---|---|
name | Option<&str> | Session name, or None for a new session |
cwd | Option<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:
| Parameter | Type | Description |
|---|---|---|
name | &str | Session name to switch to |
tab_position | Option<usize> | Tab position to focus |
pane_id | Option<(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:
| Parameter | Type | Description |
|---|---|---|
connect_to_session | ConnectToSession | Where 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:
| Parameter | Type | Description |
|---|---|---|
name | &str | Session name to switch to |
tab_position | Option<usize> | Tab position to focus |
pane_id | Option<(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:
| Parameter | Type | Description |
|---|---|---|
name | &str | New 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:
| Parameter | Type | Description |
|---|---|---|
name | &str | Name 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. withlet _ = ...) 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:
| Parameter | Type | Description |
|---|---|---|
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:
| Parameter | Type | Description |
|---|---|---|
file_to_open | FileToOpen | File path, optional line number, and optional cwd |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
file_to_open | FileToOpen | File path, optional line number, and optional cwd |
coordinates | Option<FloatingPaneCoordinates> | Optional position and size |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
file_to_open | FileToOpen | File to open |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
file_to_open | FileToOpen | File to open |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
file_to_open | FileToOpen | File to open |
coordinates | Option<FloatingPaneCoordinates> | Optional position and size |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
file_to_open | FileToOpen | File to open |
close_plugin_after_replace | bool | If true, close the plugin pane after replacement |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The pane to replace |
file_to_open | FileToOpen | File to open |
close_replaced_pane | bool | If true, close the replaced pane; if false, suppress it |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
path | impl 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:
| Parameter | Type | Description |
|---|---|---|
path | impl 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:
| Parameter | Type | Description |
|---|---|---|
path | impl AsRef<Path> | Working directory for the new terminal |
coordinates | Option<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:
| Parameter | Type | Description |
|---|---|---|
path | impl AsRef<Path> | Working directory for the new terminal |
coordinates | Option<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:
| Parameter | Type | Description |
|---|---|---|
path | impl 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:
| Parameter | Type | Description |
|---|---|---|
path | impl AsRef<Path> | Working directory for the new terminal |
close_plugin_after_replace | bool | If 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The pane to replace |
cwd | impl AsRef<Path> | Working directory for the new terminal |
close_replaced_pane | bool | If 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:
| Parameter | Type | Description |
|---|---|---|
command_to_run | CommandToRun | Command path, args, and optional cwd |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
command_to_run | CommandToRun | Command to execute |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
command_to_run | CommandToRun | Command to execute |
coordinates | Option<FloatingPaneCoordinates> | Optional position and size |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
command_to_run | CommandToRun | Command to execute |
coordinates | Option<FloatingPaneCoordinates> | Optional position and size |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
command_to_run | CommandToRun | Command to execute |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
command_to_run | CommandToRun | Command to execute |
close_plugin_after_replace | bool | If true, close the plugin; if false, suppress it |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The pane to replace |
command_to_run | CommandToRun | Command to execute |
close_replaced_pane | bool | If true, close the replaced pane; if false, suppress it |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
command_to_run | CommandToRun | Command to execute |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
terminal_pane_id | u32 | The 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:
| Parameter | Type | Description |
|---|---|---|
name | Option<impl AsRef<str>> | Optional name for the new tab |
cwd | Option<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:
| Parameter | Type | Description |
|---|---|---|
layout | &str | KDL 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:
| Parameter | Type | Description |
|---|---|---|
layout_info | impl 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 requireChangeApplicationState.
Parameters:
| Parameter | Type | Description |
|---|---|---|
command_to_run | CommandToRun | Command to execute |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
plugin_url | impl ToString | Plugin URL (e.g., "file:/path/to/plugin.wasm" or a named alias) |
configuration | BTreeMap<String, String> | Plugin configuration key-value pairs |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
plugin_url | &str | Plugin URL (e.g., "file:/path/to/plugin.wasm" or a named alias) |
configuration | BTreeMap<String, String> | Plugin configuration key-value pairs |
coordinates | Option<FloatingPaneCoordinates> | Optional position and size for the floating pane |
context | BTreeMap<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 requireChangeApplicationState.
Parameters:
| Parameter | Type | Description |
|---|---|---|
file_to_open | FileToOpen | File to open |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
name | Option<String> | Optional name for the new tab |
cwd | Option<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:
| Parameter | Type | Description |
|---|---|---|
tab_position | usize | The 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:
| Parameter | Type | Description |
|---|---|---|
tab_idx | u32 | Tab 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:
| Parameter | Type | Description |
|---|---|---|
tab_name | &str | Name 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:
| Parameter | Type | Description |
|---|---|---|
tab_name | &str | Name 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:
| Parameter | Type | Description |
|---|---|---|
tab_index | u32 | Tab 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:
| Parameter | Type | Description |
|---|---|---|
tab_index | usize | Tab 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:
| Parameter | Type | Description |
|---|---|---|
tab_id | u64 | Stable 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:
| Parameter | Type | Description |
|---|---|---|
tab_position | u32 | Tab position |
new_name | impl 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:
| Parameter | Type | Description |
|---|---|---|
tab_id | u64 | Stable tab identifier |
new_name | impl 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:
| Parameter | Type | Description |
|---|---|---|
pane_ids | &[PaneId] | Panes to move |
new_tab_name | Option<String> | Optional name for the new tab |
should_change_focus_to_new_tab | bool | Whether 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:
| Parameter | Type | Description |
|---|---|---|
pane_ids | &[PaneId] | Panes to move |
tab_index | usize | Target tab position index |
should_change_focus_to_new_tab | bool | Whether 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:
| Parameter | Type | Description |
|---|---|---|
pane_ids | &[PaneId] | Panes to move |
tab_id | usize | Target tab stable ID |
should_change_focus_to_target_tab | bool | Whether 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:
| Parameter | Type | Description |
|---|---|---|
should_float_if_hidden | bool | If 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The pane to show |
should_float_if_hidden | bool | If true, show as floating when unsuppressing |
should_focus_pane | bool | If 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:
| Parameter | Type | Description |
|---|---|---|
direction | Direction | Left, 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:
| Parameter | Type | Description |
|---|---|---|
direction | Direction | Left, 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:
| Parameter | Type | Description |
|---|---|---|
terminal_pane_id | u32 | Terminal pane ID |
should_float_if_hidden | bool | Show as floating when unsuppressing |
should_be_in_place_if_hidden | bool | Show 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:
| Parameter | Type | Description |
|---|---|---|
plugin_pane_id | u32 | Plugin pane ID |
should_float_if_hidden | bool | Show as floating when unsuppressing |
should_be_in_place_if_hidden | bool | Show 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The pane to focus |
should_float_if_hidden | bool | Show as floating when unsuppressing |
should_be_in_place_if_hidden | bool | Show 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:
| Parameter | Type | Description |
|---|---|---|
tab_id | Option<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:
| Parameter | Type | Description |
|---|---|---|
tab_id | Option<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:
| Parameter | Type | Description |
|---|---|---|
tab_id | Option<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:
| Parameter | Type | Description |
|---|---|---|
terminal_pane_id | u32 | Terminal 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:
| Parameter | Type | Description |
|---|---|---|
plugin_pane_id | u32 | Plugin 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_ids | Vec<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:
| Parameter | Type | Description |
|---|---|---|
terminal_pane_id | u32 | Terminal pane ID |
new_name | impl 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:
| Parameter | Type | Description |
|---|---|---|
plugin_pane_id | u32 | Plugin pane ID |
new_name | impl 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The pane to rename |
new_name | impl 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_frame_style | PaneFrameStyle | Full, 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:
| Parameter | Type | Description |
|---|---|---|
bar_names | Vec<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:
| Parameter | Type | Description |
|---|---|---|
bar_names | Vec<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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The pane to toggle |
show_and_focus | bool | Whether 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The pane to change |
border_style | BorderStyleOverride | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The pane to modify |
borderless | bool | true 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:
| Parameter | Type | Description |
|---|---|---|
direction | Direction | Left, 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
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:
| Parameter | Type | Description |
|---|---|---|
pane_id_to_replace | PaneId | Pane to be replaced |
existing_pane_id | PaneId | Pane to place in the replaced position |
suppress_replaced_pane | bool | If 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The floating pane |
should_be_pinned | bool | true 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:
| Parameter | Type | Description |
|---|---|---|
pane_ids | Vec<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:
| Parameter | Type | Description |
|---|---|---|
pane_ids_and_coordinates | Vec<(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:
| Parameter | Type | Description |
|---|---|---|
pane_ids | Vec<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:
| Parameter | Type | Description |
|---|---|---|
pane_ids | Vec<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:
| Parameter | Type | Description |
|---|---|---|
pane_ids_to_group | Vec<PaneId> | Panes to add to a group |
pane_ids_to_ungroup | Vec<PaneId> | Panes to remove from a group |
for_all_clients | bool | Apply 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:
| Parameter | Type | Description |
|---|---|---|
pane_ids_to_highlight | Vec<PaneId> | Panes to highlight |
pane_ids_to_unhighlight | Vec<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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The pane to modify |
fg | Option<String> | Foreground color (e.g., "#00e000") |
bg | Option<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:
| Parameter | Type | Description |
|---|---|---|
resize | Resize | Increase 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:
| Parameter | Type | Description |
|---|---|---|
resize | Resize | Increase or Decrease |
direction | Direction | Direction 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:
| Parameter | Type | Description |
|---|---|---|
resize_strategy | ResizeStrategy | Resize parameters |
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
bytes | Vec<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:
| Parameter | Type | Description |
|---|---|---|
chars | &str | Characters 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:
| Parameter | Type | Description |
|---|---|---|
bytes | Vec<u8> | Raw bytes to write |
pane_id | PaneId | Target 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:
| Parameter | Type | Description |
|---|---|---|
chars | &str | Characters to write |
pane_id | PaneId | Target 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:
| Parameter | Type | Description |
|---|---|---|
text | impl 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | Target 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | Target 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:
| Parameter | Type | Description |
|---|---|---|
mode | &InputMode | The 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:
| Parameter | Type | Description |
|---|---|---|
keys_to_unbind | Vec<(InputMode, KeyWithModifier)> | Keys to remove bindings for |
keys_to_rebind | Vec<(InputMode, KeyWithModifier, Vec<Action>)> | Keys to bind to new actions |
write_config_to_disk | bool | If 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:
| Parameter | Type | Description |
|---|---|---|
layout_name | &str | Name 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:
| Parameter | Type | Description |
|---|---|---|
tab_index | usize | Tab 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:
| Parameter | Type | Description |
|---|---|---|
layout_string | &str | KDL 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:
| Parameter | Type | Description |
|---|---|---|
layout_name | impl AsRef<str> | Name for the layout file |
layout_kdl | impl AsRef<str> | KDL layout content |
overwrite | bool | If 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:
| Parameter | Type | Description |
|---|---|---|
layout_name | impl 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:
| Parameter | Type | Description |
|---|---|---|
old_layout_name | impl Into<String> | Current layout name |
new_layout_name | impl 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:
| Parameter | Type | Description |
|---|---|---|
layout_name | impl AsRef<str> | Name of the layout to edit |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
layout_info | impl AsRef<LayoutInfo> | New layout to apply |
retain_existing_terminal_panes | bool | Keep existing terminal panes |
retain_existing_plugin_panes | bool | Keep existing plugin panes |
apply_only_to_active_tab | bool | Only apply to the active tab |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
layout_name | &str | Name 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:
| Parameter | Type | Description |
|---|---|---|
layout_name | &str | Name 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:
| Parameter | Type | Description |
|---|---|---|
cmd | &[&str] | Command and arguments (first element is the command) |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
cmd | &[&str] | Command and arguments |
env_variables | BTreeMap<String, String> | Environment variables for the command |
cwd | PathBuf | Working directory |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
url | impl AsRef<str> | Request URL |
verb | HttpVerb | HTTP method (Get, Post, Put, Delete) |
headers | BTreeMap<String, String> | Request headers |
body | Vec<u8> | Request body |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
secs | f64 | Duration 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:
| Parameter | Type | Description |
|---|---|---|
plugin_message | PluginMessage | Message 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:
| Parameter | Type | Description |
|---|---|---|
plugin_message | PluginMessage | Message 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:
| Parameter | Type | Description |
|---|---|---|
message_to_plugin | MessageToPlugin | Message 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:
| Parameter | Type | Description |
|---|---|---|
info | &std::panic::PanicHookInfo | The 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:
| Parameter | Type | Description |
|---|---|---|
pipe_name | &str | Name 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:
| Parameter | Type | Description |
|---|---|---|
pipe_name | &str | Name 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:
| Parameter | Type | Description |
|---|---|---|
pipe_name | &str | Name of the pipe |
output | &str | Output 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:
| Parameter | Type | Description |
|---|---|---|
pipe_name | &str | Name (CLI pipe id) of the pipe |
exit_code | i32 | Exit 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:
| Parameter | Type | Description |
|---|---|---|
plugin_url | impl Into<String> | URL or alias of the plugin to open |
configuration | BTreeMap<String, String> | Configuration for the popup plugin |
line | usize | Line (relative to this plugin) for the popup's top edge |
column | usize | Column (relative to this plugin) for the popup's left edge |
width | usize | Width in columns |
height | usize | Height 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: falseopens an information popup: it does not take key focus, and by default ignores clicks outside of it.cornerplaces the popup in a corner of the screen instead of atlineandcolumn.capture_all_keyssends every key to the popup, including the ones bound to Zellij actions.outside_clickchooses what a click outside the popup does:Block(ignore it) orClose.
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:
| Parameter | Type | Description |
|---|---|---|
plugin_url | impl Into<String> | URL or alias of the plugin to open |
configuration | BTreeMap<String, String> | Configuration for the popup plugin |
line | usize | Line (relative to this plugin) for the popup's top edge |
column | usize | Column (relative to this plugin) for the popup's left edge |
width | usize | Width in columns |
height | usize | Height in rows |
options | PopupOptions | How 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:
| Parameter | Type | Description |
|---|---|---|
width | usize | New width in columns |
height | usize | New 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:
| Parameter | Type | Description |
|---|---|---|
focused | bool | true to take key focus, false to give it back to the pane below |
popup_to_floating_pane
#![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:
| Parameter | Type | Description |
|---|---|---|
coordinates | Option<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:
| Parameter | Type | Description |
|---|---|---|
request | PromptRequest | What 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:
| Parameter | Type | Description |
|---|---|---|
request_id | u64 | The request_id of the PipeSource::PromptRequest |
result | PromptResult | The 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:
| Parameter | Type | Description |
|---|---|---|
target | ContextMenuTarget | Tab(tab_position) or Bar |
line | usize | Line (relative to this plugin) to open the menu at |
column | usize | Column (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:
| Parameter | Type | Description |
|---|---|---|
index | usize | Index 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:
| Parameter | Type | Description |
|---|---|---|
title | &str | The 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.
| Parameter | Type | Description |
|---|---|---|
slot_id | SlotId | The slot |
selectable | bool | true 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.
| Parameter | Type | Description |
|---|---|---|
slot_id | SlotId | The slot |
should_float_if_hidden | bool | If 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.
| Parameter | Type | Description |
|---|---|---|
slot_id | SlotId | The slot |
collapsed | bool | true 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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.
| Parameter | Type | Description |
|---|---|---|
session_name | &str | Session the pane is in |
pane_id | PaneId | The 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.
| Parameter | Type | Description |
|---|---|---|
session_name | &str | Session the pane is in |
pane_id | PaneId | The pane |
bytes | Vec<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.
| Parameter | Type | Description |
|---|---|---|
session_name | &str | Session the pane is in |
pane_id | PaneId | The pane |
key | KeyWithModifier | The 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:
| Parameter | Type | Description |
|---|---|---|
view | Option<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:
| Parameter | Type | Description |
|---|---|---|
url | &str | Plugin 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:
| Parameter | Type | Description |
|---|---|---|
plugin_id | u32 | Plugin 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:
| Parameter | Type | Description |
|---|---|---|
url | impl AsRef<str> | Plugin URL |
config | BTreeMap<String, String> | Plugin configuration |
load_in_background | bool | If true, load suppressed (hidden) |
skip_plugin_cache | bool | If 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:
| Parameter | Type | Description |
|---|---|---|
new_config | String | KDL configuration string |
save_configuration_file | bool | If 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:
| Parameter | Type | Description |
|---|---|---|
new_host_folder | PathBuf | New 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:
| Parameter | Type | Description |
|---|---|---|
folder_to_scan | impl 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.
| Parameter | Type | Description |
|---|---|---|
key | Option<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.
| Parameter | Type | Description |
|---|---|---|
key | SettingKey | The 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.
| Parameter | Type | Description |
|---|---|---|
blocks | String | One 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.
| Parameter | Type | Description |
|---|---|---|
keys | Vec<(InputMode, KeyWithModifier)> | The keys to reset, per mode |
write_config_to_disk | bool | Whether 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.
| Parameter | Type | Description |
|---|---|---|
triggers | Vec<(InputMode, MouseTrigger)> | The mouse bindings to reset, per mode |
write_config_to_disk | bool | Whether 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:
| Parameter | Type | Description |
|---|---|---|
token_label | Option<String> | Optional label for the token |
read_only | bool | If 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:
| Parameter | Type | Description |
|---|---|---|
token_label | &str | Label 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:
| Parameter | Type | Description |
|---|---|---|
old_name | &str | Current token label |
new_name | &str | New 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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The pane to apply highlights to |
highlights | Vec<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:
| Parameter | Type | Description |
|---|---|---|
pane_id | PaneId | The 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:
| Parameter | Type | Description |
|---|---|---|
action | Action | The action to execute |
context | BTreeMap<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:
| Parameter | Type | Description |
|---|---|---|
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:
| Parameter | Type | Description |
|---|---|---|
tab_position | usize | Tab position (0-indexed) |
pane_manifest | &PaneManifest | Pane 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, } } }