Introduction

xplr is a terminal UI based file explorer that aims to increase our terminal productivity by being a flexible, interactive orchestrator for the ever growing awesome command-line utilities that work with the file-system.

To achieve its goal, xplr strives to be a fast, minimal and more importantly, hackable file explorer.

xplr is not meant to be a replacement for the standard shell commands or the GUI file managers. Rather, it aims to integrate them all and expose an intuitive, scriptable, keyboard controlled, real-time visual interface, also being an ideal candidate for further integration, enabling you to achieve insane terminal productivity.

Concept

Hackable

xplr is built with configurability in mind. So it allows you to perform a vast set of operations and make it look and behave just the way you want.

A few things you can do with the xplr configuration

• Hacks
• Plugins
• Integrations

Fast

Although speed is not the primary concern, xplr is already fast enough so that you can take it out for a walk into your node_modules or /nix/store any time you want, and it will only get faster. Still, if you feel like it's somehow making you slow, just report it. Most probably we're just waiting for someone to complain.

Tip: A quick and easy way to optimize the UI rendering is reducing the number of columns in the table.

Minimal

xplr is being referred to as a File Explorer, not a File Manager. This is because at the core, xplr is only an explorer, and outsources the file management operations to external commands. This helps xplr stay minimal, and focus only on doing what it does best.

So, just like speed, minimalism isn't as as aggressively pursued as hackability. xplr simply prefers to stay minimal and looks for the opportunity to lose some kb if it makes sense.

Features

Some of the coolest features xplr provide beside the basic stuff:

• Embedded LuaJIT for portability and extensibility.
• A simple modal system based on message passing to control xplr session using:
  • Keyboard inputs
  • Shell Commands
  • Lua Functions
  • Hooks
• Easy, typesafe message passing with -m MSG or -M MSG subcommands.
• Readline-like input buffer with customizable behavior to read user inputs.
• Switchable recover mode that saves you from doing unwanted things when in a hurry.
• Customizable layouts with built-in panels. For e.g.
  • Selection list to show you the selected paths in real-time.
  • Help menu to show you the available keys bindings in each mode.
  • Input & logs to read input and display logs.
  • Filter and sort pipeline to show you the applied filters and sorters.
• Custom file properties with custom colors can be displayed in the table.
• FIFO manager to manage a FIFO file that can be used to integrate with previewers.
• Virtual root with --vroot and :v key bindings.
• Different quit options:
  • Quit with success without any output (q).
  • Quit with success and the result printed on stdout (enter).
  • Quit with success and the present working directory printed on stdout (: q p).
  • Quit with success and the path under focus printed on stdout (: q f).
  • Quit with success and the selection printed on stdout (: q s).
  • Quit with failure (ctrl-c).

Quickstart

Nice to you have here! Let's quickly start with the following steps:

• Install
• Post Install

Try in Docker

If you prefer to try it before installing, here's the snippet for your convenience.

docker run -w / -it --rm ubuntu sh -uec '
  apt-get update -y
  apt-get install -y wget tar vim less
  wget https://github.com/sayanarijit/xplr/releases/latest/download/xplr-linux.tar.gz
  tar -xzvf xplr-linux.tar.gz
  ./xplr
'

Install

You can install xplr using one of the following ways. Each has their own advantages and limitations.

For example, the Direct Download, From crates.io, and Build From Source methods allow the users to install the latest possible version of xplr, but they have one common drawback - the user will need to keep an eye on the releases, and manually upgrade xplr when a new version is available.

One way to keep an eye on the releases is to watch the repository.

Community Maintained Repositories

xplr can be installed from one of the following community maintained repositories:

Cross-platform

Nixpkgs

nix-env -f https://github.com/NixOS/nixpkgs/tarball/master -iA xplr

Or

# configuration.nix or darwin-configuration.nix
environment.systemPackages = with nixpkgs; [
  xplr
  # ...
];

Home Manager

# home.nix
home.packages = with nixpkgs; [
  xplr
  # ...
];

Or

# home.nix
programs.xplr = {
  enable = true;

  # Optional params:
  plugins = {
    tree-view = fetchFromGitHub {
      owner = "sayanarijit";
      repo = "tree-view.xplr";
    };
    local-plugin = "/home/user/.config/xplr/plugins/local-plugin";
  };
  extraConfig = ''
    require("tree-view").setup()
    require("local-plugin").setup()
  '';
};

Arch Linux

(same for Manjaro Linux)

Official Community Repo

sudo pacman -S xplr

AUR

Git version:

paru -S xplr-git

Alpine Linux

Edge Testing Repo

# Add the following line in /etc/apk/repositories:
# https://dl-cdn.alpinelinux.org/alpine/edge/testing

apk add xplr bash less

Void Linux

void-templates by shubham

Gentoo

Overlay GURU

macOS

Make sure you have the latest version of GNU core utilities installed.

MacPorts

sudo port selfupdate
sudo port install xplr

Homebrew

Stable branch:

brew install xplr

HEAD branch:

brew install --head xplr

FreeBSD

ports

pkg install xplr

Or

cd /usr/ports/misc/xplr
make install clean

NetBSD

pkgsrc

pkgin install xplr

Or

cd /usr/pkgsrc/sysutils/xplr
make install

Direct Download

One can directly download the standalone binary from the releases.

Currently, the following options are available for direct download:

• GNU/Linux
• Linux musl
• macOS

Command-line instructions:

platform="linux"  # or "macos" / "linux-musl"

# Download
wget https://github.com/sayanarijit/xplr/releases/latest/download/xplr-$platform.tar.gz

# Extract
tar xzvf xplr-$platform.tar.gz

# Place in $PATH
sudo mv xplr /usr/local/bin/

From crates.io

Prerequisites:

• Rust toolchain,
• gcc
• make

Command-line instructions:

cargo install --locked --force xplr

Build From Source

Prerequisites:

• git
• Rust toolchain
• gcc
• make

Command-line instructions:

# Clone the repository
git clone https://github.com/sayanarijit/xplr.git
cd xplr

# Build
cargo build --locked --release --bin xplr

# Place in $PATH
sudo cp target/release/xplr /usr/local/bin/

Post Install

Once installed, use the following steps to setup and run xplr.

Create the customizable config file

mkdir -p ~/.config/xplr

version="$(xplr --version | awk '{print $2}')"

echo "version = '${version:?}'" > ~/.config/xplr/init.lua

Then copy from here and remove / comment out what you don't want to customize.

Run

xplr

Configuration

xplr can be configured using Lua via a special file named init.lua, which can be placed in ~/.config/xplr/ (local to user) or /etc/xplr/ (global) depending on the use case.

When xplr loads, it first executes the built-in init.lua to set the default values, which is then overwritten by another config file, if found using the following lookup order:

1. --config /path/to/init.lua
2. ~/.config/xplr/init.lua
3. /etc/xplr/init.lua

The first one found will be loaded by xplr and the lookup will stop.

The loaded config can be further extended using the -C or --extra-config command-line option.

Config

The xplr configuration, exposed via xplr.config Lua API contains the following sections.

See:

• xplr.config.general
• xplr.config.node_types
• xplr.config.layouts
• xplr.config.modes

Function

While xplr.config defines all the static parts of the configuration, xplr.fn defines all the dynamic parts using functions.

See: Lua Function Calls

As always, xplr.fn.builtin is where the built-in functions are defined that can be overwritten.

xplr.fn.builtin.try_complete_path

Tries to auto complete the path in the input buffer

xplr.fn.builtin.fmt_general_table_row_cols_0

Renders the first column in the table

xplr.fn.builtin.fmt_general_table_row_cols_1

Renders the second column in the table

xplr.fn.builtin.fmt_general_table_row_cols_2

Renders the third column in the table

xplr.fn.builtin.fmt_general_table_row_cols_3

Renders the fourth column in the table

xplr.fn.builtin.fmt_general_table_row_cols_4

Renders the fifth column in the table

xplr.fn.custom

This is where the custom functions can be added.

There is currently no restriction on what kind of functions can be defined in xplr.fn.custom.

You can also use nested tables such as xplr.fn.custom.my_plugin.my_function to define custom functions.

Hooks

This section of the configuration cannot be overwritten by another config file or plugin, since this is an optional lua return statement specific to each config file. It can be used to define things that should be explicit for reasons like performance concerns, such as hooks.

Plugins should expose the hooks, and require users to subscribe to them explicitly.

Example:

