A Zellij plugin for creating, managing, and quickly inserting command bookmarks into the terminal.

• Easily create and manage command bookmarks: Create, edit, and organize bookmarks with ease to manage your most common terminal commands.

• Quickly filter, view, and insert commands into the terminal: Efficiently search and access commands or bookmarks by name or labels, allowing for fast navigation and command execution.

• Intuitive Navigation Modes: Switch between different navigation modes (Bookmarks or Labels) for better organization and streamlined command access.

• Advanced Templating & Dynamic Command Integration: Leverage reusable templates and dynamic interpolation with vars, cmd::<command_key>, and bookmark::<bookmark_name>. This allows you to define, customize, and reuse commands efficiently without repetitive configuration.

• Customizable Hotkeys: Define and adjust keybindings to better fit your workflow

• Navigation: Use Up and Down to navigate through the list of bookmarks or labels.
• Insert Bookmark: Press Enter to paste the selected bookmark into the terminal.
• Search: Start typing to filter the list based on the current mode.
• Remove Filter Symbol: Use Backspace to delete the last character from the filter input.
• Switch Modes: Press Ctrl Left or Ctrl Right to switch between plugin modes.
• Exit: Press Esc or Ctrl c to exit the plugin.
• Edit Bookmarks: Press Ctrl e to open the bookmark configuration file in an editor.
• Reload Bookmarks: Press Ctrl r to reload bookmarks after modifying the configuration file.
• Switch to Label Filtering Mode: Press Ctrl l to enable label filtering mode. This feature is only available in Bookmarks mode.
• Switch to ID Filtering Mode: Press Ctrl i to enable ID filtering mode. This feature is available in both Bookmarks and Labels modes.
• Bookmark Description: Press Ctrl d to display the description of the currently selected bookmark. This feature is only available in Bookmarks mode.
• Switch to Bookmarks Mode: Press Ctrl 1 to switch to Bookmarks mode.
• Switch to Labels Mode: Press Ctrl 2 to switch to Labels mode.
• View Usage Instructions: Press Ctrl 3 to switch to Usage mode and view plugin instructions.

For compatibility details, including tested versions, see COMPATIBILITY.md.

1. Install Rust and Cargo if you haven't already. Follow the installation guide here.

   Additionally, install the wasm32-wasip1 target by following the documentation here.

2. Clone the repository, build, and install the plugin by running the following commands:

   git clone https://github.com/yaroslavborbat/zellij-bookmarks.git
   cd zellij-bookmarks
   task build
   task install

For a quick installation, run the following command to download the plugin directly:

mkdir -p ~/.config/zellij/plugins && \
curl -L "https://github.com/yaroslavborbat/zellij-bookmarks/releases/latest/download/zellij-bookmarks.wasm" -o ~/.config/zellij/plugins/zellij-bookmarks.wasm

Note: You don't need to keep zellij-bookmarks.wasm at this specified location. It's just where I like to keep my zellij plugins.

Add the following configuration to your Zellij config inside the keybinds section:

shared_except "locked" {
    bind "Alt B" {
        LaunchOrFocusPlugin "file:~/.config/zellij/plugins/zellij-bookmarks.wasm" {
            floating true
            cwd "/home/<USER>/.config/zellij/"
        };
    }
}

Note: You likely already have a shared_except "locked" section in your configuration. Add the bind command there.

Note: Make sure to replace <USER> in the cwd path with your actual username.

Important: The cwd parameter is required. For details on why and what to do if it disappears after a Zellij update, see the FAQ.md.

• cwd: (REQUIRED) - The ABSOLUTE PATH where your bookmarks file will be stored.
• exec: (default: false) - If true, the command will execute immediately after pressing Enter. This can be overridden per bookmark.
• fuzzy_search: (default: true) - When filtering, uses fuzzy search to find bookmarks/labels that match the filter string.
• ignore_case: (default: false) - When filtering, ignores case sensitivity in both the filter string and bookmark/label names. Has no effect when fuzzy_search is enabled.
• autodetect_filter_mode: (default: true) - Automatically determines the filtering mode (ID or Name) based on the entered filter string, eliminating the need for manual mode switching.
• filename: (default: .zellij_bookmarks.yaml) - The name of the bookmarks file.
• bind_edit: (default: Ctrl e) Keybinding to open the bookmark configuration file in an editor.
• bind_reload: (default: Ctrl r) Keybinding to reload bookmarks.
• bind_switch_filter_label: (default: Ctrl l) Keybinding to switch to label filtering mode.
• bind_switch_filter_id: (default: Ctrl i) Keybinding to switch to id filtering mode.
• bind_describe: (default: Ctrl d) Keybinding to display the description of the selected bookmark.

