.TH YAZI-CONFIG 1
.SH NAME
yazi-config
.SH DESCRIPTION
.B
Configuration options for yazi terminal file manager.
There are three configuration files for Yazi:
.IP \(bu 2
.I "yazi.toml"
: General Configuration.
.IP \(bu 2
.I "keymap.toml"
: Keybindings Configuration.
.IP \(bu 2
.I "theme.toml"
: Color scheme Configuration.
.PP
You can find the default configuration files on the latest tag 
.I https://github.com/sxyazi/yazi/tree/latest/yazi-config/preset.
.PP
.PP
To override any of the defaults, begin by creating the corresponding file at:
.IP \(bu 2
.I "~/.config/yazi/"
on Unix-like systems.
.IP \(bu 2
.I "C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]yazi\[rs]config\[rs]"
on Windows.
.PP
.SH CONFIGURATION MIXING
.PP
The options from your configuration file will be used to override the default. However, for key bindings, if you don't want to override the default directly: 
.P
.TS
box;
L.
# keymap.toml
_
[manager]
keymap = [
  # ...
]
.TE
.P
and instead want to customize your keys upon the default, you can use prepend_* or append_* directories to prepend or append them to the default.
.PP
.P
.TS
box;
L.
# keymap.toml
_
[manager]
prepend_keymap = [
  # ...
]
append_keymap = [
  # ...
]
.TE
.P
.PP
They are also available for open, icon, previewer, and preloader rules.
.PP
.SH CUSTOM CONFIG DIRECTORY
.PP
You can change the Yazi configuration directory by exporting the YAZI_CONFIG_HOME environment variable. For example:
.TS
box;
L.
env "YAZI_CONFIG_HOME=~/.config/yazi-alt" yazi
.TE
will start Yazi with 
.I "~/.config/yazi-alt" 
as the configuration directory, and can have its own 
.I "yazi.toml"
, 
.I "keymap.toml"
, 
.I "init.lua"
, etc. files within it.
.PP
.SH "GENERAL CONFIG (yazi.toml)"
.SS "[manager]"
.IP \(bu 2
.I "ratio"
Manage layout by ratio, 3\-element array.
.RS
.PP
.TS
L L.
[1,4,3]   1/8 width for parent, 4/8 width for current, 3/8 width for preview
.TE
.PP
.RE
.IP \(bu 2
.I "sort_by"
File sorting method.
.RS
.PP
.TS
L L.
"none"          Don't sort
"modified"      Sort by last modified time
"created"       Sort by creation time (Due to a Rust bug, this is not available at the moment)
"extension"     Sort by file extension
"alphabetical"  Sort alphabetically, e.g. 1.md < 10.md < 2.md
"natural"       Sort naturally, e.g. 1.md < 2.md < 10.md
"size"          Sort by file size
.TE
.PP
.RE

.IP \(bu 2
.I "sort_sensitive"
Sort case-sensitively.
.RS
.PP
.TS
L L.
"true"          Case-sensitive
"false"         Sort by last modified time
.TE
.PP
.RE

.IP \(bu 2
.I "sort_reverse"
Display files in reverse order.
.RS
.PP
.TS
L L.
"true"          Reverse order
"false"         Normal order
.TE
.PP
.RE

.IP \(bu 2
.I "sort_dir_first"
Display directories first.
.RS
.PP
.TS
L L.
"true"          Directories first
"false"         Respects sort_by and sort_reverse only
.TE
.PP
.RE

.IP \(bu 2
.I "sort_translit"
Transliterate filenames for sorting (i.e. replaces  as A, Æ as AE, etc.), only available if sort_by = "natural".

This is useful for files that contain Hungarian characters. (Currently requires nightly builds)
.RS
.PP
.TS
L L.
"true"          Enabled
"false"         Disabled
.TE
.PP
.RE

.IP \(bu 2
.I "linemode"
Display information associated with the file on the right side of the file list row.
.PP
  "none"          No line mode.
  "size"          Display the size in bytes of the file. Since file sizes are only 
                  evaluated when sorting by size, it only works after sort_by = "size" 
                  set, and this behavior might change in the future.
  "permissions"   Display the permissions of the file, only available on 
                  Unix-like systems.
  "mtime"         Display the last modified time of the file.
  "owner"         Display the owner of the file, only available on Unix-like systems.
                  (Nightly version of Yazi required atm)
.PP

.IP \(bu 2
.I "show_hidden"
Show hidden files
.RS
.PP
.TS
L L.
"true"          Show
"false"         Do not show
.TE
.PP
.RE

.IP \(bu 2
.I "show_symlink"
Show the path of the symlink file point to, after the filename.
.RS
.PP
.TS
L L.
"true"          Show
"false"         Do not show
.TE
.PP
.RE

.IP \(bu 2
.I "scrolloff"
The number of files to keep above and below the cursor when moving through the file list.

If the value is larger than half the screen height (e.g. 200), the cursor will be centered.

.IP \(bu 2
.I "mouse_events"
Array of strings, the types of mouse events can be received by the plugin system, available values:
.RS
.PP
.TS
L L.
"true"          Show
"false"         Do not show
"click"         Mouse click
"scroll"        Mouse vertical scroll
"touch"         Mouse horizontal scroll
"move"          Mouse move
"drag"          Mouse drag (Some terminals do not support this)
.TE
.PP
.RE

.IP \(bu 2
.I "mouse_events"
Array of strings, the types of mouse events can be received by the plugin system, available values:
.RS
.PP
.TS
L L.
"true"          Show
"false"         Do not show
"click"         Mouse click
"scroll"        Mouse vertical scroll
"touch"         Mouse horizontal scroll
"move"          Mouse move
"drag"          Mouse drag (Some terminals do not support this)
.TE
.PP
.RE

.SS "[preview]"

.IP \(bu 2
.I "tab_size"
Tab width.

.IP \(bu 2
.I "max_width"
Maximum preview width for images. Run a `yazi --clear-cache` to take effect after changing this.

This value is also used for preloading images; the larger it is, the larger the image cache generated, which consumes more CPU.

.IP \(bu 2
.I "max_height"
Maximum preview height for images. Run a `yazi --clear-cache` to take effect after changing this.

This value is also used for preloading images; the larger it is, the larger the image cache generated, which consumes more CPU.

.IP \(bu 2
.I "cache_dir"
The system cache directory is used by default, and the cached files will go away on a reboot automatically.

If you want to make it more persistent, you can specify the cache directory manually as an absolute path.

.IP \(bu 2
.I "image_filter"
The filter used on image downscaling, available values:
.RS
.PP
.TS
L L.
"nearest"       Nearest Neighbor
"triangle"      Linear Triangle
"catmull-rom"   Catmull-Rom
"lanczos3"      Lanczos with window 3
.TE
.PP
They are arranged in order from fast to slow, and from poor to good quality - Lanczos3 provides the highest quality but is also the slowest.
.RE

.IP \(bu 2
.I "image_quality"
Quality on pre-caching images, range 50-90.

The larger value, the better image quality, but slower with more CPU consumption, and generates larger cache files that occupy more storage space.

.IP \(bu 2
.I "sixel_fraction"
Sixel is a very old image format that only supports 256 colors. For better image preview, Yazi trains a neural network for each image to find the most representative colors.

This value determines the number of samples used during the training, range 10-20. A smaller value produces better results but is also slower.

.IP \(bu 2
.I "ueberzug_scale"
/
.I "ueberzug_offset"
.RS
.IP \(bu 2
.I "ueberzug_scale"
(Float): Ueberzug image scaling ratio, scale>1 for enlargement, scale<1 for reduction. For example, 0.5 indicates a reduction to half.
.IP \(bu 2
.I "ueberzug_offset" 
([x, y, width, height]): Ueberzug image offset, in cell units. For example, [0.5, 0.5, -0.5, -0.5] indicates that the image is offset by half a cell in both directions, and the width and height are reduced by half a cell.

This is useful for solving a bug of Überzug++ image size calculation.

If your monitor has a 2.0 scale factor, and is running on Wayland under Hyprland, you may need to set ueberzug_scale: 0.5, and adjust the value of ueberzug_offset according to your case, to offset this issue.
.RE

.SS "[opener]"
.TS
box;
L.
[opener]
edit = [
  { run = 'nvim "$@"', block = true },
]
play = [
  { run = 'mpv "$@"', orphan = true, for = "unix" },
]
open = [
  { run = 'xdg-open "$@"', desc = "Open" },
]
# ...
.TE
Available options are as follows:
.IP \(bu 2
.I run
: The command to open the selected files, with the following variables available:
.RS
.IP \(bu 2
.I $n 
(Unix) / 
.I %n
(Windows): The N-th selected file, starting from 1. e.g. $2 represents the second selected file.
.IP \(bu 2
.I $@ 
(Unix) / 
.I %* 
(Windows): All selected files, i.e. $1, $2, ..., $n.
.IP \(bu 2
.I $0 
(Unix) / 
.I %0 
(Windows): The hovered file.
.RE
.IP \(bu 2
.I block
: Open in a blocking manner. After setting this, Yazi will hide into a secondary screen and display the program on the main screen until it exits. During this time, it can receive I/O signals, which is useful for interactive programs.
.IP \(bu 2
.I orphan
: Keep the process running even if Yazi has exited, once specified, the process will be detached from the task scheduling system.
.IP \(bu 2
.I desc
: Description of the opener, display in interactive components, such as "Open with" and help menu.
.IP \(bu 2
.I for
: The opener is only available on this system; if not specified, it's available on all systems. Available values:
.RS
.IP \(bu 2
.I unix
: Linux and macOS
.IP \(bu 2
.I windows
: Windows
.IP \(bu 2
.I linux
: Linux
.IP \(bu 2
.I macos
: macOS
.RE

.SS "[open]"
Set rules for opening specific files. You can prepend or append rules to the default through 
.I prepend_rules 
and 
.I append_rules
(See Configuration mixing for details):
.TS
box;
L.
[open]
prepend_rules = [
  { name = "*.json", use = "edit" },
  # Multiple openers for a single rule
  { name = "*.html", use = [ "open", "edit" ] },
]
append_rules = [
  { name = "*", use = "my-fallback" },
]
.TE
If your 
.I append_rules 
contains wildcard rules, they will always take precedence over the default wildcard rules as the fallback (Currently requires nightly builds).

Or, use rules to rewrite the entire default rules:
.TS
box;
L.
[open]
rules = [
  { mime = "text/*", use = "edit" },
  { mime = "video/*", use = "play" },

  # { mime = "application/json", use = "edit" },
  { name = "*.json", use = "edit" },

  # Multiple openers for a single rule
  { name = "*.html", use = [ "open", "edit" ] },
]
.TE
Available rule options are as follows:
.PP
.IP \(bu 2
.I name
: Glob expression for matching the file name. Case insensitive by default, add \s to the beginning to make it sensitive.
.IP \(bu 2
.I mime
: Glob expression for matching the mime-type. Case insensitive by default, add \s to the beginning to make it sensitive.
.IP \(bu 2
.I use
: Opener name corresponding to the names in the [opener] section.
.PP
With that:
.PP
.IP \(bu 2
If you're using the default mime-type preloader, it retrieves the mime-type of a file through `file -bL --mime-type /path/to/file` command.
.IP \(bu 2
If
.I use
is an array containing multiple openers, all commands in these openers will be merged. open will run the first of these commands; open --interactive will list all of these commands in the "open with" menu.
.PP
.SS "[tasks]"
.PP
.IP \(bu 2
.I "micro_workers"
Maximum number of concurrent micro-tasks.
.IP \(bu 2
.I "macro_workers"
Maximum number of concurrent macro-tasks.
.IP \(bu 2
.I "bizarre_retry"
Maximum number of retries when a bizarre failure occurs.
.IP \(bu 2
.I "suppress_preload"
Exclude the preload tasks created by the system from the task list, do not report their progress, and do not consider them on app exit confirming.
.IP \(bu 2
.I "image_alloc"
Maximum memory allocation limit in bytes for decoding a single image, 0 for unlimited.
.IP \(bu 2
.I "image_bound"
An array of [width, height], maximum image size (in pixels) for decoding a single image, and 0 for unlimited.
.PP
.SS "[plugin]"
previewers (
.I "prepend_previewers"
&
.I "append_previewers"
)

You can prepend or append new preview rules to the default previewers under [plugin] by 
.I "prepend_previewers"
and 
.I "append_previewers."
See Configuration mixing for details. Here are the available options for a single rule:
.IP \(bu 2
.I name
(String): Glob expression for matching the file name. Case insensitive by default, add \[rs]s to the beginning to make it sensitive.
.IP \(bu 2
.I mime 
(String): Glob expression for matching the mime-type. Case insensitive by default, add \[rs]s to the beginning to make it sensitive.
.IP \(bu 2
.I run 
(String): The name of the Lua plugin to be ran.
.IP \(bu 2
.I sync 
(Boolean): Whether to run in the sync context, default is false.
.TS
box;
L.
[plugin]
prepend_previewers = [
  # HEIC previewer
  { mime = "image/heic", run = "heic" },
]

append_previewers = [
  # My fallback previewer
  { name = "*" , run = "binary" },
]
.TE
If your 
.I "append_previewers" 
contains wildcard name rules ("*" or "*/"), they will always take precedence over the default wildcard rules as the fallback.

Yazi comes with the these previewer plugins:
.RS
.IP \(bu 2 
folder: bridge between the Yazi file system and the preview
.IP \(bu 2 
code: bridge between built-in code highlighting and the preview, providing async concurrent rendering
.IP \(bu 2 
json: bridge between `jq` and the preview, providing async concurrent rendering
.IP \(bu 2 
noop: no operation
.IP \(bu 2 
image: presentation layer of built-in image preview, offering mixed preview capabilities
.IP \(bu 2 
video: bridge between `ffmpegthumbnailer` and the preview, offering mixed preview capabilities
.IP \(bu 2 
pdf: bridge between `pdftoppm` and the preview, offering mixed preview capabilities
.IP \(bu 2 
archive: bridge between `unar` and the preview, offering mixed preview and concurrent rendering capabilities
.RE

If you want to create your own previewer, see Previewer API (
.I "https://yazi-rs.github.io/docs/plugins/overview#previewer"
).

preloaders (
.I "prepend_preloaders" 
&
.I "append_preloaders"
)

You can prepend or append new preview rules to the default preloaders under [plugin] by 
.I "prepend_preloaders" 
and 
.I "append_preloaders"
See Configuration mixing for details. Here are the available options for a single rule:
.IP \(bu 2
.I name
(String): Glob expression for matching the file name. Case insensitive by default, add \[rs]s to the beginning to make it sensitive.
.IP \(bu 2
.I mime
(String): Glob expression for matching the mime-type. Case insensitive by default, add \[rs]s to the beginning to make it sensitive.
.IP \(bu 2
.I cond
(String): Conditional expression – Only rules that meet this condition and satisfy either the name or mime will be applied. For example, A & B means A and B, and A | !B means A or not B. Here are the available factors:
.IP \(bu 2
.I mime
: This file has a mime-type.
.IP \(bu 2
.I run
(String): The name of the Lua plugin to be ran.
.IP \(bu 2
.I multi
(Boolean): Whether to preload multiple files at once.
.IP \(bu 2
.I prio
(String): Preload priority, low, normal or high. The default is normal if not specified.

.TS
box;
L.
[plugin]
prepend_preloaders = [
  # HEIC preloader
  { mime = "image/heic", run = "heic" },
]
.TE

Yazi comes with the these preloader plugins:

.RS
.IP \(bu 2
mime: preloads mime-type of files in chunks
.IP \(bu 2
noop: no operation
.IP \(bu 2
image: preloads and caches images
.IP \(bu 2
video: preloads and caches videos
.IP \(bu 2
pdf: preloads and caches PDFs.
.RE

If you want to create your own preloader, see Preloader API (
.I "https://yazi-rs.github.io/docs/plugins/overview#preloader"
).

.SS "[input]"

You can customize the title and position of each input. As for position, it consists of two parts: Origin and Offset.

The origin is the top-left corner of the input, and the offset is the increment from this origin. Together, they determine the area of the input on the screen.

Origin

.PP
For the origin, the following values are available:
.IP \(bu 2
top-left
.IP \(bu 2
top-center
.IP \(bu 2
top-right
.IP \(bu 2
bottom-left
.IP \(bu 2
bottom-center
.IP \(bu 2
bottom-right
.IP \(bu 2
center
.IP \(bu 2
hovered (the cursor position of hovered file)
.PP

Offset

As for the offset, it's a 4-element tuple: (x, y, width, height).

Placeholder

Some inputs have special placeholders that will be replaced with actual content on display:
.IP \(bu 2
trash_title: String
.RS
.IP \(bu 2
{n}: Number of files to be trashed
.IP \(bu 2
{s}: "s" if n > 1, otherwise ""
.RE
.IP \(bu 2
delete_title: String
.RS
.IP \(bu 2
{n}: Number of files to be deleted
.IP \(bu 2
{s}: "s" if n > 1, otherwise ""
.RE
.IP \(bu 2
find_title: [String, String]

It's a tuple of 2-element: first for "Find next", second for "Find previous".
.IP \(bu 2
search_title: String
.RS
.IP \(bu 2
{n}: Name of the current search engine
.RE
.IP \(bu 2
shell_title: [String, String]

It's a tuple of 2-element: first for "Non-blocking shell", second for "Blocking shell".

.IP \(bu 2
quit_title: String
.RS
.IP \(bu 2
{n}: Number of tasks are running
.IP \(bu 2
{s}: "s" if n > 1, otherwise ""
.RE

.SS "[select]"
Same as the [input] section.

.SS "[which]"
.IP \(bu 2
.I "sort_by"
Candidate sorting method.
.RS
.PP
.TS
L L.
"none"    Don't sort
"key"     Sort by key
"desc"    Sort by description
.TE
.PP
.RE
.IP \(bu 2
.I "sort_sensitive"
Sort case-sensitively.
.RS
.PP
.TS
L L.
"true"          Case-sensitive
"false"         Sort by last modified time
.TE
.PP
.RE

.IP \(bu 2
.I "sort_reverse"
Display files in reverse order.
.RS
.PP
.TS
L L.
"true"          Reverse order
"false"         Normal order
.TE
.PP
.RE

.SH "KEYBINDINGS CONFIGURATION (keymap.toml)"

.SS [manager]

.I escape

Cancel find, exit visual mode, clear selected, cancel filter, or cancel search.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--all@Do all of the below.
--find@Cancel find.
--visual@Exit visual mode.
--select@Clear selected.
--filter@Cancel filter.
--search@Cancel search.

.TE

Automatically determine the operation by default, and it will only execute the selected operation after specifying the option; multiple options can be stacked.

.I quit

Exit the process.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--no-cwd-file@Don't write the current directory to the cwd-file.
.TE

.I close

Close the current tab; if it's the last tab, exit the process instead.

.I arrow

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[n] / [n%]@Move the cursor up or down by n or n% lines. 
 @Use negative values to move up and positive
 @values to move down.
.TE

.I leave

Go back to the parent directory of the hovered file, or the parent of the current working directory if no file is hovered on.

.I enter

Enter the child directory.

.I back

Go back to the previous directory.

.I forward

Go forward to the next directory.

.I seek

Scroll the contents in the preview panel.

.TS
box tab(@);
LB | LB
=  = =
L  | L.
Argument/Option@Description
[n]@Use negative values to seek up 
 @and positive values to seek down.
.TE

Note that the default scroll keys are Alt + j and Alt + k, make sure your terminal supports Alt key combinations, or you can change them in your keymap.toml.

.I cd

Change the current directory.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[path]@The path to change to.
--interactive@Use an interactive UI to input the path.
.TE

.I reveal

Change the current directory to the parent of specified file, and hover on it.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[path]@The path to reveal.
.TE

.I select

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--state=true@Select the current file.
--state=false@Deselect the current file.
--state=none@Default, toggle the selection state 
 @of the current file.
.TE

.I select_all

Select all files in the current working directory.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--state=true@Select all files
--state=false@Deselect all files
--state=none@Default, toggle the selection state of all files
.TE

Note that `--state=false` will deselect all files in the current working directory.

If you have selected files across directories and want to deselect all of them, use 'escape --select' instead.

.I visual_mode

Enter visual mode (selection mode).

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--unset@Enter visual mode (unset mode).
.TE

.I open

Open the selected files using the rules in [open].

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--interactive@Open the hovered/selected file(s) with an 
 @interactive UI to choose the opening method.
--hovered@Always open the hovered file regardless 
 @of the selection state.
.TE

.I yank

Yank the selected files.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--cut@Cut the selected files.
.TE

.I unyank

Cancel the yank status of files.

.I paste

Paste the yanked files.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--force@Overwrite the destination file if it exists.
--follow@Copy the file pointed to by a symbolic link,
 @rather than the link itself. Only can be used 
 @during copying.
.TE

.I link

Create a symbolic link to the yanked files. (This is a privileged action in Windows and must be run as an administrator.)

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--relative@Use a relative path for the symbolic link.
--force@Overwrite the destination file if it exists.
.TE

.I remove

Move the files to the trash/recycle bin on macOS/Windows. 
For Linux, it will follow The FreeDesktop.org Trash specification (https://specifications.freedesktop.org/trash-spec/trashspec-1.0.html)

In the Android platform, you can only use it with the '--permanently' option, since there lacks the concept of a trash bin.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--force@Don't show the confirmation dialog, and 
 @trash/delete files directly.
--permanently@Permanently delete the files.
--hovered@Always remove the hovered file regardless 
 @of the selection state. (Nightly version of 
 @Yazi is required ATM)
.TE

.I create

Create a file or directory. Ends with / (Unix) or \[rs] (Windows) for directories.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--force@Overwrite the destination file directly if it exists, 
 @without showing the confirmation dialog.
.TE

.I rename

Rename a file or directory, or bulk rename if multiple files are selected ($EDITOR is used to edit the filenames by default).

.PP
.IP \(bu 2
--hovered: 
Always rename the hovered file regardless of the selection state. (Nightly version of Yazi is required ATM)
.IP \(bu 2
--force: 
Overwrite the destination file directly if it exists, without showing the confirmation dialog.
.IP \(bu 2
--empty: 
Empty a part of the filename.
.RS
.IP \(bu 2
"stem": 
Empty the stem. e.g. "foo.jpg" -> ".jpg".
.IP \(bu 2
"ext": 
Empty the extension. e.g. "foo.jpg" -> "foo.".
.IP \(bu 2
"dot_ext": 
Empty the dot and extension. e.g. "foo.jpg" -> "foo".
.IP \(bu 2
"all": 
Empty the whole filename. e.g. "foo.jpg" -> "".
.RE
.IP \(bu 2
--cursor: 
Specify the cursor position of the renaming input box.
.RS
.IP \(bu 2
"end": 
The end of the filename.
.IP \(bu 2
"start": 
The start of the filename.
.IP \(bu 2
"before_ext": 
Before the extension of the filename.
.RE
.PP
You can also use '--cursor' with '--empty', for example, 'rename --empty=stem --cursor=start' will empty the file's stem, and move the cursor to the start.

Which causes the input box content for the filename 'foo.jpg' to be '|.jpg', where "|" represents the cursor position.

.I copy

Copy the path of files or directories that are selected or hovered on.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
path@Copy the absolute path.
dirname@Copy the path of the parent directory.
filename@Copy the name of the file.
name_without_ext@Copy the name of the file without the extension.
.TE

.I shell

Run a shell command.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[run]@Optional, command template to be run.
--confirm@When the template is provided, run it directly, 
 @no input UI was shown.
--block@Open in a blocking manner. After setting this, 
 @Yazi will hide into a secondary screen and 
 @display the program on the main screen until it 
 @exits. During this time, it can receive I/O signals, 
 @which is useful for interactive programs.
--orphan@Keep the process running even if Yazi has 
 @exited, once specified, the process will be 
 @detached from the task scheduling system.
.TE
You can use the following shell variables in '[run]':

.IP \(bu 2
$n (Unix) / %n (Windows): 
The N-th selected file, starting from 1. e.g. $2 represents the second selected file.
.IP \(bu 2
$@ (Unix) / %* (Windows): 
All selected files, i.e. $1, $2, ..., $n.
.IP \(bu 2
$0 (Unix) / %0 (Windows): 
The hovered file.

.I hidden

Set the visibility of hidden files.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
show@Show hidden files.
hide@Hide hidden files.
toggle@Default, toggle the hidden state.
.TE

.I linemode

Set the line mode.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
none@No line mode.
size@Display the size in bytes of the file. Since 
 @file sizes are only evaluated when sorting 
 @by size, it only works after sort_by = "size" set, 
 @and this behavior might change in the future.
permissions@Display the permissions of the file, 
 @only available on Unix-like systems.
mtime@Display the last modified time of the file.
owner@Display the owner of the file, 
@only available on Unix-like systems. 
@(Nightly version of Yazi required atm)
.TE

In addition, you can also specify any 1 to 20 characters, and extend it within a UI plugin. Which means you can implement your own linemode through the plugin by simply overriding the 
.I Folder:linemode 
method. (https://github.com/sxyazi/yazi/blob/latest/yazi-plugin/preset/components/folder.lua)

.I search

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[engine]@Search engine, available values: fd, rg, 
 @none (cancel search)
--args@Additional arguments passed to the specified engine, 
 @for example search fd --args='-e -H' 
 @(Nightly version of Yazi required atm)
.TE

You can search with an empty keyword ("") via fd to achieve flat view.

.I find

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[query]@Optional, the query to find for. If not provided, 
 @an interactive UI will be used to input with.
--previous@Find for the previous occurrence.
--smart@Use smart-case when finding, i.e. case-sensitive 
 @if the query contains uppercase characters, otherwise 
 @case-insensitive.
--insensitive@Use case-insensitive find.
.TE

.I find_arrow

Move the cursor to the next or previous occurrence.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--previous@Move to the previous occurrence.
.TE

.I filter
.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[query]@Optional, the query to filter for. If not provided, 
 @an interactive UI will be used to input with.
--smart@Use smart-case when filtering, i.e. case-sensitive 
 @if the query contains uppercase characters, otherwise 
 @case-insensitive.
--insensitive@Use case-insensitive filter.
.TE

.I sort
.IP \(bu 2
[by]: 
Optional, if not provided, the sort method will be kept unchanged.
.RS
.IP \(bu 2
"none": 
Don't sort.
.IP \(bu 2
"modified": 
Sort by last modified time.
.IP \(bu 2
"created": 
Sort by creation time. (Due to a Rust bug, this is not available at the moment, see sxyazi/yazi#356 and rust-lang/rust#108277)
.IP \(bu 2
"extension": 
Sort by file extension.
.IP \(bu 2
"alphabetical": 
Sort alphabetically, e.g. 1.md < 10.md < 2.md
.IP \(bu 2
"natural": 
Sort naturally, e.g. 1.md < 2.md < 10.md
.IP \(bu 2
"size": 
Sort by file size.
.RE
.IP \(bu 2
--reverse: 
Display files in reverse order. '--reverse' or '--reverse=yes' to reverse, '--reverse=no' to cancel.
.IP \(bu 2
--dir-first: 
Display directories first. '--dir-first' or '--dir-first=yes' to enable, '--dir-first=no' to cancel.
.IP \(bu 2
--translit: 
Transliterate filenames for sorting, see sort_translit for details. '--translit' or '--translit=yes' to enable, '--translit=no' to cancel.

.I tab_create
.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[path]@Optional, create a new tab using the specified path.
--current@Optional, create a new tab using the current path.
.TE

If neither '[path]' nor '--current' is specified, will use the startup directory to create the tab.

.I tab_close

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[n]@Close the tab at position n, starting from 0.
.TE

.I tab_switch

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[n]@Switch to the tab at position n, starting from 0.
--relative@Switch to the tab at a position relative 
 @to the current tab. The value of n can be negative 
 @when using this parameter.
.TE

.I tab_swap

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[n]@Swap the current tab with the tab at position n, 
 @where negative values move the tab 
 @forward, and positive values move it backward.
.TE

.I tasks_show

Show the task manager.

.I help

Open the help menu.

.I plugin

See yazi-plugin (7).

.SS [tasks]

.I close

Hide the task manager.

.I arrow

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
-1@Move the cursor up 1 line.
1@Move the cursor down 1 line.
.TE

.I inspect

Inspect the task (press q to exit the inspect view).

.I cancel

Cancel the task.

.I help

Open the help menu.

.I plugin

See yazi-plugin (7).

.SS [select]

.I close

Cancel selection.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--submit@Submit the selection.
.TE

.I arrow

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[n]@Move the cursor up or down n lines. 
 @Negative value for up, positive value for down.
.TE

.I help

Open the help menu.

.I plugin
See yazi-plugin (7).

.SS [input]

.I close

Cancel input.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--submit@Submit the input.
.TE

.I escape

Go back the normal mode, or cancel input.

.I move

Move the cursor left or right.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[n]@Move the cursor n characters left or right. 
 @Negative value for left, positive value for right.
--in-operating@Move the cursor only if its currently 
 @waiting for an operation.
.TE

.I backward

Move back to the start of the current or previous word.

.I forward

Move forward to the start of the next word.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--end-of-word@Move forward to the end of the current or next word.
.TE

.I insert

Enter insert mode. This command is only available in normal mode.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--append@Insert after the cursor.
.TE

.I visual

Enter visual mode. This command is only available in normal mode.

.I delete

Delete the selected characters. This command is only available in normal mode.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--cut@Cut the selected characters into clipboard, 
 @instead of only deleting them.
--insert@Delete and enter insert mode.
.TE

.I yank

Copy the selected characters. This command is only available in normal mode.

.I paste

Paste the copied characters after the cursor. This command is only available in normal mode.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--before@Paste the copied characters before the cursor.
.TE

.I undo

Undo the last operation. This command is only available in normal mode.

.I redo

Redo the last operation. This command is only available in normal mode.

.I help

Open the help menu. This command is only available in normal mode.

.I backspace

Delete the character before the cursor. This command is only available in insert mode.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--under@Delete the character under the cursor.
.TE

.I kill

Kill the specified range of characters. This command is only available in insert mode.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
bol@Kill backwards to the BOL.
eol@Kill forwards to the EOL.
backward@Kill backwards to the start of the current word.
forward@Kill forwards to the end of the current word.
.TE

.I plugin

See yazi-plugin (7). This command is only available in insert mode.

.SS [completion]

.I close

Hide the completion menu.

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
--submit@Submit the completion.
.TE

.I close_input

Close the input box. Arguments are the same as [input] close.

.I arrow

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[n]@Move the cursor up or down n lines. 
 @Negative value for up, positive value for down.
.TE

.I help

Open the help menu.

.I plugin

See yazi-plugin (7).

.SS [help]

.I close

Hide the help menu.

.I escape

Clear the filter, or hide the help menu.

.I arrow

.TS
box tab(@);
LB  | LB
=   = =
L   | L.
Argument/Option@Description
[n]@Move the cursor up or down n lines. 
 @Negative value for up, positive value for down.
.TE

.I filter

Apply a filter for the help items.

.I plugin

See yazi-plugin (7).

.SH "COLOR SCHEME CONFIGURATION (theme.toml)"
If you're looking for ready-made themes and don't want to create one yourself, check out the yazi-rs/flavors (
.I "https://github.com/yazi-rs/flavors"
) repository.

.SS Types

Color

A color. It can be in Hex format with RGB values, such as '#484D66'. Or can be one of the following 17 values:
.PP
.IP \(bu 2
reset
.IP \(bu 2
black
.IP \(bu 2
white
.IP \(bu 2
red
.IP \(bu 2
lightred
.IP \(bu 2
green
.IP \(bu 2
lightgreen
.IP \(bu 2
yellow
.IP \(bu 2
lightyellow
.IP \(bu 2
blue
.IP \(bu 2
lightblue
.IP \(bu 2
magenta
.IP \(bu 2
lightmagenta
.IP \(bu 2
cyan
.IP \(bu 2
lightcyan
.IP \(bu 2
gray
.IP \(bu 2
darkgray
.PP

Style

Appears in a format similar to '{ fg = "#e4e4e4", bg = "black", ... }', and supports the following properties:

.PP
.IP \(bu 2
fg (Color): Foreground color
.IP \(bu 2
bg (Color): Background color
.IP \(bu 2
bold (Boolean): Bold
.IP \(bu 2
dim (Boolean): Dim (not supported by all terminals)
.IP \(bu 2
italic (Boolean): Italic
.IP \(bu 2
underline (Boolean): Underline
.IP \(bu 2
blink (Boolean): Blink
.IP \(bu 2
blink_rapid (Boolean): Rapid blink
.IP \(bu 2
reversed (Boolean): Reversed foreground and background colors
.IP \(bu 2
hidden (Boolean): Hidden
.IP \(bu 2
crossed (Boolean): Crossed out
.PP

.SS [flavor]

.IP \(bu 2
use (String): Flavor name, e.g. "Dracula". See flavor documentation for more details. (
.I "https://yazi-rs.github.io/docs/flavors/overview/"
)

.SS [manager]

.PP
.IP \(bu 2
cwd (Style): CWD text style.
.PP

Hovered:

.PP
.IP \(bu 2
hovered (Style): Hovered file style.
.IP \(bu 2
preview_hovered (Style): Hovered file style, in the preview pane.
.PP

Find: The find feature

.PP
.IP \(bu 2
find_keyword (Style): Style of the highlighted portion in the filename.
.IP \(bu 2
find_position (Style): Style of current file location in all found files to the right of the filename.
.PP

Marker: Color block on the left side separator line in the filename.

.PP
.IP \(bu 2
marker_selected (Style): Selected file marker style.
.IP \(bu 2
marker_copied (Style): Copied file marker style.
.IP \(bu 2
marker_cut (Style): Cut file marker style.
.PP

Tab: Tab bar

.PP
.IP \(bu 2
tab_active (Style): Active tab style.
.IP \(bu 2
tab_inactive (Style): Inactive tab style.
.IP \(bu 2
tab_width (Number): Tab maximum width. When set to a value greater than 2, the remaining space will be filled with the tab name, which is current directory name.
.PP

Border:

.IP \(bu 2
border_symbol (String): Border symbol. e.g. "│".
.IP \(bu 2
border_style (Style): Border style.

Highlighting: The built-in syntax highlighting feature

.IP \(bu 2
syntect_theme (String): For example, "~/Downloads/Dracula.tmTheme". Only available in the user's theme.toml and cannot be used in flavor.toml.

Yazi's builtin code highlighting themes, which are paths to .tmTheme files. You can find them on GitHub using "tmTheme" as a keyword

.SS [status]

.PP
.IP \(bu 2
separator_open (String): Opening separator symbol. e.g. "[".
.IP \(bu 2
separator_close (String): Closing separator symbol. e.g. "]".
.IP \(bu 2
separator_style (Style): Separator style.
.PP

Mode

.PP
.IP \(bu 2
mode_normal (Style): Normal mode style.
.IP \(bu 2
mode_select (Style): Select mode style.
.IP \(bu 2
mode_unset (Style): Unset mode style.
.PP

Progress

.PP
.IP \(bu 2
progress_label (Style): Progress label style.
.IP \(bu 2
progress_normal (Style): Style of the progress bar when it is not in an error state.
.IP \(bu 2
progress_error (Style): Style of the progress bar when an error occurs.
.PP

Permissions

.PP
.IP \(bu 2
permissions_t (Style): File type.
.IP \(bu 2
permissions_r (Style): Read permission.
.IP \(bu 2
permissions_w (Style): Write permission.
.IP \(bu 2
permissions_x (Style): Execute permission.
.IP \(bu 2
permissions_s (Style): - separator.
.PP

.SS [select]

.PP
.IP \(bu 2
border (Style): Border style.
.IP \(bu 2
active (Style): Selected item style.
.IP \(bu 2
inactive (Style): Unselected item style.
.PP

.SS [input]

.PP
.IP \(bu 2
border (Style): Border style.
.IP \(bu 2
title (Style): Title style.
.IP \(bu 2
value (Style): Value style.
.IP \(bu 2
selected (Style): Selected value style.
.PP

.SS [completion]

.PP
.IP \(bu 2
border (Style): Border style.
.IP \(bu 2
active (Style): Selected item style.
.IP \(bu 2
inactive (Style): Unselected item style.
.PP

Icons

.PP
.IP \(bu 2
icon_file (String): File icon.
.IP \(bu 2
icon_folder (String): Folder icon.
.IP \(bu 2
icon_command (String): Command icon.
.PP

.SS [tasks]

.PP
.IP \(bu 2
border (Style): Border style.
.IP \(bu 2
title (Style): Title style.
.IP \(bu 2
hovered (Style): Hovered item style.
.PP

.SS[which]

.PP
.IP \(bu 2
cols (Number): Number of columns. The value can be 1, 2, 3.
.IP \(bu 2
mask (Style): Mask style.
.IP \(bu 2
cand (Style): Candidate key style.
.IP \(bu 2
rest (Style): Rest key style.
.IP \(bu 2
desc (Style): Description style.
.IP \(bu 2
separator (String): Separator symbol. e.g. " -> ".
.IP \(bu 2
separator_style (Style): Separator style.
.PP

.SS [help]

.PP
.IP \(bu 2
on (Style): Key column style.
.IP \(bu 2
run (Style): Command column style.
.IP \(bu 2
desc (Style): Description column style.
.IP \(bu 2
hovered (Style): Hovered item style.
.IP \(bu 2
footer (Style): Footer style.
.PP

.SS [filetype]

Set file list item display styles for specific file types, supporting matching by name and mime-type:

.TS
box;
L.
[filetype]
rules = [
  # Images
  { mime = "image/*", fg = "yellow" },

  # Videos
  { mime = "video/*", fg = "magenta" },
  { mime = "audio/*", fg = "magenta" },

  # Empty files
  { mime = "inode/x-empty", fg = "cyan" },

  # Orphan symbolic links
  { name = "*", is = "orphan", fg = "red" },

  # ...

  # Fallback
  # { name = "*", fg = "white" },
  { name = "*/", fg = "blue" }
]
.TE

Each rule supports complete Style properties. There are two special rule:

.PP
.TS
L L.
name = "*"    matches all files.
name = "*/"   matches all directories.
.TE
.PP

You can restrict the specific type of files through is, noting that it must be used with either name or mime. It accepts the following values:

.TS
L L.
block     Block device
char      Char device
exec      Executable
fifo      FIFO
link      Symbolic link
orphan    Orphan symbolic link
sock      Socket
sticky    File with sticky bit set
.TE

.SS [icon]

Display icon based on the first matched rule.

You can prepend or append rules to the default through 
.I prepend_rules
and
.I append_rules
See Configuration mixing for details.

.TS
box;
L.
[icon]
prepend_rules = [
  { name = "*.rs"    , text = "icon_glyph_here" },
  { name = "Desktop/", text = "icon_glyph_here" },
  # ...

  # Icon with a color
  { name = "*.lua", text = "icon_glyph_here", fg = "#51a0cf" },

  # You can also use `is` rule, just like `[filetype]` section
  # Orphan symbolic links
  { name = "*", is = "orphan", text = "icon_glyph_here" },
]

append_rules = [
  # My fallback icons
  { name = "*" , text = "icon_glyph_here" },
  { name = "*/", text = icon_glyph_here" },
]
.TE

Or, use rules to rewrite the entire default rules:

.TS
box;
L.
[icon]
rules = [
  # ...Some rules
]
.TE

End with / for directories, wildcard rule (* or */) can be used for fallback matching all files or directories.

If your 
.I append_rules 
contains wildcard rules, they will always take precedence over the default wildcard rules as the fallback.

.SH "SEE ALSO"
.BR yazi-config (5),
.BR yazi-plugins (7)