return {
  -- Add messages to send when the xplr loads.
  -- This is similar to the `--on-load` command-line option.
  --
  -- Type: list of [Message](https://xplr.dev/en/message#message)s
  on_load = {
    { LogSuccess = "Configuration successfully loaded!" },
    { CallLuaSilently = "custom.some_plugin_with_hooks.on_load" },
  },

  -- Add messages to send when the directory changes.
  --
  -- Type: list of [Message](https://xplr.dev/en/message#message)s
  on_directory_change = {
    { LogSuccess = "Changed directory" },
    { CallLuaSilently = "custom.some_plugin_with_hooks.on_directory_change" },
  },

  -- Add messages to send when the focus changes.
  --
  -- Type: list of [Message](https://xplr.dev/en/message#message)s
  on_focus_change = {
    { LogSuccess = "Changed focus" },
    { CallLuaSilently = "custom.some_plugin_with_hooks.on_focus_change" },
  }

  -- Add messages to send when the mode is switched.
  --
  -- Type: list of [Message](https://xplr.dev/en/message#message)s
  on_mode_switch = {
    { LogSuccess = "Switched mode" },
    { CallLuaSilently = "custom.some_plugin_with_hooks.on_mode_switch" },
  }

  -- Add messages to send when the layout is switched
  --
  -- Type: list of [Message](https://xplr.dev/en/message#message)s
  on_layout_switch = {
    { LogSuccess = "Switched layout" },
    { CallLuaSilently = "custom.some_plugin_with_hooks.on_layout_switch" },
  }

  -- Add messages to send when the selection changes
  --
  -- Type: list of [Message](https://xplr.dev/en/message#message)s
  on_selection_change = {
    { LogSuccess = "Selection changed" },
    { CallLuaSilently = "custom.some_plugin_with_hooks.on_selection_change" },
  }
}

Note:

It's not recommended to copy the entire configuration, unless you want to freeze it and miss out on useful updates to the defaults.

Instead, you can use this as a reference to overwrite only the parts you want to update.

If you still want to copy the entire configuration, make sure to put your customization before the return statement.

General Configuration

The general configuration properties are grouped together in xplr.config.general.

xplr.config.general.disable_debug_error_mode

Set it to true if you want to ignore the startup errors. You can still see the errors in the logs.

Type: boolean

xplr.config.general.enable_mouse

Set it to true if you want to enable mouse scrolling.

Type: boolean

xplr.config.general.show_hidden

Set it to true to show hidden files by default.

Type: boolean

xplr.config.general.read_only

Set it to true to use only a subset of selected operations that forbids executing commands or performing write operations on the file-system.

Type: boolean

xplr.config.general.enable_recover_mode

Set it to true if you want to enable a safety feature that will save you from yourself when you type recklessly.

Type: boolean

xplr.config.general.hide_remaps_in_help_menu

Set it to true if you want to hide all remaps in the help menu.

Type: boolean

xplr.config.general.paginated_scrolling

Set it to true if you want paginated scrolling.

Type: boolean

xplr.config.general.scroll_padding

Set the padding value to the scroll area. Only applicable when xplr.config.general.paginated_scrolling = false.

Type: boolean

xplr.config.general.enforce_bounded_index_navigation

Set it to true if you want the cursor to stay in the same position when the focus is on the first path and you navigate to the previous path (by pressing up/k), or when the focus is on the last path and you navigate to the next path (by pressing down/j). The default behavior is to rotate from the last/first path.

Type: boolean

xplr.config.general.prompt.format

This is the shape of the prompt for the input buffer.

Type: nullable string

xplr.config.general.prompt.style

This is the style of the prompt for the input buffer.

Type: Style

xplr.config.general.logs.info.format

The string to indicate an information in logs.

Type: nullable string

xplr.config.general.logs.info.style

The style for the information logs.

Type: Style

xplr.config.general.logs.success.format

The string to indicate an success in logs.

Type: nullable string

xplr.config.general.logs.success.style

The style for the success logs.

Type: Style

xplr.config.general.logs.warning.format

The string to indicate an warnings in logs.

Type: nullable string

xplr.config.general.logs.warning.style

The style for the warnings logs.

Type: Style

xplr.config.general.logs.error.format

The string to indicate an error in logs.

Type: nullable string

xplr.config.general.logs.error.style

The style for the error logs.

Type: Style

xplr.config.general.table.header.cols

Columns to display in the table header.

Type: nullable list of tables with the following fields:

• format: nullable string
• style: Style

xplr.config.general.table.header.style

Style of the table header.

Type: Style

xplr.config.general.table.header.height

Height of the table header.

Type: nullable integer

xplr.config.general.table.row.cols

Columns to display in each row in the table.

Type: nullable list of tables with the following fields:

• format: nullable string
• style: Style

xplr.config.general.table.row.style

Default style of the table.

Type: Style

xplr.config.general.table.row.height

Height of the table rows.

Type: nullable integer

xplr.config.general.table.style

Default style of the table.

Type: Style

xplr.config.general.table.tree

Tree to display in the table.

Type: nullable list of tables with the following fields:

• format: nullable string
• style: Style

xplr.config.general.table.col_spacing

Spacing between the columns in the table.

Type: nullable integer

xplr.config.general.table.col_widths

Constraint for the column widths.

Type: nullable list of Constraint

xplr.config.general.selection.item.format

Renderer for each item in the selection list.

Type: nullable string

xplr.config.general.selection.item.style

Style for each item in the selection list.

Type: Style

xplr.config.general.search.algorithm

The default search algorithm

Type: Search Algorithm

xplr.config.general.search.unordered

The default search ordering

Type: boolean

xplr.config.general.default_ui.prefix

The content that is placed before the item name for each row by default.

Type: nullable string

xplr.config.general.default_ui.suffix

The content which is appended to each item name for each row by default.

Type: nullable string

xplr.config.general.default_ui.style

The default style of each item for each row.

Type: Style

xplr.config.general.focus_ui.prefix

The string placed before the item name for a focused row.

Type: nullable string

xplr.config.general.focus_ui.suffix

The string placed after the item name for a focused row.

Type: nullable string

xplr.config.general.focus_ui.style

Style for focused item. Type: Style

xplr.config.general.selection_ui.prefix

The string placed before the item name for a selected row.

Type: nullable string

xplr.config.general.selection_ui.suffix

The string placed after the item name for a selected row.

Type: nullable string

xplr.config.general.selection_ui.style

Style for selected rows.

Type: Style

xplr.config.general.focus_selection_ui.prefix

The string placed before item name for a selected row that gets the focus.

Type: nullable string

xplr.config.general.focus_selection_ui.suffix

The string placed after the item name for a selected row that gets the focus.

Type: nullable string

xplr.config.general.focus_selection_ui.style

Style for a selected row that gets the focus.

Type: Style

xplr.config.general.sort_and_filter_ui.separator.format

The shape of the separator for the Sort & filter panel.

Type: nullable string

xplr.config.general.sort_and_filter_ui.separator.style

The style of the separator for the Sort & filter panel.

Type: Style

xplr.config.general.sort_and_filter_ui.default_identifier.format

The content of the default identifier in Sort & filter panel.

Type: nullable string

xplr.config.general.sort_and_filter_ui.default_identifier.style

Style for the default identifier in Sort & filter panel.

Type: Style

xplr.config.general.sort_and_filter_ui.sort_direction_identifiers.forward.format

The shape of the forward direction indicator for sort identifiers in Sort & filter panel.

Type: nullable string

xplr.config.general.sort_and_filter_ui.sort_direction_identifiers.forward.style

Style of forward direction indicator in Sort & filter panel.

Type: Style

xplr.config.general.sort_and_filter_ui.sort_direction_identifiers.reverse.format

The shape of the reverse direction indicator for sort identifiers in Sort & filter panel.

Type: nullable string

xplr.config.general.sort_and_filter_ui.sort_direction_identifiers.reverse.style

Style of reverse direction indicator in Sort & filter panel.

Type: Style

xplr.config.general.sort_and_filter_ui.sorter_identifiers

The identifiers used to denote applied sorters in the Sort & filter panel.

Type: nullable mapping of the following key-value pairs:

• key: Sorter
• value:
  • format: nullable string
  • style: Style

xplr.config.general.sort_and_filter_ui.filter_identifiers

The identifiers used to denote applied filters in the Sort & filter panel.

Type: nullable mapping of the following key-value pairs:

• key: Filter
• value:
  • format: nullable string
  • style: Style

xplr.config.general.sort_and_filter_ui.search_identifiers

The identifiers used to denote applied search input.

Type: { format = nullable string, style = Style }

xplr.config.general.sort_and_filter_ui.search_direction_identifiers.ordered.format

The shape of ordered indicator for search ordering identifiers in Sort & filter panel.

Type: nullable string

xplr.config.general.sort_and_filter_ui.search_direction_identifiers.unordered.format

The shape of unordered indicator for search ordering identifiers in Sort & filter panel.

Type: nullable string

xplr.config.general.panel_ui.default.title.format

The content for panel title by default.

Type: nullable string

xplr.config.general.panel_ui.default.title.style

The style for panel title by default.

Type: Style

xplr.config.general.panel_ui.default.style

Style of the panels by default.

Type: Style

xplr.config.general.panel_ui.default.borders

Defines where to show borders for the panels by default.

Type: nullable list of Border

xplr.config.general.panel_ui.default.border_type

Type of the borders by default.

Type: nullable Border Type

xplr.config.general.panel_ui.default.border_style

Style of the panel borders by default.

Type: Style

xplr.config.general.panel_ui.table.title.format

The content for the table panel title.

Type: nullable string

xplr.config.general.panel_ui.table.title.style

Style of the table panel title.

Type: Style

xplr.config.general.panel_ui.table.style

Style of the table panel.

Type: Style

xplr.config.general.panel_ui.table.borders

Defines where to show borders for the table panel.

Type: nullable list of Border

xplr.config.general.panel_ui.table.border_type

Type of the borders for table panel.

Type: nullable Border Type

xplr.config.general.panel_ui.table.border_style

Style of the table panel borders.

Type: Style

xplr.config.general.panel_ui.help_menu.title.format

The content for the help menu panel title.

Type: nullable string

xplr.config.general.panel_ui.help_menu.title.style

Style of the help menu panel title.

Type: Style

xplr.config.general.panel_ui.help_menu.style

Style of the help menu panel.

Type: Style

xplr.config.general.panel_ui.help_menu.borders

Defines where to show borders for the help menu panel.

Type: nullable list of Border

xplr.config.general.panel_ui.help_menu.border_type

Type of the borders for help menu panel.

Type: nullable Border Type

xplr.config.general.panel_ui.help_menu.border_style

Style of the help menu panel borders.

Type: Style

xplr.config.general.panel_ui.input_and_logs.title.format

The content for the input & logs panel title.

Type: nullable string

xplr.config.general.panel_ui.input_and_logs.title.style

Style of the input & logs panel title.

Type: Style

xplr.config.general.panel_ui.input_and_logs.borders

xplr.config.general.panel_ui.input_and_logs.style

Style of the input & logs panel.

Type: Style Defines where to show borders for the input & logs panel.

Type: nullable list of Border

xplr.config.general.panel_ui.input_and_logs.border_type

Type of the borders for input & logs panel.

Type: nullable Border Type

xplr.config.general.panel_ui.input_and_logs.border_style

Style of the input & logs panel borders.

Type: Style

xplr.config.general.panel_ui.selection.title.format

The content for the selection panel title.

Type: nullable string

xplr.config.general.panel_ui.selection.title.style

Style of the selection panel title.

Type: Style

xplr.config.general.panel_ui.selection.borders

xplr.config.general.panel_ui.selection.style

Style of the selection panel.

Type: Style Defines where to show borders for the selection panel.

Type: nullable list of Border

xplr.config.general.panel_ui.selection.border_type

Type of the borders for selection panel.

Type: nullable Border Type

xplr.config.general.panel_ui.selection.border_style

Style of the selection panel borders.

Type: Style

xplr.config.general.panel_ui.sort_and_filter.title.format

The content for the sort & filter panel title.

Type: nullable string

xplr.config.general.panel_ui.sort_and_filter.title.style

Style of the sort & filter panel title.

Type: Style

xplr.config.general.panel_ui.sort_and_filter.style

Style of the sort & filter panel.

Type: Style

xplr.config.general.panel_ui.sort_and_filter.borders

Defines where to show borders for the sort & filter panel.

Type: nullable list of Border

xplr.config.general.panel_ui.sort_and_filter.border_type

Type of the borders for sort & filter panel.

Type: nullable Border Type

xplr.config.general.panel_ui.sort_and_filter.border_style

Style of the sort & filter panel borders.

Type: Style

xplr.config.general.initial_sorting

Initial group if sorters applied to the nodes list in the table.

Type: nullable list of Node Sorter

xplr.config.general.initial_mode

The name of one of the modes to use when xplr loads. This isn't the default mode. To modify the default mode, overwrite xplr.config.modes.builtin.default.

Type: nullable string

xplr.config.general.initial_layout

The name of one of the layouts to use when xplr loads. This isn't the default layout. To modify the default layout, overwrite xplr.config.layouts.builtin.default.

Type: nullable string

xplr.config.general.start_fifo

Set it to a file path to start fifo when xplr loads. Generally it is used to integrate with external tools like previewers.

Type: nullable string

xplr.config.general.global_key_bindings

Use it to define a set of key bindings that are available by default in every mode. They can be overwritten.

Type: Key Bindings

Node Types

This section defines how to deal with different kinds of nodes (files, directories, symlinks etc.) based on their properties.

One node can fall into multiple categories. For example, a node can have the extension md, and also be a file. In that case, the properties from the more specific category i.e. extension will be used.

This can be configured using the xplr.config.node_types Lua API.

xplr.config.node_types.directory.style

The style for the directory nodes

Type: Style

xplr.config.node_types.directory.meta.icon

Metadata for the directory nodes. You can set as many metadata as you want.

Type: nullable string

Example:

xplr.config.node_types.directory.meta.foo = "foo"
xplr.config.node_types.directory.meta.bar = "bar"

xplr.config.node_types.file.style

The style for the file nodes.

Type: Style

xplr.config.node_types.file.meta.icon

Metadata for the file nodes. You can set as many metadata as you want.

Type: nullable string

Example:

xplr.config.node_types.file.meta.foo = "foo"
xplr.config.node_types.file.meta.bar = "bar"

xplr.config.node_types.symlink.style

The style for the symlink nodes.

Type: Style

xplr.config.node_types.symlink.meta.icon

Metadata for the symlink nodes. You can set as many metadata as you want.

Type: nullable string

Example:

xplr.config.node_types.symlink.meta.foo = "foo"
xplr.config.node_types.symlink.meta.bar = "bar"

xplr.config.node_types.mime_essence

Metadata and style based on mime types. It is possible to use the wildcard * to match all mime sub types. It will be overwritten by the more specific sub types that are defined.

Type: mapping of the following key-value pairs:

• key: string
• value:
  • key: string
  • value: Node Type

Example:

xplr.config.node_types.mime_essence = {
  application = {
    -- application/*
    ["*"] = { meta = { icon = "a" } },

    -- application/pdf
    pdf = { meta = { icon = "" }, style = { fg = "Blue" } },

    -- application/zip
    zip = { meta = { icon = ""} },
  },
}

xplr.config.node_types.extension

Metadata and style based on extension.

Type: mapping of the following key-value pairs:

• key: string
• value: Node Type

Example:

xplr.config.node_types.extension.md = { meta = { icon = "" }, style = { fg = "Blue" } }
xplr.config.node_types.extension.rs = { meta = { icon = "🦀" } }

xplr.config.node_types.special

Metadata and style based on special file names.

Type: mapping of the following key-value pairs:

• key: string
• value: Node Type

Example:

xplr.config.node_types.special["Cargo.toml"] = { meta = { icon = "" } }
xplr.config.node_types.special["Downloads"] = { meta = { icon = "" }, style = { fg = "Blue" } }

Layouts

xplr layouts define the structure of the UI, i.e. how many panel we see, placement and size of the panels, how they look etc.

This is configuration exposed via the xplr.config.layouts API.

xplr.config.layouts.builtin contain some built-in panels which can be overridden, but you can't add or remove panels in it.

You can add new panels in xplr.config.layouts.custom.

Example: Defining Custom Layout

xplr.config.layouts.builtin.default = {
  Horizontal = {
    config = {
      margin = 1,
      horizontal_margin = 1,
      vertical_margin = 1,
      constraints = {
        { Percentage = 50 },
        { Percentage = 50 },
      }
    },
    splits = {
      "Table",
      "HelpMenu",
    }
  }
}

Result:

╭ /home ─────────────╮╭ Help [default] ────╮
│   ╭─── path        ││.    show hidden    │
│   ├▸[ð Desktop/]   ││/    search         │
│   ├  ð Documents/  ││:    action         │
│   ├  ð Downloads/  ││?    global help    │
│   ├  ð GitHub/     ││G    go to bottom   │
│   ├  ð Music/      ││V    select/unselect│
│   ├  ð Pictures/   ││ctrl duplicate as   │
│   ├  ð Public/     ││ctrl next visit     │
╰────────────────────╯╰────────────────────╯

xplr.config.layouts.builtin.default

The default layout

Type: Layout

xplr.config.layouts.builtin.no_help

The layout without help menu

Type: Layout

xplr.config.layouts.builtin.no_selection

The layout without selection panel

Type: Layout

xplr.config.layouts.builtin.no_help_no_selection

The layout without help menu and selection panel

Type: Layout

xplr.config.layouts.custom

This is where you can define custom layouts

Type: mapping of the following key-value pairs:

• key: string
• value: Layout

Example:

xplr.config.layouts.custom.example = "Nothing" -- Show a blank screen
xplr.config.general.initial_layout = "example" -- Load the example layout

Modes

xplr is a modal file explorer. That means the users switch between different modes, each containing a different set of key bindings to avoid clashes. Users can switch between these modes at run-time.

The modes can be configured using the xplr.config.modes Lua API.

xplr.config.modes.builtin contain some built-in modes which can be overridden, but you can't add or remove modes in it.

xplr.config.modes.builtin.default

The builtin default mode. Visit the Default Key Bindings to see what each mode does.

Type: Mode

xplr.config.modes.builtin.debug_error

The builtin debug error mode.

Type: Mode

xplr.config.modes.builtin.recover

The builtin recover mode.

Type: Mode

xplr.config.modes.builtin.go_to_path

The builtin go to path mode.

Type: Mode

xplr.config.modes.builtin.move_to

The builtin move_to mode.

Type: Mode

xplr.config.modes.builtin.copy_to

The builtin copy_to mode.

Type: Mode

xplr.config.modes.builtin.selection_ops

The builtin selection ops mode.

Type: Mode

xplr.config.modes.builtin.create

The builtin create mode.

Type: Mode

xplr.config.modes.builtin.create_directory

The builtin create directory mode.

Type: Mode

xplr.config.modes.builtin.create_file

The builtin create file mode.

Type: Mode

xplr.config.modes.builtin.number

The builtin number mode.

Type: Mode

xplr.config.modes.builtin.go_to

The builtin go to mode.

Type: Mode

xplr.config.modes.builtin.rename

The builtin rename mode.

Type: Mode

xplr.config.modes.builtin.duplicate_as

The builtin duplicate as mode.

Type: Mode

xplr.config.modes.builtin.delete

The builtin delete mode.

Type: Mode

xplr.config.modes.builtin.action

The builtin action mode.

Type: Mode

xplr.config.modes.builtin.quit

The builtin quit mode.

Type: Mode

xplr.config.modes.builtin.search

The builtin search mode.

Type: Mode

xplr.config.modes.builtin.filter

The builtin filter mode.

Type: Mode

xplr.config.modes.builtin.relative_path_does_match_regex

The builtin relative_path_does_match_regex mode.

Type: Mode

xplr.config.modes.builtin.relative_path_does_not_match_regex

The builtin relative_path_does_not_match_regex mode.

Type: Mode

xplr.config.modes.builtin.sort

The builtin sort mode.

Type: Mode

xplr.config.modes.builtin.switch_layout

The builtin switch layout mode.

Type: Mode

xplr.config.modes.builtin.vroot

The builtin vroot mode.

Type: Mode

xplr.config.modes.builtin.edit_permissions

The builtin edit permissions mode.

Type: Mode

xplr.config.modes.custom

This is where you define custom modes.

Type: mapping of the following key-value pairs:

• key: string
• value: Mode

Example:

xplr.config.modes.custom.example = {
  name = "example",
  key_bindings = {
    on_key = {
      enter = {
        help = "default mode",
        messages = {
          "PopMode",
          { SwitchModeBuiltin = "default" },
        },
      },
    },
  },
}

xplr.config.general.initial_mode = "example"

Concept

These are the concepts that make xplr probably the most hackable terminal file explorer.

• Key Bindings
• Node Type
• Layout
• Mode
• Message
• Borders
• Style
• Sorting
• Filtering
• Column Renderer
• Lua Function Calls
• Environment Variables and Pipes

Sum Type

This section isn't specific to xplr. However, since xplr configuration makes heavy use of this particular data type, even though it isn't available in most of the mainstream programming languages (yet), making it a wild or unfamiliar concept for many, it's worth doing a quick introduction here.

If you're already familiar with Sum Type / Tagged Union (e.g. Rust's enum), you can skip ahead.

While reading this doc, you'll come across some data types like Layout, Color, Message etc. that says something like "x is a sum type that can be any of the following", and then you'll see a list of strings and/or lua tables just below.

Yes, they are actually sum types, i.e. they can be any of the given set of tagged variants listed there.

Notice the word "be". Unlike classes or structs (aka product types), they can't "have" values, they can only "be" the value, or rather, be one of the possible set of values.

Also notice the word "tagged". Unlike the single variant null, or the dual variant boolean types, the variants of sum types are tagged (i.e. named), and may further have, or be, value or values of any data type.

A simple example of a sum type is an enum. Many programming languages have them, but only a few modern programming languages allow nesting other types into a sum type.

#![allow(unused)]
fn main() {
enum Color {
    Red,
    Green,
}
}

Here, Color can be one of two possible set of values: Red and Green, just like boolean, but unlike boolean, being tagged allows Color to have more than two variants if required, by changing the definition.

e.g.

#![allow(unused)]
fn main() {
enum Color {
    Red,
    Green,
    Blue,
}
}

We'd document it here as:

Result is a sum type that can be one of the following:

• "Red"
• "Green"
• "Blue"

But some languages (like Rust, Haskell, Elm etc.) go even further, allowing us to associate each branch of the enum with further nested types like:

#![allow(unused)]
fn main() {
enum Layout {
    Table,
    HelpMenu,
    Horizontal {
        config: LayoutConfig,  // A product type (similar to class/struct)
        splits: Vec<Layout>  // A list of "Layout"s (i.e. list of sum types)
    },
}
}

Here, as we can see, unlike the first example, some of Layout's possible variants can have further nested types associated with them. Note that Horizontal here can have a sum type (e.g. enum), or a product type (e.g. class/struct), or both (any number of them actually) nested in it. But the nested values will only exist when Layout is Horizontal.

We'd document it here as:

Layout is a sum type that can be one of the following:

• "Table"
• "HelpMenu"
• { Horizontal = { config = Layout Config, splits = { Layout, ... } }

And then we'd go on documenting whatever Layout Config is.

So, there you go. This is exactly what sum types are - glorified enums that can have nested types in each branch.

Key Bindings

Key bindings define how each keyboard input will be handled while in a specific mode.

See the Default key bindings for example.

To configure or work with key bindings, visit Configure Key Bindings.

In case you need help debugging key bindings or to understand the system DYI way, refer to the Debug Key Bindings guide.

Configure Key Bindings

In xplr, each keyboard input passes through a bunch of handlers (e.g. on_key, on_number, default etc.) in a given order. If any of the handlers is configured to with an action, it will intercept the key and produce messages for xplr to handle.

Try debug key bindings to understand how key bindings actually work.

Key Bindings

Key bindings contains the following information:

• on_key
• on_alphabet
• on_number
• on_alphanumeric
• on_special_character
• on_character
• on_navigation
• on_function
• default

on_key

Type: mapping of Key to nullable Action

Defines what to do when an exact key is pressed.

on_alphabet

Type: nullable Action

An action to perform if the keyboard input is an alphabet and is not mapped via the on_key field.

on_number

Type: nullable Action

An action to perform if the keyboard input is a number and is not mapped via the on_key field.

on_alphanumeric

Type: nullable Action

An action to perform if the keyboard input is alphanumeric and is not mapped via the on_key, on_alphabet or on_number field.

on_special_character

Type: nullable Action

An action to perform if the keyboard input is a special character and is not mapped via the on_key field.

on_character

Type: nullable Action

An action to perform if the keyboard input is a character and is not mapped via the on_key, on_alphabet, on_number, on_alphanumeric or on_special_character field.

on_navigation

Type: nullable Action

An action to perform if the keyboard input is a navigation key and is not mapped via the on_key field.

on_function

Type: nullable Action

An action to perform if the keyboard input is a function key and is not mapped via the on_key field.

default

Type: nullable Action

Default action to perform in case if a keyboard input not mapped via any of the on_* fields mentioned above.

Key

A key is a sum type can be one of the following:

• 0, 1, ... 9
• a, b, ... z
• A, B, ... Z
• f1, f2, ... f12
• backspace
• left
• right
• up
• down
• home
• end
• page-up
• page-down
• back-tab
• delete
• insert
• enter
• tab
• esc
• ctrl-a, ctrl-b, ... ctrl-z
• ctrl-backspace, ctrl-left, ... ctrl-esc
• alt-a, alt-b, ... alt-z

And finally, the special characters - including space (" ") with their ctrl bindings.

Action

An action contains the following information:

• help
• messages

help

Type: nullable string

Description of what it does. If unspecified, it will be excluded from the help menu.

messages

Type: A list of Message to send.

The list of messages to send when a key is pressed.

Tutorial: Adding a New Mode

Assuming xplr is installed and setup, let's add our own mode to integrate xplr with fzf.

We'll call it fzxplr mode.

First, let's add a custom mode called fzxplr, and map the key F to an action that will call fzf to search and focus on a file or enter into a directory.

xplr.config.modes.custom.fzxplr = {
  name = "fzxplr",
  key_bindings = {
    on_key = {
      F = {
        help = "search",
        messages = {
          {
            BashExec = [===[
              PTH=$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}" | awk -F/ '{print $NF}' | fzf)
              if [ -d "$PTH" ]; then
                "$XPLR" -m 'ChangeDirectory: %q' "$PTH"
              else
                "$XPLR" -m 'FocusPath: %q' "$PTH"
              fi
            ]===]
          },
          "PopMode",
        },
      },
    },
    default = {
      messages = {
        "PopMode",
      },
    },
  },
}

As you can see, the key F in mode fzxplr (the name can be anything) executes a script in bash.

BashExec, PopMode, SwitchModeBuiltin, ChangeDirectory and FocusPath are messages, $XPLR, $XPLR_PIPE_DIRECTORY_NODES_OUT are environment variables exported by xplr before executing the command. They contain the path to the input and output pipes that allows external tools to interact with xplr.

Now that we have our new mode ready, let's add an entry point to this mode via the default mode.

xplr.config.modes.builtin.default.key_bindings.on_key["F"] = {
  help = "fzf mode",
  messages = {
    { SwitchModeCustom = "fzxplr" },
  },
}

Now let's try out the new xplr-fzf integration.

Visit Awesome Plugins for more integration options.

Default Key Bindings

The default key binding is inspired by vim and slightly overlaps with nnn, but it's supposed to be customized as per user requirements.

When you press ? in default mode, you can see the complete list of modes and the key mappings for each mode.

default

go_to_path

rename

recover

go_to

relative_path_does_match_regex

action

default

debug_error

create_directory

selection_ops

relative_path_does_not_match_regex

create_file

quit

create

vroot

search

switch_layout

sort

number

copy_to

edit_permissions

delete

move_to

filter

duplicate_as

Debug Key Bindings

If you need help debugging or understanding key bindings DYI way, you can create a test.lua file with the following script, launch xplr with xplr --extra-config test.lua, press # and play around.

-- The global key bindings inherited by all the modes.
xplr.config.general.global_key_bindings = {
  on_key = {
    esc = {
      help = "escape",
      messages = {
        { LogInfo = "global on_key(esc) called" },
        "PopMode",
      },
    },
    ["ctrl-c"] = {
      help = "terminate",
      messages = {
        "Terminate",
      },
    },
  },
}

-- Press `#` to enter the `debug key bindings` mode.
xplr.config.modes.builtin.default.key_bindings.on_key["#"] = {
  help = "test",
  messages = {
    "PopMode",
    { SwitchModeCustom = "debug_key_bindings" },
  },
}

-- The `debug key bindings` mode.
xplr.config.modes.custom.debug_key_bindings = {
  name = "debug key bindings",
  key_bindings = {
    on_key = {
      ["1"] = {
        messages = {
          { LogInfo = "on_key(1) called" },
        },
      },
      a = {
        messages = {
          { LogInfo = "on_key(a) called" },
        },
      },
      ["`"] = {
        messages = {
          { LogInfo = "on_key(`) called" },
        },
      },
      tab = {
        messages = {
          { LogInfo = "on_key(tab) called" },
        },
      },
      f1 = {
        messages = {
          { LogInfo = "on_key(f1) called" },
        },
      },
    },
    on_alphabet = {
      messages = {
        { LogInfo = "on_alphabet called" },
      },
    },
    on_number = {
      messages = {
        { LogInfo = "on_number called" },
      },
    },
    -- on_alphanumeric = {
    --   messages = {
    --     { LogInfo = "on_alphanumeric called" },
    --   },
    -- },
    on_special_character = {
      messages = {
        { LogInfo = "on_special_character called" },
      },
    },
    -- on_character = {
    --   messages = {
    --     { LogInfo = "on_character called" },
    --   },
    -- },
    on_navigation = {
      messages = {
        { LogInfo = "on_navigation called" },
      },
    },
    on_function = {
      messages = {
        { LogInfo = "on_function called" },
      },
    },
    default = {
      messages = {
        { LogInfo = "default called" },
      },
    },
  },
}

Node Type

A node-type contains the following fields:

• meta
• style

meta

Type: mapping of string and string

A meta field can contain custom metadata about a node. By default, the "icon" metadata is set for the directory, file, and symlink nodes.

Example:

xplr.config.node_types.file = {
  meta = {
    icon = "f",
    foo = "bar",
  }
}

Also See:

• xplr.config.node_types

Layout

Example: Defining Custom Layout

xplr.config.layouts.builtin.default = {
  Horizontal = {
    config = {
      margin = 1,
      horizontal_margin = 1,
      vertical_margin = 1,
      constraints = {
        { Percentage = 50 },
        { Percentage = 50 },
      }
    },
    splits = {
      "Table",
      "HelpMenu",
    }
  }
}

Result:

 ╭ /home ─────────────╮╭ Help [default] ────╮
 │   ╭─── path        ││.    show hidden    │
 │   ├▸[ð Desktop/]   ││/    search         │
 │   ├  ð Documents/  ││:    action         │
 │   ├  ð Downloads/  ││?    global help    │
 │   ├  ð GitHub/     ││G    go to bottom   │
 │   ├  ð Music/      ││V    select/unselect│
 │   ├  ð Pictures/   ││ctrl duplicate as   │
 │   ├  ð Public/     ││ctrl next visit     │
 ╰────────────────────╯╰────────────────────╯

A layout is a sum type can be one of the following:

• Nothing
• Table
• InputAndLogs
• Selection
• HelpMenu
• SortAndFilter
• Static
• Dynamic
• Horizontal
• Vertical
• CustomContent (deprecated, use Static or Dynamic)

Nothing

This layout contains a blank panel.

Type: "Nothing"

Table

This layout contains the table displaying the files and directories in the current directory.

InputAndLogs

This layout contains the panel displaying the input prompt and logs.

Type: "InputAndLogs"

Selection

This layout contains the panel displaying the selected paths.

Type: "Selection"

HelpMenu

This layout contains the panel displaying the help menu for the current mode in real-time.

Type: "HelpMenu"

SortAndFilter

This layout contains the panel displaying the pipeline of sorters and filters applied on the list of paths being displayed.

Type: "SortAndFilter"

Static

This is a custom layout to render static content.

Type: { Static = Custom Panel }

Dynamic

This is a custom layout to render dynamic content using a function defined in xplr.fn that takes Content Renderer Argument and returns Custom Panel.

Type: { Dynamic = "Content Renderer" }

Horizontal

This is a special layout that splits the panel into two horizontal parts.

It contains the following information:

• config
• splits

Type: { Vertical = { config = Layout Config, splits = { Layout, ... } }

Vertical

This is a special layout that splits the panel into two vertical parts.

It contains the following information:

• config
• splits

Type: { Vertical = { config = Layout Config, splits = { Layout, ... } }

Layout Config

A layout config contains the following information:

• margin
• horizontal_margin
• vertical_margin
• constraints

margin

Type: nullable integer

The width of the margin in all direction.

horizontal_Margin

Type: nullable integer

The width of the horizontal margins. Overwrites the margin value.

vertical_Margin

Type: nullable integer

The width of the vertical margins. Overwrites the margin value.

constraints

Type: nullable list of Constraint

The constraints applied on the layout.

Constraint

A constraint is a sum type can be one of the following:

• { Percentage = int }
• { Ratio = { int, int } }
• { Length = { int }
• { LengthLessThanScreenHeight = int }
• { LengthLessThanScreenWidth = int }
• { LengthLessThanLayoutHeight = int }
• { LengthLessThanLayoutWidth = int }
• { Max = int }
• { MaxLessThanScreenHeight = int }
• { MaxLessThanScreenWidth = int }
• { MaxLessThanLayoutHeight = int }
• { MaxLessThanLayoutWidth = int }
• { Min = int }
• { MinLessThanScreenHeight = int }
• { MinLessThanScreenWidth = int }
• { MinLessThanLayoutHeight = int }
• { MinLessThanLayoutWidth = int }

splits

Type: list of Layout

The list of child layouts to fit into the parent layout.

Custom Panel

Custom panel is a sum type can be one of the following:

• CustomParagraph
• CustomList
• CustomTable
• CustomLayout

CustomParagraph

A paragraph to render. It contains the following fields:

• ui (nullable Panel UI Config): Optional UI config for the panel.
• body (string): The string to render.

Example: Render a custom static paragraph

xplr.config.layouts.builtin.default = {
  Static = {
    CustomParagraph = {
      ui = { title = { format = " custom title " } },
      body = "custom body",
    },
  },
}

Result:

╭ custom title ────────╮
│custom body           │
│                      │
│                      │
╰──────────────────────╯

Example: Render a custom dynamic paragraph

xplr.config.layouts.builtin.default = { Dynamic = "custom.render_layout" }

xplr.fn.custom.render_layout = function(ctx)
  return {
    CustomParagraph = {
      ui = { title = { format = ctx.app.pwd } },
      body = xplr.util.to_yaml(ctx.app.focused_node),
    },
  }
end

Result:

╭/home/sayanarijit───────────────────────────╮
│mime_essence: inode/directory               │
│relative_path: Desktop                      │
│is_symlink: false                           │
│is_readonly: false                          │
│parent: /home/sayanarijit                   │
│absolute_path: /home/sayanarijit/Desktop    │
│is_broken: false                            │
│created: 1668087850396758714                │
│size: 4096                                  │
│gid: 100                                    │
╰────────────────────────────────────────────╯

CustomList

A list to render. It contains the following fields:

• ui (nullable Panel UI Config): Optional UI config for the panel.
• body (list of string): The list of strings to display.

Example: Render a custom static list

xplr.config.layouts.builtin.default = {
  Static = {
    CustomList = {
      ui = { title = { format = " custom title " } },
      body = { "1", "2", "3" },
    },
  },
}

Result:

╭ custom title ─────────────╮
│1                          │
│2                          │
│3                          │
│                           │
╰───────────────────────────╯

Example: Render a custom dynamic list

xplr.config.layouts.builtin.default = { Dynamic = "custom.render_layout" }

xplr.fn.custom.render_layout = function(ctx)
  return {
    CustomList = {
      ui = { title = { format = ctx.app.pwd } },
      body = {
        (ctx.app.focused_node or {}).relative_path or "",
        ctx.app.version,
        tostring(ctx.app.pid),
      },
    },
  }
end

Result:

╭/home/sayanarijit──────────╮
│Desktop                    │
│0.21.2                     │
│17336                      │
│                           │
│                           │
╰───────────────────────────╯

CustomTable

A custom table to render. It contains the following fields:

• ui (nullable Panel UI Config): Optional UI config for the panel.
• widths (list of Constraint): Width of the columns.
• col_spacing (nullable int): Spacing between columns. Defaults to 1.
• body (list of list of string): The rows and columns to render.

Example: Render a custom static table

xplr.config.layouts.builtin.default = {
  Static = {
    CustomTable = {
      ui = { title = { format = " custom title " } },
      widths = {
        { Percentage = 50 },
        { Percentage = 50 },
      },
      body = {
        { "a", "b" },
        { "c", "d" },
      },
    },
  },
}

Result:

╭ custom title ────────────────────╮
│a                 b               │
│c                 d               │
│                                  │
│                                  │
│                                  │
╰──────────────────────────────────╯

Example: Render a custom dynamic table

xplr.config.layouts.builtin.default = {Dynamic = "custom.render_layout" }

xplr.fn.custom.render_layout = function(ctx)
  return {
    CustomTable = {
      ui = { title = { format = ctx.app.pwd } },
      widths = {
        { Percentage = 50 },
        { Percentage = 50 },
      },
      body = {
        { "", "" },
        { "Layout height", tostring(ctx.layout_size.height) },
        { "Layout width", tostring(ctx.layout_size.width) },
        { "", "" },
        { "Screen height", tostring(ctx.screen_size.height) },
        { "Screen width", tostring(ctx.screen_size.width) },
      },
    },
  }
end

Result:

╭/home/sayanarijit───────────────────────────╮
│                                            │
│Layout height          12                   │
│Layout width           46                   │
│                                            │
│Screen height          12                   │
│Screen width           46                   │
│                                            │
│                                            │
│                                            │
│                                            │
╰────────────────────────────────────────────╯

CustomLayout

A whole custom layout to render. It doesn't make sense to use it as a Static layout, but can be very useful to render as a Dynamic layout for use cases where the structure of the layout needs to change without having to switch modes.

WARNING: Rendering the same dynamic custom layout recursively will result in a ugly crash.

Example: Render a custom dynamic layout

xplr.config.layouts.builtin.default = { Dynamic = "custom.render_layout" }

xplr.fn.custom.render_layout = function(ctx)
  local inner = {
    config = {
      constraints = {
        { Percentage = 50 },
        { Percentage = 50 },
      },
    },
    splits = {
      { Static = { CustomParagraph = { body = "Try your luck..." } } },
      { Static = { CustomParagraph = { body = "Press ctrl-r" } } },
    },
  }

  local layout_type = "Vertical"
  if math.random(1, 2) == 1 then
    layout_type = "Horizontal"
  end

  return { CustomLayout = { [layout_type] = inner } }
end

Result:

╭─────────────────────╮╭─────────────────────╮
│Try your luck...     ││Press ctrl-r         │
│                     ││                     │
│                     ││                     │
│                     ││                     │
│                     ││                     │
│                     ││                     │
│                     ││                     │
│                     ││                     │
│                     ││                     │
│                     ││                     │
╰─────────────────────╯╰─────────────────────╯

Or

╭────────────────────────────────────────────╮
│Try your luck...                            │
│                                            │
│                                            │
│                                            │
╰────────────────────────────────────────────╯
╭────────────────────────────────────────────╮
│Press ctrl-r                                │
│                                            │
│                                            │
│                                            │
╰────────────────────────────────────────────╯

Panel UI Config

It contains the following optional fields:

• title ({ format = "string", style = Style }): the title of the panel.
• style (Style): The style of the panel body.
• borders (nullable list of Border): The shape of the borders.
• border_type (Border Type): The type of the borders.
• border_style (Style): The style of the borders.

Content Renderer

It is a Lua function that receives a special argument as input and returns some output that can be rendered in the UI. It is used to render content body for the custom dynamic layouts.

Content Renderer Argument

It contains the following information:

• layout_size
• screen_size
• scrolltop
• app

Size

It contains the following information:

• x
• y
• height
• width

Every field is of integer type.

scrolltop

Type: integer

The start index of the visible nodes in the table.

app

This is a lightweight version of the Lua Context. In this context, the heavyweight fields like directory_buffer are omitted for performance reasons.

Hence, only the following fields are available.

• version
• pwd
• initial_pwd
• vroot
• focused_node
• selection
• mode
• layout
• input_buffer
• pid
• session_path
• explorer_config

Also See:

• xplr.config.layouts

Mode

A mode contains the following information:

• name
• help
• extra_help
• key_bindings
• layout
• prompt

name

Type: string

This is the name of the mode visible in the help menu.

help

Type: nullable string

If specified, the help menu will display this instead of the auto generated mappings.

extra_help

Type: nullable string

If specified, the help menu will display this along-side the auto generated help menu.

key_bindings

Type: Key Bindings

The key bindings available in that mode.

layout

Type: nullable Layout

If specified, this layout will be used to render the UI.

prompt

Type: nullable string

If set, this prompt will be displayed in the input buffer when in this mode.

Also See:

• xplr.config.modes

Message

You can think of xplr as a server. Just like web servers listen to HTTP requests, xplr listens to messages.

A message is a sum type that can have these possible values.

You can send these messages to an xplr session in the following ways:

• Via command-line (currently during start-up only, using --on-load)
• Via key bindings
• Via Lua function calls
• Via shell command using the input pipe
• Via socket (coming soon)

Format

To send messages using the key bindings or Lua function calls, messages are represented in Lua syntax.

For example:

• "Quit"
• { FocusPath = "/path/to/file" }
• { Call = { command = "bash", args = { "-c", "read -p test" } } }

However, to send messages using the input pipe, they need to be represented using YAML (or JSON) syntax.

For example:

• Quit
• FocusPath: "/path/to/file"
• Call: { command: bash, args: ["-c", "read -p test"] }

Use "$XPLR" -m TEMPLATE [VALUE]... command-line option to safely format TEMPLATE into a valid message. If uses jf to parse and render the template. And $XPLR (rather than xplr) makes sure that the correct version of the binary is being used.

For example:

• "$XPLR" -m Quit
• "$XPLR" -m 'FocusPath: %q' "/path/to/file"
• "$XPLR" -m 'Call: { command: %q, args: [%*q] }' bash -c "read -p test"

Also See:

• Full List of Messages

Full List of Messages

xplr messages categorized based on their purpose.

Categories

• Exploring
• Screen
• Navigation
• Virtual Root
• Reading Input
• Switching Mode
• Switching Layout
• Executing Commands
• Calling Lua Functions
• Select Operations
• Filter Operations
• Sort Operations
• Search Operations
• Mouse Operations
• Fifo Operations
• Logging
• Debugging
• Quit Options

Exploring

ExplorePwd

Explore the present working directory and register the filtered nodes. This operation is expensive. So, try to avoid using it too often.

Example:

• Lua: "ExplorePwd"
• YAML: ExplorePwd

ExplorePwdAsync

Explore the present working directory and register the filtered nodes asynchronously. This operation happens asynchronously. That means, the xplr directory buffers won't be updated immediately. Hence, it needs to be used with care and probably with special checks in place. To explore $PWD synchronously, use ExplorePwd instead.

Example:

• Lua: "ExplorePwdAsync"
• YAML: ExplorePwdAsync

ExploreParentsAsync

Explore the present working directory along with its parents and register the filtered nodes. This operation happens asynchronously. That means, the xplr directory buffers won't be updated immediately. Hence, it needs to be used with care and probably with special checks in place. To explore just the $PWD synchronously, use ExplorePwd instead.

Example:

• Lua: "ExploreParentsAsync"
• YAML: ExploreParentsAsync

Screen

ClearScreen

Clear the screen.

Example:

• Lua: "ClearScreen"
• YAML: ClearScreen

Refresh

Refresh the screen. But it will not re-explore the directory if the working directory is the same. If there is some change in the working directory and you want to re-explore it, use the Explore message instead. Also, it will not clear the screen. Use ClearScreen for that.

Example:

• Lua: "Refresh"
• YAML: Refresh

Navigation

FocusNext

Focus next node.

Example:

• Lua: "FocusNext"
• YAML: FocusNext

FocusNextSelection

Focus on the next selected node.

Example:

• Lua: "FocusNextSelection"
• YAML: FocusNextSelection

FocusNextByRelativeIndex

Focus on the nth node relative to the current focus where n is a given value.

Type: { FocusNextByRelativeIndex = int }

Example:

• Lua: { FocusNextByRelativeIndex = 2 }
• YAML: FocusNextByRelativeIndex: 2

FocusNextByRelativeIndexFromInput

Focus on the nth node relative to the current focus where n is read from the input buffer.

Example:

• Lua: "FocusNextByRelativeIndexFromInput"
• YAML: FocusNextByRelativeIndexFromInput

FocusPrevious

Focus on the previous item.

Example:

• Lua: "FocusPrevious"
• YAML: FocusPrevious

FocusPreviousSelection

Focus on the previous selection item.

Example:

• Lua: "FocusPreviousSelection"
• YAML: FocusPreviousSelection

FocusPreviousByRelativeIndex

Focus on the -nth node relative to the current focus where n is a given value.

Type: { FocusPreviousByRelativeIndex = int }

Example:

• Lua: { FocusPreviousByRelativeIndex = 2 }
• YAML: FocusPreviousByRelativeIndex: 2

FocusPreviousByRelativeIndexFromInput

Focus on the -nth node relative to the current focus where n is read from the input buffer.

Example:

• Lua: "FocusPreviousByRelativeIndexFromInput"
• YAML: FocusPreviousByRelativeIndexFromInput

FocusFirst

Focus on the first node.

Example:

• Lua: "FocusFirst"
• YAML: FocusFirst

FocusLast

Focus on the last node.

Example:

• Lua: "FocusLast"
• YAML: FocusLast

FocusPath

Focus on the given path.

Type: { FocusPath = "string" }

Example:

• Lua: { FocusPath = "/path/to/file" }
• YAML: FocusPath: /path/to/file

FocusPathFromInput

Focus on the path read from input buffer.

Example:

• Lua: "FocusPathFromInput"
• YAML: FocusPathFromInput

FocusByIndex

Focus on the absolute nth node where n is a given value.

Type: { FocusByIndex = int }

Example:

• Lua: { FocusByIndex = 2 }
• YAML: FocusByIndex: 2

FocusByIndexFromInput

Focus on the absolute nth node where n is read from the input buffer.

Example:

• Lua: "FocusByIndexFromInput"
• YAML: FocusByIndexFromInput

FocusByFileName

Focus on the file by name from the present working directory.

Type: { FocusByFileName = "string" }

Example:

• Lua: { FocusByFileName = "filename.ext" }
• YAML: FocusByFileName: filename.ext

ScrollUp

Scroll up by terminal height.

Example:

• Lua: "ScrollUp"
• YAML: ScrollUp

ScrollDown

Scroll down by terminal height.

Example:

• Lua: "ScrollDown"
• YAML: ScrollDown

ScrollUpHalf

Scroll up by half of terminal height.

Example:

• Lua: "ScrollUpHalf"
• YAML: ScrollUpHalf

ScrollDownHalf

Scroll down by half of terminal height.

Example:

• Lua: "ScrollDownHalf"
• YAML: ScrollDownHalf

ChangeDirectory

Change the present working directory ($PWD)

Type: { ChangeDirectory = "string" }

Example:

• Lua: { ChangeDirectory = "/path/to/directory" }
• YAML: ChangeDirectory: /path/to/directory

Enter

Enter into the currently focused path if it's a directory.

Example:

• Lua: "Enter"
• YAML: Enter

Back

Go back to the parent directory.

Example:

• Lua: "Back"
• YAML: Back

LastVisitedPath

Go to the last path visited.

Example:

• Lua: "LastVisitedPath"
• YAML: LastVisitedPath

NextVisitedPath

Go to the next path visited.

Example:

• Lua: "NextVisitedPath"
• YAML: NextVisitedPath

PreviousVisitedDeepBranch

Go to the previous deep level branch.

Example:

• Lua: "PreviousVisitedDeepBranch"
• YAML: PreviousVisitedDeepBranch

NextVisitedDeepBranch

Go to the next deep level branch.

Example:

• Lua: "NextVisitedDeepBranch"
• YAML: NextVisitedDeepBranch

FollowSymlink

Follow the symlink under focus to its actual location.

Example:

• Lua: "FollowSymlink"
• YAML: FollowSymlink

Virtual Root

SetVroot

Sets the virtual root for isolating xplr navigation, similar to --vroot, but temporary (can be reset back to initial value). If the $PWD is outside the vroot, xplr will automatically enter vroot.

Type: { SetVroot = "string" }

Example:

• Lua: { SetVroot = "/tmp" }
• YAML: SetVroot: /tmp

UnsetVroot

Unset the virtual root temporarily (can be reset back to the initial value).

Example:

• Lua: "UnsetVroot"
• YAML: UnsetVroot

ToggleVroot

Toggle virtual root between unset, initial value and $PWD.

Example:

• Lua: "ToggleVroot"
• YAML: ToggleVroot

ResetVroot

Reset the virtual root back to the initial value.

Example:

• Lua: "ResetVroot"
• YAML: ResetVroot

Reading Input

SetInputPrompt

Set the input prompt temporarily, until the input buffer is reset.

Type: { SetInputPrompt = string }

Example:

• Lua: { SetInputPrompt = "→" }
• YAML: SetInputPrompt: →

UpdateInputBuffer

Update the input buffer using cursor based operations.

Type: { UpdateInputBuffer = Input Operation }

Example:

• Lua: { UpdateInputBuffer = "GoToPreviousWord" }
• YAML: UpdateInputBuffer: GoToPreviousWord

UpdateInputBufferFromKey

Update the input buffer from the key read from keyboard input.

Example:

• Lua: "UpdateInputBufferFromKey"
• YAML: UpdateInputBufferFromKey

BufferInput

Append/buffer the given string into the input buffer.

Type: { BufferInput = "string" }

Example:

• Lua: { BufferInput = "foo" }
• YAML: BufferInput: foo

BufferInputFromKey

Append/buffer the character read from a keyboard input into the input buffer.

Example:

• Lua: "BufferInputFromKey"
• YAML: BufferInputFromKey

SetInputBuffer

Set/rewrite the input buffer with the given string. When the input buffer is not-null (even if empty string) it will show in the UI.

Type: { SetInputBuffer = "string" }

Example:

• Lua: { SetInputBuffer = "foo" }
• YAML: SetInputBuffer: foo

RemoveInputBufferLastCharacter

Remove input buffer's last character.

Example:

• Lua: "RemoveInputBufferLastCharacter"
• YAML: RemoveInputBufferLastCharacter

RemoveInputBufferLastWord

Remove input buffer's last word.

Example:

• Lua: "RemoveInputBufferLastWord"
• YAML: RemoveInputBufferLastWord

ResetInputBuffer

Reset the input buffer back to null. It will not show in the UI.

Example:

• Lua: "ResetInputBuffer"
• YAML: ResetInputBuffer

Switching Mode

SwitchMode

Switch input mode.

Type : { SwitchMode = "string" }

Example:

• Lua: { SwitchMode = "default" }
• YAML: SwitchMode: default

NOTE: To be specific about which mode to switch to, use SwitchModeBuiltin or SwitchModeCustom instead.

SwitchModeKeepingInputBuffer

Switch input mode. It keeps the input buffer.

Type: { SwitchModeKeepingInputBuffer = "string" }

Example:

• Lua: { SwitchModeKeepingInputBuffer = "default" }
• YAML: SwitchModeKeepingInputBuffer: default

NOTE: To be specific about which mode to switch to, use SwitchModeBuiltinKeepingInputBuffer or SwitchModeCustomKeepingInputBuffer instead.

SwitchModeBuiltin

Switch to a builtin mode. It clears the input buffer.

Type: { SwitchModeBuiltin = "string" }

Example:

• Lua: { SwitchModeBuiltin = "default" }
• YAML: SwitchModeBuiltin: default

SwitchModeBuiltinKeepingInputBuffer

Switch to a builtin mode. It keeps the input buffer.

Type: { SwitchModeBuiltinKeepingInputBuffer = "string" }

Example:

• Lua: { SwitchModeBuiltinKeepingInputBuffer = "default" }
• YAML: SwitchModeBuiltinKeepingInputBuffer: default

SwitchModeCustom

Switch to a custom mode. It clears the input buffer.

Type: { SwitchModeCustom = "string" }

Example:

• Lua: { SwitchModeCustom = "my_custom_mode" }
• YAML: SwitchModeCustom: my_custom_mode

SwitchModeCustomKeepingInputBuffer

Switch to a custom mode. It keeps the input buffer.

Type: { SwitchModeCustomKeepingInputBuffer = "string" }

Example:

• Lua: { SwitchModeCustomKeepingInputBuffer = "my_custom_mode" }
• YAML: SwitchModeCustomKeepingInputBuffer: my_custom_mode

PopMode

Pop the last mode from the history and switch to it. It clears the input buffer.

Example:

• Lua: "PopMode"
• YAML: PopMode

PopModeKeepingInputBuffer

Pop the last mode from the history and switch to it. It keeps the input buffer.

Example:

• Lua: PopModeKeepingInputBuffer
• YAML: PopModeKeepingInputBuffer

Switching Layout

SwitchLayout

Switch layout.

Type: { SwitchLayout = "string" }

Example:

• Lua: { SwitchLayout = "default" }
• YAML: SwitchLayout: default

NOTE: To be specific about which layout to switch to, use SwitchLayoutBuiltin or SwitchLayoutCustom instead.

SwitchLayoutBuiltin

Switch to a builtin layout.

Type: { SwitchLayoutBuiltin = "string" }

Example:

• Lua: { SwitchLayoutBuiltin = "default" }
• YAML: SwitchLayoutBuiltin: default

SwitchLayoutCustom

Switch to a custom layout.

Type: { SwitchLayoutCustom = "string" }

Example:

• Lua: { SwitchLayoutCustom = "my_custom_layout" }
• YAML: SwitchLayoutCustom: my_custom_layout

Executing Commands

Call

Like Call0, but it uses \n as the delimiter in input/output pipes, hence it cannot handle files with \n in the name. You may want to use Call0 instead.

Call0

Call a shell command with the given arguments. Note that the arguments will be shell-escaped. So to read the variables, the -c option of the shell can be used. You may need to pass ExplorePwd depending on the expectation.

Type: { Call0 = { command = "string", args = { "list", "of", "string" } }

Example:

• Lua: { Call0 = { command = "bash", args = { "-c", "read -p test" } } }
• YAML: Call0: { command: bash, args: ["-c", "read -p test"] }

CallSilently

Like CallSilently0, but it uses \n as the delimiter in input/output pipes, hence it cannot handle files with \n in the name. You may want to use CallSilently0 instead.

CallSilently0

Like Call0 but without the flicker. The stdin, stdout stderr will be piped to null. So it's non-interactive.

Type: { CallSilently0 = { command = "string", args = {"list", "of", "string"} } }

Example:

• Lua: { CallSilently0 = { command = "tput", args = { "bell" } } }
• YAML: CallSilently0: { command: tput, args: ["bell"] }

BashExec

Like BashExec0, but it uses \n as the delimiter in input/output pipes, hence it cannot handle files with \n in the name. You may want to use BashExec0 instead.

BashExec0

An alias to Call: {command: bash, args: ["-c", "{string}"], silent: false} where {string} is the given value.

Type: { BashExec0 = "string" }

Example:

• Lua: { BashExec0 = "read -p test" }
• YAML: BashExec0: "read -p test"

BashExecSilently

Like BashExecSilently0, but it uses \n as the delimiter in input/output pipes, hence it cannot handle files with \n in the name. You may want to use BashExecSilently0 instead.

BashExecSilently0

Like BashExec0 but without the flicker. The stdin, stdout stderr will be piped to null. So it's non-interactive.

Type: { BashExecSilently0 = "string" }

Example:

• Lua: { BashExecSilently0 = "tput bell" }
• YAML: BashExecSilently0: "tput bell"

Calling Lua Functions

CallLua

Call a Lua function.

A Lua Context object will be passed to the function as argument. The function can optionally return a list of messages for xplr to handle after the executing the function.

Type: { CallLua = "string" }

Example:

• Lua: { CallLua = "custom.some_custom_funtion" }
• YAML: CallLua: custom.some_custom_funtion

CallLuaSilently

Like CallLua but without the flicker. The stdin, stdout stderr will be piped to null. So it's non-interactive.

Type: { CallLuaSilently = "string" }

Example:

• Lua: { CallLuaSilently = "custom.some_custom_function" }
• YAML: CallLuaSilently: custom.some_custom_function

LuaEval

Execute Lua code without needing to define a function.

If the string is a callable, xplr will try to call it with with the Lua Context argument.

Type: { LuaEval = "string" }

Example:

• Lua: { LuaEval = [[return { { LogInfo = io.read() } }]] }
• Lua: { LuaEval = [[function(app) return { { LogInfo = app.pwd } } end]] }
• YAML: LuaEval: "return { { LogInfo = io.read() } }"
• YAML: LuaEval: "function(app) return { { LogInfo = app.pwd } } end"

LuaEvalSilently

Like LuaEval but without the flicker. The stdin, stdout stderr will be piped to null. So it's non-interactive.

Type: { LuaEvalSilently = "string" }

Example:

• Lua: { LuaEvalSilently = [[return { { LogInfo = "foo" } }]] }
• YAML: LuaEvalSilently: "return { { LogInfo = 'foo' } }"

Select Operations

Select

Select the focused node.

Example:

• Lua: "Select"
• YAML: Select

SelectAll

Select all the visible nodes.

Example:

• Lua: "SelectAll"
• YAML: SelectAll

SelectPath

Select the given path.

Type: { SelectPath = "string" }

Example:

• Lua: { SelectPath = "/path/to/file" }
• YAML: SelectPath: /path/to/file

UnSelect

Unselect the focused node.

Example:

• Lua: "UnSelect"
• YAML: UnSelect

UnSelectAll

Unselect all the visible nodes.

Example:

• Lua: "UnSelectAll"
• YAML: UnSelectAll

UnSelectPath

UnSelect the given path.

Type: { UnSelectPath = "string)" }

Example:

• Lua: { UnSelectPath = "/path/to/file" }
• YAML: UnSelectPath: /path/to/file

ToggleSelection

Toggle selection on the focused node.

Example:

• Lua: "ToggleSelection"
• YAML ToggleSelection

ToggleSelectAll

Toggle between select all and unselect all. Example:

• Lua: "ToggleSelectAll"
• YAML: ToggleSelectAll

ToggleSelectionByPath

Toggle selection by file path.

Type: { ToggleSelectionByPath = "string" }

Example:

• Lua: { ToggleSelectionByPath = "/path/to/file" }
• YAML: ToggleSelectionByPath: /path/to/file

ClearSelection

Clear the selection.

Example:

• Lua: "ClearSelection"
• YAML: ClearSelection

Filter Operations

AddNodeFilter

Add a filter to exclude nodes while exploring directories. You need to call ExplorePwd or ExplorePwdAsync explicitly. Filters get automatically cleared when changing directories.

Type: { AddNodeFilter = { filter = Filter, input = "string" }

Example:

• Lua: { AddNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }
• YAML: AddNodeFilter: { filter: RelativePathDoesStartWith, input: foo }

RemoveNodeFilter

Remove an existing filter. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Type: { RemoveNodeFilter = { filter = Filter, input = "string" }

Example:

• Lua: { RemoveNodeFilter: { filter: "RelativePathDoesStartWith", input: "foo" } }
• YAML: RemoveNodeFilter: { filter: RelativePathDoesStartWith, input: foo }

ToggleNodeFilter

Remove a filter if it exists, else, add a it. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Type: { ToggleNodeFilter = { filter = Filter, input = "string" }

Example:

• Lua: { ToggleNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }
• YAML: ToggleNodeFilter: { filter: RelativePathDoesStartWith, input: foo }

AddNodeFilterFromInput

Add a node filter reading the input from the buffer. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Type: { AddNodeFilterFromInput = Filter }

Example:

• Lua: { AddNodeFilterFromInput = "RelativePathDoesStartWith" }
• YAML: AddNodeFilterFromInput: RelativePathDoesStartWith

RemoveNodeFilterFromInput

Remove a node filter reading the input from the buffer. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Type: { RemoveNodeFilterFromInput = Filter }

Example:

• Lua: { RemoveNodeFilterFromInput = "RelativePathDoesStartWith" }
• YAML: RemoveNodeFilterFromInput: RelativePathDoesStartWith

RemoveLastNodeFilter

Remove the last node filter. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Example:

• Lua: "RemoveLastNodeFilter"
• YAML: RemoveLastNodeFilter

ResetNodeFilters

Reset the node filters back to the default configuration. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Example:

• Lua: "ResetNodeFilters"
• YAML: ResetNodeFilters

ClearNodeFilters

Clear all the node filters. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Example:

• Lua: "ClearNodeFilters"
• YAML: ClearNodeFilters

Sort Operations

AddNodeSorter

Add a sorter to sort nodes while exploring directories. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Type: { AddNodeSorter = { sorter = Sorter, reverse = bool } }

Example:

• Lua: { AddNodeSorter = { sorter = "ByRelativePath", reverse = false } }
• YAML: AddNodeSorter: { sorter: ByRelativePath, reverse: false }

RemoveNodeSorter

Remove an existing sorter. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Type: { RemoveNodeSorter = Sorter }

Example:

• Lua: { RemoveNodeSorter = "ByRelativePath" }
• YAML: RemoveNodeSorter: ByRelativePath

ReverseNodeSorter

Reverse a node sorter. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Type: { ReverseNodeSorter = Sorter }

Example:

• Lua: { ReverseNodeSorter = "ByRelativePath" }
• YAML: ReverseNodeSorter: ByRelativePath

ToggleNodeSorter

Remove a sorter if it exists, else, add a it. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Type: { ToggleNodeSorter = { sorter = Sorter, reverse = bool } }

Example:

• Lua: { ToggleSorterSorter: { sorter = "ByRelativePath", reverse = false } }
• YAML: ToggleSorterSorter: {sorter: ByRelativePath, reverse: false }

ReverseNodeSorters

Reverse the node sorters. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Example:

• Lua: "ReverseNodeSorters"
• YAML: ReverseNodeSorters

RemoveLastNodeSorter

Remove the last node sorter. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Example:

• Lua: "RemoveLastNodeSorter"
• YAML: RemoveLastNodeSorter

ResetNodeSorters

Reset the node sorters back to the default configuration. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Example:

• Lua: "ResetNodeSorters"
• YAML: ResetNodeSorters

ClearNodeSorters

Clear all the node sorters. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Example:

• Lua: "ClearNodeSorters"
• YAML: ClearNodeSorters

Search Operations

Search

Search files using the current or default (fuzzy) search algorithm. You need to call ExplorePwd or ExplorePwdAsync explicitly. It gets reset automatically when changing directory.

Type: { Search = "string" }

Example:

• Lua: { Search = "pattern" }
• YAML: Search: pattern

SearchFromInput

Calls Search with the input taken from the input buffer.

Example:

• Lua: "SearchFromInput"
• YAML: SearchFromInput

SearchFuzzy

Search files using fuzzy match algorithm. It keeps the filters, but overrides the sorters. You need to call ExplorePwd or ExplorePwdAsync explicitly. It gets reset automatically when changing directory.

Type: { SearchFuzzy = "string" }

Example:

• Lua: { SearchFuzzy = "pattern" }
• YAML: SearchFuzzy: pattern

SearchFuzzyFromInput

Calls SearchFuzzy with the input taken from the input buffer. You need to call ExplorePwd or ExplorePwdAsync explicitly. It gets reset automatically when changing directory.

Example:

• Lua: "SearchFuzzyFromInput"
• YAML: SearchFuzzyFromInput

SearchFuzzyUnordered

Like SearchFuzzy, but doesn't not perform rank based sorting. You need to call ExplorePwd or ExplorePwdAsync explicitly. It gets reset automatically when changing directory.

Type: { SearchFuzzyUnordered = "string" }

Example:

• Lua: { SearchFuzzyUnordered = "pattern" }
• YAML: SearchFuzzyUnordered: pattern

SearchFuzzyUnorderedFromInput

Calls SearchFuzzyUnordered with the input taken from the input buffer. You need to call ExplorePwd or ExplorePwdAsync explicitly. It gets reset automatically when changing directory.

Example:

• Lua: "SearchFuzzyUnorderedFromInput"
• YAML: SearchFuzzyUnorderedFromInput

SearchRegex

Search files using regex match algorithm. It keeps the filters, but overrides the sorters. You need to call ExplorePwd or ExplorePwdAsync explicitly. It gets reset automatically when changing directory.

Type: { SearchRegex = "string" }

Example:

• Lua: { SearchRegex = "pattern" }
• YAML: SearchRegex: pattern

SearchRegexFromInput

Calls SearchRegex with the input taken from the input buffer. You need to call ExplorePwd or ExplorePwdAsync explicitly. It gets reset automatically when changing directory.

Example:

• Lua: "SearchRegexFromInput"
• YAML: SearchRegexFromInput

SearchRegexUnordered

Like SearchRegex, but doesn't not perform rank based sorting. You need to call ExplorePwd or ExplorePwdAsync explicitly. It gets reset automatically when changing directory.

Type: { SearchRegexUnordered = "string" }

Example:

• Lua: { SearchRegexUnordered = "pattern" }
• YAML: SearchRegexUnordered: pattern

SearchRegexUnorderedFromInput

Calls SearchRegexUnordered with the input taken from the input buffer. You need to call ExplorePwd or ExplorePwdAsync explicitly. It gets reset automatically when changing directory.

Example:

• Lua: "SearchRegexUnorderedFromInput"
• YAML: SearchRegexUnorderedFromInput

ToggleSearchAlgorithm

Toggles between different search algorithms, without changing the input buffer You need to call ExplorePwd or ExplorePwdAsync explicitly.

Example:

• Lua: "ToggleSearchAlgorithm"
• YAML: ToggleSearchAlgorithm

EnableSearchOrder

Enables ranked search without changing the input buffer. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Example:

• Lua: "EnableOrderedSearch"
• YAML: EnableSearchOrder

DisableSearchOrder

Disabled ranked search without changing the input buffer. You need to call ExplorePwd or ExplorePwdAsync explicitly.

Example:

• Lua: "DisableSearchOrder"
• YAML: DisableSearchOrder

ToggleSearchOrder

Toggles ranked search without changing the input buffer.

Example:

• Lua: "ToggleSearchOrder"
• YAML: ToggleSearchOrder

AcceptSearch

Accepts the search by keeping the latest focus while in search mode. Automatically calls ExplorePwd.

Example:

• Lua: "AcceptSearch"
• YAML: AcceptSearch

CancelSearch

Cancels the search by discarding the latest focus and recovering the focus before search. Automatically calls ExplorePwd.

Example:

• Lua: "CancelSearch"
• YAML: CancelSearch

Mouse Operations

EnableMouse

Enable mouse

Example:

• Lua: "EnableMouse"
• YAML: EnableMouse

DisableMouse

Disable mouse

Example:

• Lua: "DisableMouse"
• YAML: DisableMouse

ToggleMouse

Toggle mouse

Example:

• Lua: "ToggleMouse"
• YAML: ToggleMouse

Fifo Operations

StartFifo

Start piping the focused path to the given fifo path

Type: { StartFifo = "string" }

Example:

• Lua: { StartFifo = "/tmp/xplr.fifo }
• YAML: StartFifo: /tmp/xplr.fifo

StopFifo

Close the active fifo and stop piping.

Example:

• Lua: "StopFifo"
• YAML: StopFifo

ToggleFifo

Toggle between {Start|Stop}Fifo

Type: { ToggleFifo = "string" }

Example:

• Lua: { ToggleFifo = "/path/to/fifo" }
• YAML: ToggleFifo: /path/to/fifo

Logging

LogInfo

Log information message.

Type: { LogInfo = "string" }

Example:

• Lua: { LogInfo = "launching satellite" }
• YAML: LogInfo: launching satellite

LogSuccess

Log a success message.

Type: { LogSuccess = "String" }

Example:

• Lua: { LogSuccess = "satellite reached destination" }
• YAML: LogSuccess: satellite reached destination

LogWarning

Log an warning message.

Type: { LogWarning = "string" }

Example:

• Lua: { LogWarning = "satellite is heating" }
• YAML: LogWarning: satellite is heating

LogError

Log an error message.

Type: { LogError = "string" }

Example:

• Lua: { LogError = "satellite crashed" }
• YAML: LogError: satellite crashed

Debugging

Debug

Write the application state to a file, without quitting. Also helpful for debugging.

Type: { Debug = "string" }

Example:

• Lua: { Debug = "/path/to/file" }
• YAML: Debug: /path/to/file

Quit Options

Quit

Example:

• Lua: "Quit"
• YAML: Quit

Quit with returncode zero (success).

PrintPwdAndQuit

Print $PWD and quit.

Example:

• Lua: "PrintPwdAndQuit"
• YAML: PrintPwdAndQuit

PrintFocusPathAndQuit

Print the path under focus and quit. It can be empty string if there's nothing to focus.

Example:

• Lua: "PrintFocusPathAndQuit"
• YAML: PrintFocusPathAndQuit

PrintSelectionAndQuit

Print the selected paths and quit. It can be empty is no path is selected.

Example:

• Lua: "PrintSelectionAndQuit"
• YAML: PrintSelectionAndQuit

PrintResultAndQuit

Print the selected paths if it's not empty, else, print the focused node's path.

Example:

• Lua: "PrintResultAndQuit"
• YAML: PrintResultAndQuit

PrintAppStateAndQuit

Print the state of application in YAML format. Helpful for debugging or generating the default configuration file.

Example:

• Lua: "PrintAppStateAndQuit"
• YAML: PrintAppStateAndQuit

Terminate

Terminate the application with a non-zero return code.

Example:

• Lua: "Terminate"
• YAML: Terminate

Also See:

• Message

Input Operation

Cursor based input operation is a sum type can be one of the following:

• { SetCursor = int }
• { InsertCharacter = str }
• "GoToPreviousCharacter"
• "GoToNextCharacter"
• "GoToPreviousWord"
• "GoToNextWord"
• "GoToStart"
• "GoToEnd"
• "DeletePreviousCharacter"
• "DeleteNextCharacter"
• "DeletePreviousWord"
• "DeleteNextWord"
• "DeleteLine"
• "DeleteTillEnd"

Also See:

• Message
• Full List of Messages

Borders

xplr allows customizing the shape and style of the borders.

Border

A border is a sum type that can be one of the following:

• "Top"
• "Right"
• "Bottom"
• "Left"

Border Type

A border type is a sum type that can be one of the following:

• "Plain"
• "Rounded"
• "Double"
• "Thick"

Border Style

The style of the borders.

Example

xplr.config.general.panel_ui.default.borders = { "Top", "Right", "Bottom", "Left" }
xplr.config.general.panel_ui.default.border_type = "Thick"
xplr.config.general.panel_ui.default.border_style.fg = "Black"
xplr.config.general.panel_ui.default.border_style.bg = "Gray"

Style

A style object contains the following information:

• fg
• bg
• add_modifiers
• sub_modifiers

fg

Type: nullable Color

The foreground color.

bg

Type: nullable Color

The background color.

add_modifiers

Type: nullable list of Modifier

Modifiers to add.

sub_modifiers

Type: nullable list of Modifier

Modifiers to remove.

Color

Color is a sum type that can be one of the following:

• "Reset"
• "Black"
• "Red"
• "Green"
• "Yellow"
• "Blue"
• "Magenta"
• "Cyan"
• "Gray"
• "DarkGray"
• "LightRed"
• "LightGreen"
• "LightYellow"
• "LightBlue"
• "LightMagenta"
• "LightCyan"
• "White"
• { Rgb = { int, int, int } }
• { Indexed = int }

Modifier

Modifier is a sum type that can be one of the following:

• "Bold"
• "Dim"
• "Italic"
• "Underlined"
• "SlowBlink"
• "RapidBlink"
• "Reversed"
• "Hidden"
• "CrossedOut"

Example

xplr.config.general.prompt.style.fg = "Red"
xplr.config.general.prompt.style.bg = { Rgb = { 100, 150, 200 } }
xplr.config.general.prompt.style.add_modifiers = { "Bold", "Italic" }
xplr.config.general.prompt.style.sub_modifiers = { "Hidden" }

Searching

xplr supports searching paths using different algorithm. The search mechanism generally appears between filters and sorters in the Sort & filter panel.

Example:

fzy:foo↓

This line means that the nodes visible on the table are being filtered using the fuzzy matching algorithm on the input foo. The arrow means that ranking based ordering is being applied, i.e. sorters are being ignored.

Node Searcher Applicable

Node Searcher contains the following fields:

• pattern
• recoverable_focus
• algorithm
• unordered

pattern

The patterns used to search.

Type: string

recoverable_focus

Where to focus when search is cancelled.

Type: nullable string

algorithm

Search algorithm to use. Defaults to the value set in xplr.config.general.search.algorithm.

It can be one of the following:

• Fuzzy
• Regex

unordered

Whether to skip ordering the search result by algorithm based ranking. Defaults to the value set in xplr.config.general.search.unordered.

Type: boolean

Example:

local searcher = {
  pattern = "pattern to search",
  recoverable_focus = "/path/to/focus/on/cancel",
  algorithm = "Fuzzy",
  unordered = false,
}

xplr.util.explore({ searcher = searcher })

See xplr.util.explore.

Sorting

xplr supports sorting paths by different properties. The sorting mechanism works like a pipeline, which in visible in the Sort & filter panel.

Example:

size↑ › [i]rel↓ › [c]dir↑ › [c]file↑ › sym↑

This line means that the nodes visible in the table will be first sorted by it's size, then by case insensitive relative path, then by the canonical (symlink resolved) type of the node, and finally by whether or not the node is a symlink.

The arrows denote the order.

Each part of this pipeline is called Node Sorter Applicable.

Node Sorter Applicable

It contains the following information:

• sorter
• reverse

sorter

A sorter is a sum type that can be one of the following:

• "ByRelativePath"
• "ByIRelativePath"
• "ByExtension"
• "ByIsDir"
• "ByIsFile"
• "ByIsSymlink"
• "ByIsBroken"
• "ByIsReadonly"
• "ByMimeEssence"
• "BySize"
• "ByCreated"
• "ByLastModified"
• "ByCanonicalAbsolutePath"
• "ByICanonicalAbsolutePath"
• "ByCanonicalExtension"
• "ByCanonicalIsDir"
• "ByCanonicalIsFile"
• "ByCanonicalIsReadonly"
• "ByCanonicalMimeEssence"
• "ByCanonicalSize"
• "ByCanonicalCreated"
• "ByCanonicalLastModified"
• "BySymlinkAbsolutePath"
• "ByISymlinkAbsolutePath"
• "BySymlinkExtension"
• "BySymlinkIsDir"
• "BySymlinkIsFile"
• "BySymlinkIsReadonly"
• "BySymlinkMimeEssence"
• "BySymlinkSize"
• "BySymlinkCreated"
• "BySymlinkLastModified"

reverse

Type: boolean

It defined the direction of the order.

Example

xplr.config.general.initial_sorting = {
    { sorter = "ByCanonicalIsDir", reverse = true },
    { sorter = "ByIRelativePath", reverse = false },
}

This snippet defines the initial sorting logic to be applied when xplr loads.

Filtering

xplr supports filtering paths by different properties. The filtering mechanism works like a pipeline, which in visible in the Sort & filter panel.

Example:

rel!^. › [i]abs=~abc › [i]rel!~xyz

This line means that the nodes visible on the table will first be filtered by the condition: relative path does not start with ., then by the condition: absolute path contains abc (case insensitive), and finally by the condition: relative path does not contain xyz (case insensitive).

Each part of this pipeline is called Node Filter Applicable.

Node Filter Applicable

It contains the following information:

• filter
• input

filter

A filter is a sum type that can be one of the following:

• "RelativePathIs"
• "RelativePathIsNot"
• "IRelativePathIs"
• "IRelativePathIsNot"
• "RelativePathDoesStartWith"
• "RelativePathDoesNotStartWith"
• "IRelativePathDoesStartWith"
• "IRelativePathDoesNotStartWith"
• "RelativePathDoesContain"
• "RelativePathDoesNotContain"
• "IRelativePathDoesContain"
• "IRelativePathDoesNotContain"
• "RelativePathDoesEndWith"
• "RelativePathDoesNotEndWith"
• "IRelativePathDoesEndWith"
• "IRelativePathDoesNotEndWith"
• "RelativePathDoesMatchRegex"
• "RelativePathDoesNotMatchRegex"
• "IRelativePathDoesMatchRegex"
• "IRelativePathDoesNotMatchRegex"
• "AbsolutePathIs"
• "AbsolutePathIsNot"
• "IAbsolutePathIs"
• "IAbsolutePathIsNot"
• "AbsolutePathDoesStartWith"
• "AbsolutePathDoesNotStartWith"
• "IAbsolutePathDoesStartWith"
• "IAbsolutePathDoesNotStartWith"
• "AbsolutePathDoesContain"
• "AbsolutePathDoesNotContain"
• "IAbsolutePathDoesContain"
• "IAbsolutePathDoesNotContain"
• "AbsolutePathDoesEndWith"
• "AbsolutePathDoesNotEndWith"
• "IAbsolutePathDoesEndWith"
• "IAbsolutePathDoesNotEndWith"
• "AbsolutePathDoesMatchRegex"
• "AbsolutePathDoesNotMatchRegex"
• "IAbsolutePathDoesMatchRegex"
• "IAbsolutePathDoesNotMatchRegex"

input

Type: string

The input for the condition.

Example:

ToggleNodeFilter = {
  filter = "RelativePathDoesNotStartWith",
  input = "."
}

Here, ToggleNodeFilter is a message that adds or removes (toggles) the filter applied.

Column Renderer

A column renderer is a Lua function that receives a special argument and returns a string that will be displayed in each specific field of the files table.

Example: Customizing Table Renderer

xplr.fn.custom.fmt_simple_column = function(m)
  return m.prefix .. m.relative_path .. m.suffix
end

xplr.config.general.table.header.cols = {
  { format = "  path" }
}

xplr.config.general.table.row.cols = {
  { format = "custom.fmt_simple_column" }
}

xplr.config.general.table.col_widths = {
  { Percentage = 100 }
}

-- With this config, you should only see a single column displaying the
-- relative paths.

xplr by default provides the following column renderers:

• xplr.fn.builtin.fmt_general_table_row_cols_0
• xplr.fn.builtin.fmt_general_table_row_cols_1
• xplr.fn.builtin.fmt_general_table_row_cols_2
• xplr.fn.builtin.fmt_general_table_row_cols_3
• xplr.fn.builtin.fmt_general_table_row_cols_4

You can either overwrite these functions, or create new functions in xplr.fn.custom and point to them.

Terminal colors are supported.

Table Renderer Argument

The special argument contains the following fields

• parent
• relative_path
• absolute_path
• extension
• is_symlink
• is_broken
• is_dir
• is_file
• is_readonly
• mime_essence
• size
• human_size
• permissions
• created
• last_modified
• uid
• gid
• canonical
• symlink
• index
• relative_index
• is_before_focus
• is_after_focus
• tree
• prefix
• suffix
• is_selected
• is_focused
• total
• style
• meta

parent

Type: string

The parent path of the node.

relative_path

Type: string

The path relative to the parent, i.e. the file/directory name with extension.

absolute_path

Type: string

The absolute path (without resolving symlinks) of the node.

extension

Type: string

The extension of the node.

is_symlink

Type: boolean

true if the node is a symlink.

is_broken

Type: boolean

true if the node is a broken symlink.

is_dir

Type: boolean

true if the node is a directory.

is_file

Type: boolean

true if the node is a file.

is_readonly

Type: boolean

true if the node is real-only.

mime_essence

Type: string

The mime type of the node. For e.g. text/csv, image/jpeg etc.

size

Type: integer

The size of the exact node. The size of a directory won't be calculated recursively.

human_size

Type: string

Like size but in human readable format.

permissions

Type: Permission

The permissions applied to the node.

created

Type: nullable integer

Creation time in nanosecond since UNIX epoch.

last_modified

Type: nullable integer

Last modification time in nanosecond since UNIX epoch.

uid

Type: integer

User ID of the file owner.

gid

Type: integer

Group ID of the file owner.

canonical

Type: nullable Resolved Node Metadata

If the node is a symlink, it will hold information about the symlink resolved node. Else, it will hold information the actual node. It the symlink is broken, it will be null.

symlink

Type: nullable Resolved Node Metadata

If the node is a symlink and is not broken, it will hold information about the symlink resolved node. However, it will never hold information about the actual node. It will instead be null.

index

Type: integer

Index (starting from 0) of the node.

relative_index

Type: integer

Relative index from the focused node (i.e. 0th node).

is_before_focus

Type: boolean

true if the node is before the focused node.

is_after_focus

Type: boolean

true if the node is after the focused node.

tree

Type: string

The tree component based on the node's index.

prefix

Type: string

The prefix applicable for the node.

suffix

Type: string

The suffix applicable for the node.

is_selected

Type: boolean

true if the node is selected.

is_focused

Type: boolean

true if the node is under focus.

total

Type: integer

The total number of the nodes.

style

Type: Style

The applicable style object for the node.

meta

Type: mapping of string and string

The applicable meta object for the node.

Permission

Permission contains the following fields:

• user_read
• user_write
• user_execute
• group_read
• group_write
• group_execute
• other_read
• other_write
• other_execute
• sticky
• setgid
• setuid

Each field holds a boolean value.

Resolved Node Metadata

It contains the following fields.

• absolute_path
• extension
• is_dir
• is_file
• is_readonly
• mime_essence
• size
• human_size
• created
• last_modified
• uid
• gid

Lua Function Calls

xplr allows you to define lua functions using the xplr.fn.custom Lua API.

These functions can be called using messages like CallLua, CallLuaSilently.

When called the function receives a special argument that contains some useful information. The function can optionally return a list of messages which will be handled by xplr.

Example: Using Lua Function Calls

-- Define the function
xplr.fn.custom.ask_name_and_greet = function(app)
  print("What's your name?")

  local name = io.read()
  local greeting = "Hello " .. name .. "!"
  local message = greeting .. " You are inside " .. app.pwd

  return {
    { LogSuccess = message },
  }
end

-- Map the function to a key (space)
xplr.config.modes.builtin.default.key_bindings.on_key.space = {
  help = "ask name and greet",
  messages = {
    { CallLua = "custom.ask_name_and_greet" }
  }
}

-- Now, when you press "space" in default mode, you will be prompted for your
-- name. Enter your name to receive a nice greeting and to know your location.

Visit the xplr.util API docs for some useful utility / helper functions that you can use in your Lua function calls.

Lua Context

This is a special argument passed to the lua functions when called using the CallLua, CallLuaSilently messages.

It contains the following information:

• version
• pwd
• initial_pwd
• vroot
• focused_node
• directory_buffer
• selection
• mode
• layout
• input_buffer
• pid
• session_path
• explorer_config
• history
• last_modes

version

Type: string

xplr version. Can be used to test compatibility.

pwd

Type: string

The present working directory.

initial_pwd

Type: string

The initial working directory when xplr started.

vroot

Type: nullable string

The current virtual root.

focused_node

Type: nullable Node

The node under focus.

directory_buffer

Type: nullable Directory Buffer

The directory buffer being rendered.

selection

Type: list of selected Nodes

The selected nodes.

mode

Type: Mode

Current mode.

layout

Type: Layout

Current layout.

input_buffer

Type: nullable string

The input buffer.

pid

Type: integer

The xplr session PID.

session_path

Type: string

The session path.

explorer_config

Type: Explorer Config

The configuration for exploring paths.

history

Type: History

last_modes

Type: list of Mode

Last modes, not popped yet.

Node

A node contains the following fields:

• parent
• relative_path
• absolute_path
• extension
• is_symlink
• is_broken
• is_dir
• is_file
• is_readonly
• mime_essence
• size
• human_size
• permissions
• created
• last_modified
• uid
• gid
• canonical
• symlink

parent

Type: string

The parent path of the node.

relative_path

Type: string

The path relative to the parent, i.e. the file/directory name with extension.

absolute_path

Type: string

The absolute path (without resolving symlinks) of the node.

extension

Type: string

The extension of the node.

is_symlink

Type: boolean

true if the node is a symlink.

is_broken

Type: boolean

true if the node is a broken symlink.

is_dir

Type: boolean

true if the node is a directory.

is_file

Type: boolean

true if the node is a file.

is_readonly

Type: boolean

true if the node is real-only.

mime_essence

Type: string

The mime type of the node. For e.g. text/csv, image/jpeg etc.

size

Type: integer

The size of the exact node. The size of a directory won't be calculated recursively.

human_size

Type: string

Like size but in human readable format.

permissions

Type: Permission

The permissions applied to the node.

created

Type: nullable integer

Creation time in nanosecond since UNIX epoch.

last_modified

Type: nullable integer

Last modification time in nanosecond since UNIX epoch.

uid

Type: integer

User ID of the file owner.

gid

Type: integer

Group ID of the file owner.

canonical

Type: nullable Resolved Node Metadata

If the node is a symlink, it will hold information about the symlink resolved node. Else, it will hold information the actual node. It the symlink is broken, it will be null.

symlink

Type: nullable Resolved Node Metadata

If the node is a symlink and is not broken, it will hold information about the symlink resolved node. However, it will never hold information about the actual node. It will instead be null.

Directory Buffer

Directory buffer contains the following fields:

• parent
• nodes
• total
• focus

parent

Type: string

The parent path of the node.

nodes

Type: list of Nodes

A list of visible nodes.

total

Type: int

The count of nodes being rendered.

focus

Type: int

The index of the node under focus. It can be 0 even when there's no node to focus on.

History

History contains the following fields:

• loc
• paths

loc

Type: int

Location of the current path in history.

paths

Type: list of string

Visited paths.

Explorer Config

Explorer config contains the following fields:

• filters
• sorters
• searcher

filters

List of filters to apply.

Type: list of Node Filter Applicable

sorters

Add list or sorters to the pipeline.

Type: list of Node Sorter Applicable

searcher

The searcher to use (if any).

Type: nullable Node Searcher Applicable

Also See:

• xplr.util

xplr.util.version

Get the xplr version details.

Type: function() -> { major: number, minor: number, patch: number }

Example:

xplr.util.version()
-- { major = 0, minor = 0, patch = 0 }

xplr.util.debug

Print the given value to the console, and return it as a string. Useful for debugging.

Type: function( value ) -> string

Example:

xplr.util.debug({ foo = "bar", bar = function() end })
-- {
--   ["bar"] = function: 0x55e5cebdeae0,
--   ["foo"] = "bar",
-- }

xplr.util.clone

Clone/deepcopy a Lua value. Doesn't work with functions.

Type: function( value ) -> value

Example:

local val = { foo = "bar" }
local val_clone = xplr.util.clone(val)
val.foo = "baz"
print(val_clone.foo)
-- "bar"

xplr.util.exists

Check if the given path exists.

Type: function( path:string ) -> boolean

Example:

xplr.util.exists("/foo/bar")
-- true

xplr.util.is_dir

Check if the given path is a directory.

Type: function( path:string ) -> boolean

Example:

xplr.util.is_dir("/foo/bar")
-- true

xplr.util.is_file

Check if the given path is a file.

Type: function( path:string ) -> boolean

Example:

xplr.util.is_file("/foo/bar")
-- true

xplr.util.is_symlink

Check if the given path is a symlink.

Type: function( path:string ) -> boolean

Example:

xplr.util.is_file("/foo/bar")
-- true

xplr.util.is_absolute

Check if the given path is an absolute path.

Type: function( path:string ) -> boolean

Example:

xplr.util.is_absolute("/foo/bar")
-- true

xplr.util.path_split

Split a path into its components.

Type: function( path:string ) -> boolean

Example:

xplr.util.path_split("/foo/bar")
-- { "/", "foo", "bar" }

xplr.util.path_split(".././foo")
-- { "..", "foo" }

xplr.util.node

Get Node information of a given path. Doesn't check if the path exists. Returns nil if the path is "/". Errors out if absolute path can't be obtained.

Type: function( path:string ) -> Node|nil

Example:

xplr.util.node("./bar")
-- { parent = "/pwd", relative_path = "bar", absolute_path = "/pwd/bar", ... }

xplr.util.node("/")
-- nil

xplr.util.node_type

Get the configured Node Type of a given Node.

Type: function( Node, xplr.config.node_types|nil ) -> Node Type

If the second argument is missing, global config xplr.config.node_types will be used.

Example:

xplr.util.node_type(app.focused_node)
-- { style = { fg = "Red", ... }, meta = { icon = "", ... } ... }

xplr.util.node_type(xplr.util.node("/foo/bar"), xplr.config.node_types)
-- { style = { fg = "Red", ... }, meta = { icon = "", ... } ... }

xplr.util.dirname

Get the directory name of a given path.

Type: function( path:string ) -> path:string|nil

Example:

xplr.util.dirname("/foo/bar")
-- "/foo"

xplr.util.basename

Get the base name of a given path.

Type: function( path:string ) -> path:string|nil

Example:

xplr.util.basename("/foo/bar")
-- "bar"

xplr.util.absolute

Get the absolute path of the given path by prepending $PWD. It doesn't check if the path exists.

Type: function( path:string ) -> path:string

Example:

xplr.util.absolute("foo/bar")
-- "/tmp/foo/bar"

xplr.util.relative_to

Get the relative path based on the given base path or current working dir. Will error if it fails to determine a relative path.

Type: function( path:string, options:table|nil ) -> path:string

Options type: { base:string|nil, with_prefix_dots:bookean|nil, without_suffix_dots:boolean|nil }

• If base path is given, the path will be relative to it.
• If with_prefix_dots is true, the path will always start with dots .. / .
• If without_suffix_dots is true, the name will be visible instead of dots .. / .

Example:

xplr.util.relative_to("/present/working/directory")
-- "."

xplr.util.relative_to("/present/working/directory/foo")
-- "foo"

xplr.util.relative_to("/present/working/directory/foo", { with_prefix_dots = true })
-- "./foo"

xplr.util.relative_to("/present/working/directory", { without_suffix_dots = true })
-- "../directory"

xplr.util.relative_to("/present/working")
-- ".."

xplr.util.relative_to("/present/working", { without_suffix_dots = true })
-- "../../working"

xplr.util.relative_to("/present/working/directory", { base = "/present/foo/bar" })
-- "../../working/directory"

xplr.util.shorten

Shorten the given absolute path using the following rules:

• either relative to your home dir if it makes sense
• or relative to the current working directory
• or absolute path if it makes the most sense

Type: Similar to xplr.util.relative_to

Example:

xplr.util.shorten("/home/username/.config")
-- "~/.config"

xplr.util.shorten("/present/working/directory")
-- "."

xplr.util.shorten("/present/working/directory/foo")
-- "foo"

xplr.util.shorten("/present/working/directory/foo", { with_prefix_dots = true })
-- "./foo"

xplr.util.shorten("/present/working/directory", { without_suffix_dots = true })
-- "../directory"

xplr.util.shorten("/present/working/directory", { base = "/present/foo/bar" })
-- "../../working/directory"

xplr.util.shorten("/tmp")
-- "/tmp"

xplr.util.explore

Explore directories with the given explorer config.

Type: function( path:string, ExplorerConfig|nil ) -> { Node, ... }

Example:

xplr.util.explore("/tmp")
-- { { absolute_path = "/tmp/a", ... }, ... }

xplr.util.explore("/tmp", app.explorer_config)
-- { { absolute_path = "/tmp/a", ... }, ... }

xplr.util.shell_execute

Execute shell commands safely.

Type: function( program:string, args:{ string, ... }|nil ) -> { stdout = string, stderr = string, returncode = number|nil }

Example:

xplr.util.shell_execute("pwd")
-- { stdout = "/present/working/directory", stderr = "", returncode = 0 }

xplr.util.shell_execute("bash", {"-c", "xplr --help"})
-- { stdout = "xplr...", stderr = "", returncode = 0 }

xplr.util.shell_quote

Quote commands and paths safely.

Type: function( string ) -> string

Example:

xplr.util.shell_quote("a'b\"c")
-- 'a'"'"'b"c'

xplr.util.shell_escape

Escape commands and paths safely.

Type: function( string ) -> string

Example:

xplr.util.shell_escape("a'b\"c")
-- "\"a'b\\\"c\""

xplr.util.from_json

Load JSON string into Lua value.

Type: function( string ) -> any

Example:

xplr.util.from_json([[{"foo": "bar"}]])
-- { foo = "bar" }

xplr.util.to_json

Dump Lua value into JSON (i.e. also YAML) string.

Type: function( value ) -> string

Example:

xplr.util.to_json({ foo = "bar" })
-- [[{ "foo": "bar" }]]

xplr.util.to_json({ foo = "bar" }, { pretty = true })
-- [[{
--   "foo": "bar"
-- }]]

xplr.util.from_yaml

Load YAML (i.e. also JSON) string into Lua value.

Type: function( string ) -> value

Example:

xplr.util.from_yaml([[{foo: bar}]])
-- { foo = "bar" }

xplr.util.to_yaml

Dump Lua value into YAML string.

Type: function( value ) -> string

Example:

xplr.util.to_yaml({ foo = "bar" })
-- "foo: bar"

xplr.util.lscolor

Get a Style object for the given path based on the LS_COLORS environment variable.

Type: function( path:string ) -> Style

Example:

xplr.util.lscolor("Desktop")
-- { fg = "Red", bg = nil, add_modifiers = {}, sub_modifiers = {} }

xplr.util.paint

Apply style (escape sequence) to string using a given Style object.

Type: function( string, Style|nil ) -> string

Example:

xplr.util.paint("Desktop", { fg = "Red", bg = nil, add_modifiers = {}, sub_modifiers = {} })
-- "\u001b[31mDesktop\u001b[0m"

xplr.util.style_mix

Mix multiple Style objects into one.

Type: function( { Style, Style, ... } ) -> Style

Example:

xplr.util.style_mix({{ fg = "Red" }, { bg = "Blue" }, { add_modifiers = {"Bold"} }})
-- { fg = "Red", bg = "Blue", add_modifiers = { "Bold" }, sub_modifiers = {} }

xplr.util.textwrap

Wrap the given text to fit the specified width. It will try to not split words when possible.

Type: function( string, options:number|table ) -> { string, ...}

Options type: { width = number, initial_indent = string|nil, subsequent_indent = string|nil, break_words = boolean|nil }

Example:

xplr.util.textwrap("this will be cut off", 11)
-- { "this will', 'be cut off" }

xplr.util.textwrap(
  "this will be cut off",
  { width = 12, initial_indent = "", subsequent_indent = "    ", break_words = false }
)
-- { "this will be", "    cut off" }

xplr.util.layout_replace

Find the target layout in the given layout and replace it with the replacement layout, returning a new layout.

Type: function( layout:Layout, target:Layout, replacement:Layout ) -> layout:Layout

Example:

local layout = {
  Horizontal = {
    splits = {
      "Table",  -- Target
      "HelpMenu",
    },
    config = ...,
  }
}

xplr.util.layout_replace(layout, "Table", "Selection")
-- {
--   Horizontal = {
--     splits = {
--       "Selection",  -- Replacement
--       "HelpMenu",
--     },
--     config = ...
--   }
-- }

xplr.util.permissions_rwx

Convert Permission to rwxrwxrwx representation with special bits.

Type: function( Permission ) -> string

Example:

xplr.util.permissions_rwx({ user_read = true })
-- "r--------"

xplr.util.permissions_rwx(app.focused_node.permission)
-- "rwxrwsrwT"

xplr.util.permissions_octal

Convert Permission to octal representation.

Type: function( Permission ) -> { number, number, number, number }

Example:

xplr.util.permissions_octal({ user_read = true })
-- { 0, 4, 0, 0 }

xplr.util.permissions_octal(app.focused_node.permission)
-- { 0, 7, 5, 4 }

Environment Variables and Pipes

Alternative to CallLua, CallLuaSilently messages that call Lua functions, there are Call0, CallSilently0, BashExec0, BashExecSilently0 messages that call shell commands.

Example: Simple file opener using xdg-open and $XPLR_FOCUS_PATH

xplr.config.modes.builtin.default.key_bindings.on_key["X"] = {
  help = "open",
  messages = {
    {
      BashExecSilently0 = [===[
        xdg-open "${XPLR_FOCUS_PATH:?}"
      ]===],
    },
  },
}

However, unlike the Lua functions, these shell commands have to read the useful information and send messages via environment variables and temporary files called "pipe"s. These environment variables and files are only available when a command is being executed.

Example: Using Environment Variables and Pipes

xplr.config.modes.builtin.default.key_bindings.on_key["space"] = {
  help = "ask name and greet",
  messages = {
    {
      BashExec0 = [===[
        echo "What's your name?"

        read name
        greeting="Hello $name!"
        message="$greeting You are inside $PWD"

        "$XPLR" -m 'LogSuccess: %q' "$message"
      ]===]
    }
  }
}

-- Now, when you press "space" in default mode, you will be prompted for your
-- name. Enter your name to receive a nice greeting and to know your location.

Visit the fzf integration tutorial for another example.

To see the environment variables and pipes, invoke the shell by typing :! in default mode and run the following command:

env | grep ^XPLR

You will see something like:

XPLR=xplr
XPLR_FOCUS_INDEX=0
XPLR_MODE=action to
XPLR_PIPE_SELECTION_OUT=/run/user/1000/xplr/session/122278/pipe/selection_out
XPLR_INPUT_BUFFER=
XPLR_PIPE_GLOBAL_HELP_MENU_OUT=/run/user/1000/xplr/session/122278/pipe/global_help_menu_out
XPLR_PID=122278
XPLR_PIPE_MSG_IN=/run/user/1000/xplr/session/122278/pipe/msg_in
XPLR_PIPE_LOGS_OUT=/run/user/1000/xplr/session/122278/pipe/logs_out
XPLR_PIPE_RESULT_OUT=/run/user/1000/xplr/session/122278/pipe/result_out
XPLR_PIPE_HISTORY_OUT=/run/user/1000/xplr/session/122278/pipe/history_out
XPLR_FOCUS_PATH=/home/sayanarijit/Documents/GitHub/xplr/docs/en/book
XPLR_SESSION_PATH=/run/user/1000/xplr/session/122278
XPLR_APP_VERSION=0.14.3
XPLR_PIPE_DIRECTORY_NODES_OUT=/run/user/1000/xplr/session/122278/pipe/directory_nodes_out

The environment variables starting with XPLR_PIPE_ are the temporary files called "pipe"s.

The other variables are single-line variables containing simple information:

• XPLR
• XPLR_APP_VERSION
• XPLR_FOCUS_INDEX
• XPLR_FOCUS_PATH
• XPLR_INPUT_BUFFER
• XPLR_INITIAL_PWD
• XPLR_MODE
• XPLR_PID
• XPLR_SESSION_PATH
• XPLR_VROOT

Environment variables

XPLR

The binary path of xplr command.

XPLR_APP_VERSION

Self-explanatory.

XPLR_FOCUS_INDEX

Contains the index of the currently focused item, as seen in column-renderer/index.

XPLR_FOCUS_PATH

Contains the full path of the currently focused node.

XPLR_INITIAL_PWD

The $PWD then xplr started.

XPLR_INPUT_BUFFER

The line currently in displaying in the xplr input buffer. For e.g. the search input while searching. See Reading Input.

XPLR_MODE

Contains the mode xplr is currently in, see modes.

XPLR_PID

Contains the process ID of the current xplr process.

XPLR_SESSION_PATH

Contains the current session path, like /tmp/runtime-"$USER"/xplr/session/"$XPLR_PID"/, you can find temporary files here, such as pipes.

XPLR_VROOT

Contains the path of current virtual root, is set.

Pipes

Input pipe

Currently there is only one input pipe.

• XPLR_PIPE_MSG_IN

Output pipes

XPLR_PIPE_*_OUT are the output pipes that contain data which cannot be exposed directly via environment variables, like multi-line strings. These pipes can be accessed as plain text files located in $XPLR_SESSION_PATH.

Depending on the message (e.g. Call or Call0), each line will be separated by newline or null character (\n or \0).

• XPLR_PIPE_SELECTION_OUT
• XPLR_PIPE_GLOBAL_HELP_MENU_OUT
• XPLR_PIPE_LOGS_OUT
• XPLR_PIPE_RESULT_OUT
• XPLR_PIPE_HISTORY_OUT
• XPLR_PIPE_DIRECTORY_NODES_OUT

XPLR_PIPE_MSG_IN

Append new messages to this pipe in YAML (or JSON) syntax. These messages will be read and handled by xplr after the command execution.

Depending on the message (e.g. Call or Call0) you need to separate each message using newline or null character (\n or \0).

NOTE: Since version v0.20.0, it's recommended to avoid writing directly to this file, as safely escaping YAML strings is a lot of work. Use xplr -m / xplr --pipe-msg-in to pass messages to xplr in a safer way.

It uses jf syntax to safely convert an YAML template into a valid message.

Example: "$XPLR" -m 'ChangeDirectory: %q' "${HOME:?}"

XPLR_PIPE_SELECTION_OUT

List of selected paths.

XPLR_PIPE_GLOBAL_HELP_MENU_OUT

The full help menu.

XPLR_PIPE_LOGS_OUT

List of logs.

XPLR_PIPE_RESULT_OUT

Result (selected paths if any, else the focused path)

XPLR_PIPE_HISTORY_OUT

List of last visited paths (similar to jump list in vim).

XPLR_PIPE_DIRECTORY_NODES_OUT

List of paths, filtered and sorted as displayed in the files table.

Awesome Hacks

Here's a list of cool xplr hacks, i.e. snippets of code that you can just copy and paste into your configuration or the appropriate file, that are too small or too niche for a full fledge plugin.

Do you have something cool to share?

Edit this file or share them here.

You can try these hacks by writing them to a file, say hack.lua and passing it to xplr with --extra-config or -C.

xplr -C hack.lua

cd on quit

Change directory using xplr.

alias xcd='cd "$(xplr --print-pwd-as-result)"'

Spawn multiple sessions in different tabs (iTerm2)

Creating a new session that starts with iTerm2.

xplr.config.modes.builtin.default.key_bindings.on_key["ctrl-n"] = {
  help = "new session",
  messages = {
    { BashExecSilently = [[
        osascript <<EOF
        tell application "iTerm2"
          tell current window
            create tab with default profile
            tell current session to write text "xplr"
          end tell
        end tell
      ]]
    },
  },
}

Bookmark

Bookmark files using m and fuzzy search bookmarks using backtick.

xplr.config.modes.builtin.default.key_bindings.on_key.m = {
  help = "bookmark",
  messages = {
    {
      BashExecSilently0 = [===[
        PTH="${XPLR_FOCUS_PATH:?}"
        PTH_ESC=$(printf %q "$PTH")
        if echo "${PTH:?}" >> "${XPLR_SESSION_PATH:?}/bookmarks"; then
          "$XPLR" -m 'LogSuccess: %q' "$PTH_ESC added to bookmarks"
        else
          "$XPLR" -m 'LogError: %q' "Failed to bookmark $PTH_ESC"
        fi
      ]===],
    },
  },
}

xplr.config.modes.builtin.default.key_bindings.on_key["`"] = {
  help = "go to bookmark",
  messages = {
    {
      BashExec0 = [===[
        PTH=$(cat "${XPLR_SESSION_PATH:?}/bookmarks" | fzf --no-sort)
        PTH_ESC=$(printf %q "$PTH")
        if [ "$PTH" ]; then
          "$XPLR" -m 'FocusPath: %q' "$PTH"
        fi
      ]===],
    },
  },
}

Persistent, multi-session bookmark

A bookmark mode that allows for a bookmark file to be used throughout multiples sessions. It is set to the environment variable $XPLR_BOOKMARK_FILE. A bookmark can be added, deleted, or jumped to.

-- With `export XPLR_BOOKMARK_FILE="$HOME/bookmarks"`
-- Bookmark: mode binding
xplr.config.modes.builtin.default.key_bindings.on_key["b"] = {
  help = "bookmark mode",
  messages = {
    { SwitchModeCustom = "bookmark" },
  },
}
xplr.config.modes.custom.bookmark = {
  name = "bookmark",
  key_bindings = {
    on_key = {
      m = {
        help = "bookmark dir",
        messages = {
          {
            BashExecSilently0 = [[
              PTH="${XPLR_FOCUS_PATH:?}"
              if [ -d "${PTH}" ]; then
                PTH="${PTH}"
              elif [ -f "${PTH}" ]; then
                PTH=$(dirname "${PTH}")
              fi
              PTH_ESC=$(printf %q "$PTH")
              if echo "${PTH:?}" >> "${XPLR_BOOKMARK_FILE:?}"; then
                "$XPLR" -m 'LogSuccess: %q' "$PTH_ESC added to bookmarks"
              else
                "$XPLR" -m 'LogError: %q' "Failed to bookmark $PTH_ESC"
              fi
            ]],
          },
          "PopMode",
        },
      },
      g = {
        help = "go to bookmark",
        messages = {
          {
            BashExec0 = [===[
              PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort)
              if [ "$PTH" ]; then
                "$XPLR" -m 'FocusPath: %q' "$PTH"
              fi
            ]===],
          },
          "PopMode",
        },
      },
      d = {
        help = "delete bookmark",
        messages = {
          {
            BashExec0 = [[
              PTH=$(cat "${XPLR_BOOKMARK_FILE:?}" | fzf --no-sort)
              sd "$PTH\n" "" "${XPLR_BOOKMARK_FILE:?}"
            ]],
          },
          "PopMode",
        },
      },
      esc = {
        help = "cancel",
        messages = {
          "PopMode",
        },
      },
    },
  },
}

Another bookmark manager type thing, taken from wfxr's zsh plugin.

Another bookmark manager type thing, taken from wfxr's zsh plugin which has colored output with fzf.

xplr.config.modes.builtin.go_to.key_bindings.on_key.b = {
  help = "bookmark jump",
  messages = {
    "PopMode",
    { BashExec0 = [===[
        field='\(\S\+\s*\)'
        esc=$(printf '\033')
        N="${esc}[0m"
        R="${esc}[31m"
        G="${esc}[32m"
        Y="${esc}[33m"
        B="${esc}[34m"
        pattern="s#^${field}${field}${field}${field}#$Y\1$R\2$N\3$B\4$N#"
        PTH=$(sed 's#: # -> #' "$PATHMARKS_FILE"| nl| column -t \
        | gsed "${pattern}" \
        | fzf --ansi \
            --height '40%' \
            --preview="echo {}|sed 's#.*->  ##'| xargs exa --color=always" \
            --preview-window="right:50%" \
        | sed 's#.*->  ##')
        if [ "$PTH" ]; then
          "$XPLR" -m 'ChangeDirectory: %q' "$PTH"
        fi
      ]===]
    },
  }
}

Fuzzy search history

Fuzzy search the last visited directories.

xplr.config.modes.builtin.go_to.key_bindings.on_key.h = {
  help = "history",
  messages = {
    "PopMode",
    {
      BashExec0 = [===[
        PTH=$(cat "${XPLR_PIPE_HISTORY_OUT:?}" | sort -z -u | fzf --read0)
        if [ "$PTH" ]; then
          "$XPLR" -m 'ChangeDirectory: %q' "$PTH"
        fi
      ]===],
    },
  },
}

Batch rename

Batch rename the selected or visible files and directories in $PWD.

xplr.config.modes.builtin.default.key_bindings.on_key.R = {
  help = "batch rename",
  messages = {
    {
      BashExec = [===[
       SELECTION=$(cat "${XPLR_PIPE_SELECTION_OUT:?}")
       NODES=${SELECTION:-$(cat "${XPLR_PIPE_DIRECTORY_NODES_OUT:?}")}
       if [ "$NODES" ]; then
         echo -e "$NODES" | renamer
         "$XPLR" -m ExplorePwdAsync
       fi
     ]===],
    },
  },
}

Serve $PWD

Serve $PWD using a static web server via LAN.

xplr.config.modes.builtin.default.key_bindings.on_key.S = {
  help = "serve $PWD",
  messages = {
    {
      BashExec0 = [===[
        IP=$(ip addr | grep -w inet | cut -d/ -f1 | grep -Eo '[0-9]{1,3}\.[0-9]{      1,3}\.[0-9]{1,3}\.[0-9]{1,3}' | fzf --prompt 'Select IP > ')
        echo "IP: ${IP:?}"
        read -p "Port (default 5000): " PORT
        echo
        sfz --all --cors --no-ignore --bind ${IP:?} --port ${PORT:-5000} . &
        sleep 1 && read -p '[press enter to exit]'
        kill -9 %1
      ]===],
    },
  },
}

Image viewer (imv)

Preview images using imv.

xplr.config.modes.builtin.default.key_bindings.on_key.P = {
  help = "preview",
  messages = {
    {
      BashExecSilently0 = [===[
        FIFO_PATH="/tmp/xplr.fifo"

        if [ -e "$FIFO_PATH" ]; then
          "$XPLR" -m StopFifo
          rm -f -- "$FIFO_PATH"
        else
          mkfifo "$FIFO_PATH"
          "$HOME/.local/bin/imv-open.sh" "$FIFO_PATH" "$XPLR_FOCUS_PATH" &
          "$XPLR" -m 'StartFifo: %q' "$FIFO_PATH"
        fi
      ]===],
    },
  },
}

#!/usr/bin/env bash

FIFO_PATH="$1"
IMAGE="$2"
MAINWINDOW="$(xdotool getactivewindow)"
IMV_PID="$(pgrep imv)"

if [ ! "$IMV_PID" ]; then
  imv "$IMAGE" &
  IMV_PID=$!
fi

sleep 0.5

xdotool windowactivate "$MAINWINDOW"

while read -r path; do
  imv-msg "$IMV_PID" close all
  imv-msg "$IMV_PID" open "$path"
done < "$FIFO_PATH"

imv-msg "$IMV_PID" quit
[ -e "$FIFO_PATH" ] && rm -f -- "$FIFO_PATH"

Text preview pane

Preview text files in a native xplr pane (should be fast enough).

local function stat(node)
  return xplr.util.to_yaml(xplr.util.node(node.absolute_path))
end

local function read(path, height)
  local p = io.open(path)

  if p == nil then
    return nil
  end

  local i = 0
  local res = ""
  for line in p:lines() do
    if line:match("[^ -~\n\t]") then
      p:close()
      return
    end

    res = res .. line .. "\n"
    if i == height then
      break
    end
    i = i + 1
  end
  p:close()

  return res
end

xplr.fn.custom.preview_pane = {}
xplr.fn.custom.preview_pane.render = function(ctx)
  local title = nil
  local body = ""
  local n = ctx.app.focused_node
  if n and n.canonical then
    n = n.canonical
  end

  if n then
    title = { format = n.absolute_path, style = xplr.util.lscolor(n.absolute_path) }
    if n.is_file then
      body = read(n.absolute_path, ctx.layout_size.height) or stat(n)
    else
      body = stat(n)
    end
  end

  return { CustomParagraph = { ui = { title = title }, body = body } }
end

local preview_pane = { Dynamic = "custom.preview_pane.render" }
local split_preview = {
  Horizontal = {
    config = {
      constraints = {
        { Percentage = 60 },
        { Percentage = 40 },
      },
    },
    splits = {
      "Table",
      preview_pane,
    },
  },
}

xplr.config.layouts.builtin.default =
    xplr.util.layout_replace(xplr.config.layouts.builtin.default, "Table", split_preview)

Tere Navigation

Navigate using the tere file explorer (defaults to type-to-nav system).

xplr.config.modes.builtin.default.key_bindings.on_key.T = {
  help = "tere nav",
  messages = {
    { BashExec0 = [["$XPLR" -m 'ChangeDirectory: %q' "$(tere)"]] },
  },
}

Also See:

• Awesome Plugins
• Awesome Integrations

Plugin

xplr supports pluggable Lua modules that can be used to easily configure or extend xplr UI and functionalities.

• Installing Plugins
• Writing Plugins
• Awesome Plugins

Installing Plugins

One way to install plugins is to use a plugin manager like dtomvan/xpm.xplr.

But you can also install and manage plugins manually.

Install Manually

• Add the following line in ~/.config/xplr/init.lua

  local home = os.getenv("HOME")
  package.path = home
  .. "/.config/xplr/plugins/?/init.lua;"
  .. home
  .. "/.config/xplr/plugins/?.lua;"
  .. package.path
  

• Clone the plugin

  mkdir -p ~/.config/xplr/plugins
  
  git clone https://github.com/sayanarijit/material-landscape2.xplr ~/.config/xplr/plugins/material-landscape2
  

• Require the module in ~/.config/xplr/init.lua

  require("material-landscape2").setup()
  
  -- The setup arguments might differ for different plugins.
  -- Visit the project README for setup instructions.
  

Luarocks Support

Some plugins may require luarocks to work.

Setup luarocks with the following steps:

• Install luarocks (via your package managers or follow the official guide).

• Add eval "$(luarocks path --lua-version 5.1)" in your .bashrc or .zshrc.

• Add the following lines in ~/.config/xplr/init.lua

  package.path = os.getenv("LUA_PATH") .. ";" .. package.path
  package.cpath = os.getenv("LUA_CPATH") .. ";" .. package.cpath
  

  Now you can install packages using luarocks. Be sure to append --lua-version.

Example:

luarocks install luafilesystem --local --lua-version 5.1

Writing Plugins

Anyone who can write Lua code, can write xplr plugins.

Just follow the instructions and best practices:

Naming

xplr plugins are named using hiphen (-) separated words that may also include integers. They will be plugged using the require() function in Lua.

Structure

A minimal plugin should confirm to the following structure:

.
├── README.md
└── init.lua

You can also use this template.

README.md

This is where you document what the plugin does, how to use it, etc.

init.lua

This file is executed to load the plugin. It should expose a setup() function, which will be used by the users to setup the plugin.

Example:

local function setup(args)
  local xplr = xplr
  -- do stuff with xplr
end

return { setup = setup }

Publishing

When publishing plugins on GitHub or other repositories, it's a best practice to append .xplr to the name to make them distinguishable. Similar to the *.nvim naming convention for Neovim plugins.

Finally, after publishing, don't hesitate to let us know.

Best practices

• Try not to execute a lot of commands at startup, it may make xplr slow to start.
• When executing commands, prefer Call0 over Call, BashExec0 over BashExec and so on. File names may contain newline characters (e.g. foo$'\n'bar).
• File names may also contain quotes. Avoid writing directly to $XPLR_PIPE_MSG_IN. Use xplr -m / xplr --pipe-msg-in instead.
• Check for empty variables using the syntax ${FOO:?} or use a default value ${FOO:-defaultvalue}.

Examples

Visit Awesome Plugins for xplr plugin examples.

Also See

• Tip: A list of hacks yet to make it as Lua plugins
• Tip: Some UI and theming tips
• Tutorial: Adding a New Mode
• Example: Using Environment Variables and Pipes
• Example: Using Lua Function Calls
• Example: Defining Custom Layout
• Example: Customizing Table Renderer
• Example: Render a custom dynamic table
• Example: Implementing a directory visit counter

Awesome Plugins

Here's a list of awesome xplr plugins that you might want to check out. If none of the following plugins work for you, it's very easy to write your own.

Extension

• sayanarijit/command-mode.xplr The missing command mode for xplr.
• igorepst/context-switch.xplr Context switch plugin for xplr.
• sayanarijit/dual-pane.xplr Implements support for dual-pane navigation into xplr.
• sayanarijit/map.xplr Visually inspect and interactively execute batch commands using xplr.
• sayanarijit/offline-docs.xplr Fetch the appropriate version of xplr docs and browse offline.
• sayanarijit/regex-search.xplr Bring back the regex based search in xplr.
• sayanarijit/registers.xplr Use multiple registers to store the selected paths.
• sayanarijit/tree-view.xplr Hackable tree view for xplr
• sayanarijit/tri-pane.xplr xplr plugin that implements ranger-like three pane layout.
• sayanarijit/type-to-nav.xplr Inspired by nnn's type-to-nav mode for xplr, with some tweaks.
• dtomvan/term.xplr Terminal integration for xplr.
• sayanarijit/wl-clipboard.xplr Copy and paste with system clipboard using wl-clipboard
• dtomvan/xpm.xplr The XPLR Plugin Manager.
• emsquid/style.xplr Helper plugin that allows you to integrate xplr's Style anywhere.

Integration

• sayanarijit/alacritty.xplr Alacritty integration for xplr.
• sayanarijit/dragon.xplr Drag and drop files using dragon.
• sayanarijit/dua-cli.xplr Get the disk usage using dua-cli with selection support.
• sayanarijit/fzf.xplr Fuzzy search using fzf to focus on a file or enter.
• sayanarijit/find.xplr An interactive finder plugin to complement map.xplr.
• Junker/nuke.xplr Open files in apps by file type or mime.
• sayanarijit/nvim-ctrl.xplr Send files to running Neovim sessions using nvim-ctrl.
• dtomvan/ouch.xplr This plugin uses ouch to compress and decompress files.
• dtomvan/paste-rs.xplr Use this plugin to paste your files to paste.rs, and open/delete them later using fzf.
• sayanarijit/preview-tabbed.xplr Preview paths using suckless tabbed and nnn preview-tabbed.
• sayanarijit/qrcp.xplr Send and receive files via QR code using qrcp.
• sayanarijit/scp.xplr Integrate xplr with scp.
• sayanarijit/trash-cli.xplr Trash files and directories using trash-cli.
• sayanarijit/xclip.xplr Copy and paste with system clipboard using xclip.
• sayanarijit/zoxide.xplr Change directory using the zoxide database.

Theme

• sayanarijit/material-landscape.xplr Material Landscape
• sayanarijit/material-landscape2.xplr Material Landscape 2
• sayanarijit/zentable.xplr A clean, distraction free xplr table UI
• dy-sh/dysh-style.xplr Complements xplr theme with icons and highlighting.
• prncss-xyz/icons.xplr An icon theme for xplr.
• dtomvan/extra-icons.xplr Adds more icons to icons.xplr, compatible with zentable.xplr.
• hartan/web-devicons.xplr Adds nvim-web-devicons to xplr with optional coloring
• duganchen/one-table-column.xplr Moves file stats to a status bar.
• dy-sh/get-rid-of-index.xplr Removes the index column.

Also See:

• Awesome Hacks
• Awesome Integrations

Integration

xplr is designed to integrate well with other tools and commands. It can be used as a file picker or a pluggable file manager.

• Awesome Integrations

Awesome Integrations

Here's a list of awesome xplr integrations that you might want to check out.

If none of the following integrations work for you, you can create your own and let us know.

Editor

• fm-nvim Neovim plugin that lets you use your favorite terminal file managers from within Neovim.
• vim-floaterm xplr integrated in vim-floaterm (Neo)vim plugin.
• xplr.vim Pick files in Vim using xplr.

Github

• gh-xplr Explore GitHub repos using xplr via GitHub CLI.

Shell

• powerlevel10k Powerlevel10k prompt for xplr shell.

Security Tools

• gpg-tui Import GPG certificates using xplr.

Also See:

• Awesome Hacks
• Awesome Plugins

Alternatives

These are the alternative TUI/CLI file managers/explorers you might want to check out (in no particular order).

• nnn
• vifm
• ranger
• lf
• joshuto
• fff
• mc
• broot
• hunter
• noice
• clifm
• clifm (non curses)
• felix
• yazi

add more

Upgrade Guide

When you upgrade xplr, you might see an error like this

Incompatible script version in: /home/sayanarijit/.config/xplr/init.lua. The script version is: 0.9.0, the required version is: 0.10.1. Visit https://github.com/sayanarijit/xplr/wiki/Upgrade-Guide

All you need to do is follow the instructions starting from your config version, all the way to the required version.

Instructions

v0.20.2 -> v0.21.9

• Some plugins might stop rendering colors. Wait for them to update.
• Rename xplr.config.general.sort_and_filter_ui.search_identifier to xplr.config.general.sort_and_filter_ui.search_identifiers.
• Resolved Node API will not contain the permissions field anymore. Use the utility function xplr.util.node to get its permissions.
• Layout CustomContent has been undocumented. It will stay for compatibility, but you should prefer using the following new layouts, because they support custom title:
  • Static
  • Dynamic
• Use the new messages for improved search operations:
  • Search
  • SearchFromInput
  • SearchFuzzyUnordered
  • SearchFuzzyUnorderedFromInput
  • SearchRegex
  • SearchRegexFromInput
  • SearchRegexUnordered
  • SearchRegexUnorderedFromInput
  • ToggleSearchAlgorithm
  • EnableSearchOrder
  • DisableSearchOrder
  • ToggleSearchOrder
• Use skim's search syntax to customize the search.
• Set your preferred search algorithm and ordering: xplr.config.general.search.algorithm = "Fuzzy" -- or "Regex". xplr.config.general.search.unordered = false -- or true
• You need to clear the selection list manually after performing batch operation like copy, softlink creation etc.
• Use the following new key bindings:
  • :sl to list selection in a $PAGER.
  • :ss to create softlink of the selected items.
  • :sh to create hardlink of the selected items.
  • :se to edit selection list in your $EDITOR.
  • Better conflict handling: prompt for action.
• Navigate between the selected paths using the following messages:
  • FocusPreviousSelection (ctrl-p)
  • FocusNextSelection (ctrl-n)
• Use LS_COLORS environment variable, along with the following utility
• functions for applying better styling/theaming.
  • xplr.util.lscolor
  • xplr.util.paint
  • xplr.util.textwrap
  • xplr.util.style_mix
• Use new the fields in Column Renderer Argument:
  • style
  • permissions
• Use the following config to specify how the paths in selection list should be rendered:
  • xplr.config.general.selection.item.format
  • xplr.config.general.selection.item.style
• Use the following utility functions to work with the file permissions:
  • xplr.util.permissions_rwx
  • xplr.util.permissions_octal
• Type :p to edit file permissions interactively.
• Also check out the following utility functions:
  • xplr.util.layout_replace
  • xplr.util.relative_to
  • xplr.util.shorthand
  • xplr.util.clone
  • xplr.util.exists
  • xplr.util.is_dir
  • xplr.util.is_file
  • xplr.util.is_symlink
  • xplr.util.is_absolute
  • xplr.util.path_split
  • xplr.util.node
  • xplr.util.node_type
  • xplr.util.shell_escape
• Executables will me marked with the mime type: application/x-executable.
• macOS legacy coreutils will be generally supported, but please update it.
• Since v0.21.2 you can use the on_selection_change hook.
• Since v0.21.4 you can use function keys upto F24 and the following new messages:
  • NextVisitedDeepBranch (bound to ) key)
  • PreviousVisitedDeepBranch (bound to ( key)
• Since v0.21.6:
  • You can use c and m keys in default mode to quickly copy and move focused or selected files, without having to change directory.
  • Use xplr.util.debug() to debug lua values.
• Since v0.21.8:
  • Scroll behavior will default to vim-like continuous scrolling. You can set xplr.config.general.paginated_scrolling = true to revert back to the paginated scrolling.
  • Set xplr.config.general.scroll_padding to customize the scroll padding.
  • The calculated scrolltop value will be passed as part of the Content Rendeder Argument in Dynamic layout renderer functions.

Thanks to @noahmayr for contributing to a major part of this release.

v0.19.4 -> v0.20.2

• BREAKING: xplr shell (:!) will default to null (\0) delimited pipes, as opposed to newline (\n) delimited ones (i.e. will use Call0 instead of Call).
• Use new messages for safer file path handling (\0 delimited):
  • Call0
  • CallSilently0
  • BashExec0
  • BashExecSilently0
• Use new sub-commands for safer message passing:
  • -m FORMAT [ARGUMENT]... / --pipe-msg-in FORMAT [ARGUMENT]...
  • -M FORMAT [ARGUMENT]... / --print-msg-in FORMAT [ARGUMENT]... Where FORMAT is a YAML string that may contain %s, %q and %% placeholders and ARGUMENT is the value per placeholder. See init.lua.
• Following hooks can be defined in the config files using an optional return { on_* = { list, of, messages }, ... } statement at the end.
  • on_load
  • on_focus_change
  • on_directory_change
  • on_mode_switch (since v0.20.2)
  • on_layout_switch (since v0.20.2)
• Use --vroot to isolate navigation of an xplr session inside a specific directory. Interaction still requires passing full path, and shell, lua functions etc still can access paths outside vroot.
• Use the following messages to switch vroot at runtime, or the use key bindings available in the new builtin mode "vroot" (mapped to : v).
  • SetVroot
  • UnsetVroot
  • ToggleVroot
  • ResetVroot
• Use $XPLR_INITIAL_PWD and Lua equivalent to implement workspace like features without using virtual root. Use keys gi to go to the initial working directory from anywhere.
• Use the convenient xplr.util utility functions in your Lua function calls. See xplr.util API docs.

v0.18.0 -> v0.19.4

• BREAKING: The builtin modes cannot be accessed using space separated names anymore. Use underscore separated mode names. For e.g. SwitchModeBuiltin: create file becomes SwitchModeBuiltin: create_file and so on. Kindly go through your config, find and update them, or copy from the latest init.lua.
• Now you can use xplr.config.general.global_key_bindings to define a set of key bindings that are available by default in every mode. e.g. esc and ctrl-c, and remove boilerplate code from your config.
• You can use the new builtin mode go_to_path which can be used for typing or pasting paths to enter into or to focus on. Type g p to enter this mode.
• Now you can use basic tab completion in the go_to_path, create_file, create_directory, rename and duplicate_as modes.
• Use the builtin function xplr.fn.builtin.try_complete_path to add easy tab completion support into your own configuration.
• Now you can open OSC 7 compatible terminals into the xplr's current working directory by spawning new terminal sessions via the terminal supported key bindings.
• Use NO_COLOR environment variable to disable OSC 7 compliance along with colors.
• If you have fully copied the default init.lua locally, you might want to go through the latest improvements in init.lua. Specifically the search, filter and sort modes. Also, search for SetInputPrompt and the tab key bindings.
• Since version 0.19.1, you can access uid and gid of the file owner in the Lua API.
• The input buffer will support more readline-like keys. Also, added "DeleteTillEnd" as another cursor based "InputOperation" option.
• Fixed applying regex based filters via the CLI and $XPLR_PIPE_MSG_IN pipe.
• You can use the prompt field to define input prompt for each mode, instead of using the SetInputPrompt message.
• Since version v0.19.4, the native search will default to skim-v2 based fuzzy matching. esc while in search mode will recover the initial focus. People who prefer the regex based search, can use the regex-search.xplr plugin. The following messages will be available for search based operations:
  • SearchFuzzy
  • SearchFuzzyFromInput
  • AcceptSearch
  • CancelSearch
• Since version v0.19.4, quick scrolling operations are supported using the following messages and keys:
  • ScrollUp -------- page-up
  • ScrollDown ------ page-down
  • ScrollUpHalf ---- {
  • ScrollDownHalf -- }

v0.17.6 -> v0.18.0

• Key binding f r and f R will now filter using regex.
• Key binding f backspace will now remove the last filter.
• Search mode now defaults to regex search.
• Node metadata in the Lua API will contain two new fields:
  • created
  • last_modified
• The last column in the files table now displays the last modification time.
• You can now use --read0, --write0 and -0/--null to read and/or print null character delimited paths.
• You can now the following regex filters:
  • RelativePathDoesMatchRegex
  • RelativePathDoesNotMatchRegex
  • IRelativePathDoesMatchRegex
  • IRelativePathDoesNotMatchRegex
  • AbsolutePathDoesMatchRegex
  • AbsolutePathDoesNotMatchRegex
  • IAbsolutePathDoesMatchRegex
  • IAbsolutePathDoesNotMatchRegex
• You can use a new SetInputPrompt to set the input prompt dynamically.
• You can now use the following timestamp based sorters:
  • "ByCreated"
  • "ByLastModified"
  • "ByCanonicalCreated"
  • "ByCanonicalLastModified"
  • "BySymlinkCreated"
  • "BySymlinkLastModified"

v0.16.4 -> v0.17.6

• Deprecated app.directory_buffer, app.history, and app.last_modes in the custom dynamic layout renderer context. As of now, there's no way to access these fields in dynamic layouts. While app.history and app.last_modes can be re-added upon request (with justification), app.directory_buffer has been deprecated for good. However, there's no change in the CallLua* context.
• Set xplr.config.general.hide_remaps_in_help_menu to true to hide the remaps in help menu.
• None will be serialized to nil in Lua.
• LuaEval can now return a function that will be called with the Lua Context argument. Refer to the Full List of Messages doc for example.
• From version v0.17.1, set xplr.config.general.disable_debug_error_mode to true to disable switching to the "debug error" mode when startup errors occur.
• From version v0.17.2, you can use CLI argument --print-pwd-as-result for cd on quit, and key binding ctrl-d to duplicate a path in the same directory with a different name.
• Since version v0.17.3, you can use border_type, border_style to customize borders, and enforce_bounded_index_navigation to customize up/down navigation behavior when focus is on the top or bottom node.

v0.15.2 -> v0.16.4

• Deprecated config.general.cursor. The default terminal cursor will be used for the time being.
• Opening xplr inside a symlink will not resolve the path.
• You can now replace most boilerplate configuration handling keys to send BufferInputFromKey, RemoveInputBufferLastCharacter, RemoveInputBufferLastWord, SetInputBuffer = "" etc. messages with a single UpdateInputBufferFromKey message.
• You can now pass multiple paths as command-line arguments or via stdin to select paths, e.g. xplr -- $PWD /path/to/select/1 /path/to/select/2.
• Pass --force-focus to focus on the first path even if it's a directory, e.g. xplr . --force-focus.
• Use new messages LuaEval and LuaEvalSilently to run Lua code without needing to define a function. However, the app context won't be available.
• You can now use new key handlers in the config:
  • on_alphanumeric
  • on_character
  • on_navigation
  • on_function

v0.14.7 -> v0.15.2

• Deprecated config field from CallLua argument. Use the globally available xplr.config instead.
• xplr.config.general.disable_recover_mode has been deprecated. Use xplr.config.general.enable_recover_mode instead.
• Use xplr.config.general.focus_selection_ui to highlight selected files under focus differently than files under focus that are not selected.
• Use PopModeKeepingInputBuffer, and SwitchMode alternatives to switching to different modes without resetting the input buffer.
• Use the new CustomContent layout option to render custom content.
• Use the new layout field in a mode to define custom layout for a specific mode.
• Library users please refer to the latest API docs and examples.

v0.13.7 -> v0.14.7

• macOS users need to place their config file (init.lua) in $HOME/.config/xplr/ or /etc/xplr/.
• Library users please refer to the latest API docs.
• Check out the new messages: {Start|Stop|Toggle}Fifo. These enable support for FIFO based file previews.
• You can disable the recover mode using config.general.disable_recover_mode = true.
• Try running xplr --help. Yes, CLI has been implemented.
• Since version v0.14.3, StartFifo and ToggleFifo will write to the FIFO path when called. So, there's no need to pipe the focus path explicitly.
• Since version v0.14.3, general config xplr.config.start_fifo is available which can be set to a file path to start a fifo when xplr starts.
• Since version v0.14.4, $XPLR_SESSION_PATH can be used to dump session related data.
• Since version v0.14.6, the -C or --extra-config CLI argument is available.

v0.12.1 -> v0.13.7

• Lua functions called using CallLua and CallLuaSilently messages will receive CallLuaArg object as the function argument (instead of the App object).
• Each node_types config will inherit defaults from matching less specific node_types config and overwrite them.
• Since version v0.13.2, you don't need to use/send Refresh anymore. It will be auto-handled by xplr.

v0.11.1 -> v0.12.1

• xplr.config.node_types.mime_essence has split into type and subtype. Hence, instead of xplr.config.node_types.mime_essence["text/plain"] = .. use xplr.config.node_types.mime_essence["text"] = { plain = .. }.
• You can also define xplr.config.node_types.mime_essence["text"]["*"] that will match all text types (text/*).

v0.10.2 -> v0.11.1

• remaps: has been removed to avoid confusion. Use lua assignments instead. For e.g.

  xplr.config.modes.builtin.default.key_bindings.on_key["v"] = xplr.config.modes.builtin.default.key_bindings.on_key.space
  

v0.9.1 -> v0.10.2

• config.yml has been fully replaced with init.lua. If you have a lot of customization in your config.yml, xplr-yml2lua can help you with migrating it to init.lua.
• Handlebars templates has been replaced with Lua functions. You can either remove the customizations or overwrite the functions accordingly.
• Added new messages CallLua and CallLuaSilently to call lua functions. The app state will be passed as input to the functions, and the returned messages will be handled by xplr. CallLua and CallLuaSilently are more flexible (and probably faster) alternatives to Call, CallSilently, BashExec and BashExecSilently. e.g.

v0.9.0 -> v0.9.1

• You can now set remaps: {key: null} to un-map a key.
• gx will open the item under focus.
• New key map :sx will open the selected items.

v0.8.0 -> v0.9.0

Your previous config should mostly work fine. However, in case you are using SwitchMode heavily in your custom config, follow along.

• Introduced new message PopMode. You might want to use this message instead of SwitchMode* when returning back to the previous mode.
• After using (the group of) PopMode and SwitchMode* messages, you are now required to Refresh manually to avoid the UI lag.
• Pressing any invalid key will now lead you to the recover mode and will protect you from typing further invalid keys. Press esc to escape the recover mode.
• Introduced new message LogWarning, similar to other Log* messages.
• Creating files and directories has been optimized for batch creation.

v0.7.2 -> v0.8.0

If you have made changes to the config file,

• Replace message Explore with ExplorePwd or ExplorePwdAsync or probably ExploreParentsAsync.
• Pipe $XPLR_PIPE_FOCUS_OUT has been removed. Use $XPLR_FOCUS_PATH env var instead.
• You might want to review your path escaping logics. For e.g. use echo FocusPath: "'"$PWD"'" >> $PIPE instead of echo "FocusPath: $PWD" >> $PIPE.

v0.7.0 -> v0.7.2

• Just update the version in your config file.
• For version >= v0.7.1, you might want to free up or remap the tab key in search mode to enable easy selection during search.

v0.6.0 -> v0.7.0

If you haven't made any changes in the config file, you should be fine just updating the version number. Else,

• You can make the Table: ..., InputAndLogs: ... layout values null and define the common properties in the general.panel_ui instead.

v0.5.13 -> v0.6.0

If you haven't made any changes in the config file, you should be fine just updating the version number. Else,

• Rename add_modifier: {bits: 1} to add_modifiers: [Bold], sub_modifier: {bits: 1} to sub_modifiers: [Bold] and so on.
• Rename percentage: 10 to Percentage: 10, ratio: 1 to Ratio: 1 and so on.
• You might want to free up or remap the ctrl-w key binding in default mode to enable layout switching.

Optionally, checkout this new theme to learn more about what's new.

v0.5.0 -> v0.5.13

• Just update the version in your config file.
• For versions >= v0.5.8, you can set $OPENER env var to declare a global GUI file opener (to open files using keys gx).
• You might also want to update other mappings to handle files with names starting with - (hiphen). For example, instead of rm ${filename} use rm -- ${filename}. Same goes for cp, mv, cat, touch etc.
• For version >= v0.5.13, you might want to use the more specific SwitchModeBuiltin and SwitchModeCustom messages instead of the general SwitchMode message.

v0.4.3 -> v0.5.0

If you haven't have any changes in the config file, you should be fine just updating the version number.

Else do the following

• Replace {RelativePathIs, case_sensitive: true} with RelativePathIs.
• Replace {RelativePathIs, case_sensitive: false} with IRelativePathIs.
• Do the same with other filters you are using.
• You might want to update your backspace handling to use the RemoveInputBufferLastCharacter message.
• You might want to free-up f, s, ctrl-r and ctrl-u key bindings in the default mode, or remap them.
• You might want to use the new UI variables.
• Update your config version to v0.5.0.

v0.4.2 -> v0.4.3

If you have customized general.table.row.cols, you might want to update it to use the new variables with better symlink support.

v0.4.1 -> v0.4.2

In case you have mapped the keys q, ctrl-i and ctrl-o, you may want to revisit the default mode key bindings and remap accordingly to use the new functionalities.

v0.3.13 -> v0.4.1

A lot has changed (apologies). But I promise from now on, upgrading will be much less painful (thanks to @maximbaz's valuable inputs and code reviews).

So, to start with the upgrade, let's remove everything from your config file except the version field and your custom modifications. If version is the only thing remaining, update it to v0.4.1 and you are done.

Else, do the following

• Rename general.focused_ui to general.focus_ui (see here).
• Rename filetypes to node_types. (see here)
• Rename custom field to meta. (see here)
• Move icon to meta.icon. (see here)
• Rename normal_ui to default_ui. (see here)
• Split modes into modes.builtin and modes.custom (see here). Migrate your custom modes to modes.custom. And copy only the changes in the in-built modes in modes.builtin.
• Finally, update the version to v0.4.1.

v0.3.8 -> v0.3.13

Your current config should work fine. However, you might want to replace some Call and BashExec messages with CallSilently and BashExecSilently to remove the flickering of the screen.

If you haven't made any changes to the configuration, you can delete and regenerate it.

Else, do the following

• Check the new default config by temporarily removing your current config (with backup) and dumping the new config.
• Search for Call and BashExec in the new config.
• Compare and probably replace the associated actions in your current config

v0.3.0 -> v0.3.8

Your current config should work fine. However, you might want to replace some ResetNodeFilters messages with RemoveNodeFilter and RemoveNodeFilterFromInput to get a better search and filter experience.

If you haven't made any changes to the configuration, you can delete and regenerate it.

Else, do the following

• Check the new default config by temporarily removing your current config (with backup) and dumping the new config.
• Search for RemoveNodeFilterFromInput in the new config.
• Compare and probably replace the associated actions in your current config.

v0.2.14 -> v0.3.0

If you haven't made any changes to the configuration, you can delete and regenerate it.

Else do the following:

• $XPLR_APP_YAML has been removed. You can use Debug to export the app state.
• $XPLR_RESULT has been ported to file $XPLR_PIPE_RESULT_OUT. Use cat instead of echo, < instead of <<< etc.
• $XPLR_GLOBAL_HELP_MENU has been ported to file $XPLR_PIPE_GLOBAL_HELP_MENU_OUT. Use cat instead of echo, < instead of <<< etc.
• $XPLR_DIRECTORY_NODES has been ported to file $XPLR_PIPE_DIRECTORY_NODES_OUT. Use cat instead of echo, < instead of <<< etc.
• $XPLR_LOGS has been ported to file $XPLR_PIPE_LOGS_OUT. Use cat instead of echo, < instead of <<< etc.
• $XPLR_PIPE_RESULT has been ported to file $XPLR_PIPE_RESULT_OUT. Use cat instead of echo, < instead of <<< etc.
• Finally, update the version in your config file.