The bookmarks configuration is a YAML file that defines your bookmarks. Here's a detailed explanation of the configuration structure and its usage.

A global key-value map for variables. These variables can be used to parameterize commands and bookmarks.

• Use the templating syntax {{ <variable_name> }} to reference a variable.

• If you need to include {{ ... }} as a literal string in your commands (e.g., for tools like crictl), you must escape it with double backslashes (\\).

  Example:

  cmds:
  - crictl inspect --output go-template --template '\\{{.info.pid}}' $CTR

A map for frequently used commands that aren't directly insertable into the terminal. You can include them in bookmarks by referencing them as cmd::<command_key>.

A list of bookmarks. Each bookmark has the following fields:

• name: A unique name for the bookmark. Can be used to link to a bookmark in other bookmarks.
• cmds: A list of commands for the bookmark. These can include:
  • Plain text commands.
  • Commands referenced from cmds using cmd::<command_key>.
  • Commands imported from other bookmarks using bookmark::<bookmark_name>.
• desc: (optional) A description of the bookmark to provide context or explanation about its purpose.
• exec: (optional) A boolean flag indicating whether the commands should be executed immediately.
• labels: (optional) A list of labels or tags associated with the bookmark.
• vars: (optional) Local variables specific to the bookmark. These have a higher priority than global vars.

Commands within a bookmark are concatenated using the separator &&.

• Templating with Variables: Variables defined in vars or bookmark-specific vars can be used in commands or bookmarks using the syntax {{ <variable_name> }}. Bookmark-specific variables take precedence over global ones, allowing flexible and context-specific command customization.

• Command Reuse with cmds:

  • Use cmd::<command_key> to reference predefined reusable commands from cmds.
  • Use bookmark::<bookmark_name> to include all commands from another bookmark into the current one.
  • Commands are concatenated with &&, ensuring sequential execution.

This structure provides a modular, reusable, and powerful way to parameterize commands and configurations using simple templating and bookmark composition.

vars:
  global_var: "Global value"
  path: "/home/user"

cmds:
  greet: "echo 'Hello, World!'"
  list_files: "ls -la {{ path }}"
  custom_echo: "echo '{{ message }}'"

bookmarks:
- name: "Bookmark1"
  desc: "A test bookmark combining plain text and reusable commands."
  cmds:
  - "echo 'This is Bookmark1'"
  - cmd::greet
  - bookmark::Bookmark2
  - cmd::custom_echo
  exec: false
  labels:
  - "utilities"
  - "example"
  vars:
    message: "Bye Bye!"

- name: "Bookmark2"
  desc: "Command to list files dynamically using the path variable."
  cmds:
  - "cmd::list_files"
  exec: true
  labels:
  - "files"

• global_var and path are global variables accessible in all commands and bookmarks.
• The {{ path }} variable is used in cmds to dynamically include the value of path.

• greet: A reusable command to print a greeting.
• list_files: A command to list files using the path variable.
• custom_echo: A customizable echo command using the message variable.

• Contains:
  • Plain text commands.
  • A reference to the reusable command cmd::greet.
  • Imports all commands from Bookmark2 using bookmark::Bookmark2.
• Includes local variables that can customize command behavior.
• Result command that would paste to terminal:

  echo 'This is Bookmark1' \
  && echo 'Hello, World!' \
  && ls -la /home/user \
  && echo 'Bye Bye!'

• Contains:
  • A command that uses the list_files command template (cmd::list_files).
• Is executed immediately because exec: true is set.
• Result command that would execute:

  ls -la /home/user

• zellij-bookmarks - A Zellij plugin for creating, managing, and quickly inserting command bookmarks into the terminal.
• zellij-playbooks - A Zellij plugin to browse, select, and execute commands from playbook files directly in the terminal.

Found an issue or have a feature request? Feel free to open an issue on GitHub.