YAZI-CONFIG(1)

📦 version 26.9.1, in nixos 26.05, nixpkgs unstable

✨ NAME ✨

yazi-config — the config bible for the yazi terminal file manager, live from the General Commands Manual 💅

🎀 DESCRIPTION 🎀

bestie, this is where you learn how to make yazi look and act exactly how you want. configuration options for the yazi terminal file manager. There are three config files in total:

  • yazi.toml — General Configuration.
  • keymap.toml — Keybindings Configuration.
  • theme.toml — Color scheme Configuration.

You can find the default configuration files on the latest tag https://github.com/sxyazi/yazi/tree/latest/yazi-config/preset 🔗

To override any of the defaults, begin by creating the corresponding file at:

  • ~/.config/yazi/ on Unix-like systems.
  • C:\Users\USERNAME\AppData\Roaming\yazi\config\ on Windows.

so yes, you literally just make the file and yazi's like "say less" 🫶

🦋 CONFIGURATION MIXING 🦋

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:

# keymap.toml
[manager]
keymap = [
  # ...
]

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 ✨

# keymap.toml
[manager]
prepend_keymap = [
  # ...
]
append_keymap = [
  # ...
]

They are also available for open, icon, previewer, and preloader rules 👑

ngl this is the iconic way to do it — you keep all the default vibes and just sprinkle yours on top, no cap 💖

🌸 CUSTOM CONFIG DIRECTORY 🌸

You can change the Yazi configuration directory by exporting the YAZI_CONFIG_HOME environment variable. For example:

env "YAZI_CONFIG_HOME=~/.config/yazi-alt" yazi

will start Yazi with ~/.config/yazi-alt as the configuration directory, and can have its own yazi.toml , keymap.toml , init.lua , etc. files within it. like, a whole separate personality for yazi, obsessed 😭💜

🔥 GENERAL CONFIG (yazi.toml) 🔥

⭐ [manager] ⭐

  • ratio — Manage layout by ratio, 3-element array.
    • [1,4,3] — 1/8 width for parent, 4/8 width for current, 3/8 width for preview
  • sort_by — File sorting method. your options are:
    • "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
  • sort_sensitive — Sort case-sensitively.
    • "true" — Case-sensitive
    • "false" — Sort by last modified time
yes, that's genuinely what the "false" line says 😭 keeping it 100% faithful because that's what's written, periodt.
  • sort_reverse — Display files in reverse order.
    • "true" — Reverse order
    • "false" — Normal order
  • sort_dir_first — Display directories first.
    • "true" — Directories first
    • "false" — Respects sort_by and sort_reverse only
  • 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) 🌈

  • "true" — Enabled
  • "false" — Disabled
  • linemode — Display information associated with the file on the right side of the file list row.
    • "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)
  • show_hidden — Show hidden files
    • "true" — Show
    • "false" — Do not show
  • show_symlink — Show the path of the symlink file point to, after the filename.
    • "true" — Show
    • "false" — Do not show
  • 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. 🎯

  • mouse_events — Array of strings, the types of mouse events can be received by the plugin system, available values:
    • "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)
  • mouse_events — Array of strings, the types of mouse events can be received by the plugin system, available values:
    • "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)
not me listing mouse_events twice 💀 the original literally has it twice, so here it is twice. we don't skip, we don't merge, we stay faithful fr fr 🫶

🧚 [preview] 🧚

  • tab_size — Tab width.
  • 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. 🔥

  • 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. 🔥

  • 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. 💾

  • image_filter — The filter used on image downscaling, available values:
    • "nearest" — Nearest Neighbor
    • "triangle" — Linear Triangle
    • "catmull-rom" — Catmull-Rom
    • "lanczos3" — Lanczos with window 3

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. ⚖️

  • 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. so like, gorgeous but expensive 💅

  • 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.

  • ueberzug_scale / ueberzug_offset
    • ueberzug_scale (Float): Ueberzug image scaling ratio, scale>1 for enlargement, scale<1 for reduction. For example, 0.5 indicates a reduction to half.
    • 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.

👑 [opener] 👑

[opener]
edit = [
  { run = 'nvim "$@"', block = true },
]
play = [
  { run = 'mpv "$@"', orphan = true, for = "unix" },
]
open = [
  { run = 'xdg-open "$@"', desc = "Open" },
]
# ...

Available options are as follows:

  • run — The command to open the selected files, with the following variables available:
    • $n (Unix) / %n (Windows): The N-th selected file, starting from 1. e.g. $2 represents the second selected file.
    • $@ (Unix) / %* (Windows): All selected files, i.e. $1, $2, ..., $n.
    • $0 (Unix) / %0 (Windows): The hovered file.
  • 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. 🕊️
  • desc — Description of the opener, display in interactive components, such as "Open with" and help menu.
  • for — The opener is only available on this system; if not specified, it's available on all systems. Available values:
    • unix — Linux and macOS
    • windows — Windows
    • linux — Linux
    • macos — macOS

[open] — rules for opening files, periodt 💅

This is where you tell Yazi how to open specific files. You can prepend or append rules to the defaults through prepend_rules and append_rules (see Configuration mixing for the deets, bestie):

[open]
prepend_rules = [
  { name = "*.json", use = "edit" },
  # Multiple openers for a single rule
  { name = "*.html", use = [ "open", "edit" ] },
]
append_rules = [
  { name = "*", use = "my-fallback" },
]

If your append_rules contains wildcard rules, they will always take precedence over the default wildcard rules as the fallback (currently requires nightly builds).

Heads up, bestie: that wildcard fallback thing is a nightly-builds situation right now. Don't come for me if stable acts different 💀

Or, use rules to rewrite the entire default rules:

[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" ] },
]

Available rule options are as follows:

  • name — glob expression for matching the file name. Case insensitive by default; add to the beginning to make it sensitive.
  • mime — glob expression for matching the mime-type. Case insensitive by default; add to the beginning to make it sensitive.
  • use — opener name corresponding to the names in the [opener] section.

With that:

  • If you're using the default mime-type preloader, it retrieves the mime-type of a file through the file -bL --mime-type /path/to/file command.
  • If 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.

[tasks] — task-manager vibes 🧚

  • micro_workers — maximum number of concurrent micro-tasks.
  • macro_workers — maximum number of concurrent macro-tasks.
  • bizarre_retry — maximum number of retries when a bizarre failure occurs.
  • 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.
  • image_alloc — maximum memory allocation limit in bytes for decoding a single image, 0 for unlimited.
  • image_bound — an array of [width, height], maximum image size (in pixels) for decoding a single image, and 0 for unlimited.

[plugin] — plugins, previewers, preloaders, the whole cute little ecosystem 🦋

previewers (prepend_previewers & append_previewers)

You can prepend or append new preview rules to the default previewers under [plugin] by prepend_previewers and append_previewers. See Configuration mixing for details. Here are the available options for a single rule:

  • name (String) — glob expression for matching the file name. Case insensitive by default; add \s to the beginning to make it sensitive.
  • mime (String) — glob expression for matching the mime-type. Case insensitive by default; add \s to the beginning to make it sensitive.
  • run (String) — the name of the Lua plugin to be ran.
  • sync (Boolean) — whether to run in the sync context, default is false.
[plugin]
prepend_previewers = [
  # HEIC previewer
  { mime = "image/heic", run = "heic" },
]

append_previewers = [
  # My fallback previewer
  { name = "*" , run = "binary" },
]

If your append_previewers contains wildcard name rules ("*" or "*/"), they will always take precedence over the default wildcard rules as the fallback.

Yazi comes with these previewer plugins:

  • folder — bridge between the Yazi file system and the preview
  • code — bridge between built-in code highlighting and the preview, providing async concurrent rendering
  • json — bridge between jq and the preview, providing async concurrent rendering
  • noop — no operation
  • image — presentation layer of built-in image preview, offering mixed preview capabilities
  • video — bridge between ffmpegthumbnailer and the preview, offering mixed preview capabilities
  • pdf — bridge between pdftoppm and the preview, offering mixed preview capabilities
  • archive — bridge between unar and the preview, offering mixed preview and concurrent rendering capabilities

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

preloaders (prepend_preloaders & append_preloaders)

You can prepend or append new preview rules to the default preloaders under [plugin] by prepend_preloaders and append_preloaders. See Configuration mixing for details. Here are the available options for a single rule:

  • name (String) — glob expression for matching the file name. Case insensitive by default; add \s to the beginning to make it sensitive.
  • mime (String) — glob expression for matching the mime-type. Case insensitive by default; add \s to the beginning to make it sensitive.
  • 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:
    • mime — this file has a mime-type.
  • run (String) — the name of the Lua plugin to be ran.
  • multi (Boolean) — whether to preload multiple files at once.
  • prio (String) — preload priority, low, normal or high. The default is normal if not specified.
[plugin]
prepend_preloaders = [
  # HEIC preloader
  { mime = "image/heic", run = "heic" },
]

Yazi comes with these preloader plugins:

  • mime — preloads mime-type of files in chunks
  • noop — no operation
  • image — preloads and caches images
  • video — preloads and caches videos
  • pdf — preloads and caches PDFs.

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

[input] — input boxes, but make them cute 🎀

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

For the origin, the following values are available:

  • top-left
  • top-center
  • top-right
  • bottom-left
  • bottom-center
  • bottom-right
  • center
  • hovered (the cursor position of hovered file)

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:

  • trash_title: String
    • {n}: Number of files to be trashed
    • {s}: "s" if n > 1, otherwise ""
  • delete_title: String
    • {n}: Number of files to be deleted
    • {s}: "s" if n > 1, otherwise ""
  • find_title: [String, String]

It's a tuple of 2-element: first for "Find next", second for "Find previous".

  • search_title: String
    • {n}: Name of the current search engine
  • shell_title: [String, String]

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

  • quit_title: String
    • {n}: Number of tasks are running
    • {s}: "s" if n > 1, otherwise ""

[select] — same energy as [input] ✨

Same as the [input] section.

[which] — the which-key menu, sorted and slaying 🔥

  • sort_by — candidate sorting method.
    • "none" — don't sort
    • "key" — sort by key
    • "desc" — sort by description
  • sort_sensitive — sort case-sensitively.
    • "true" — case-sensitive
    • "false" — sort by last modified time
  • sort_reverse — display files in reverse order.
    • "true" — reverse order
    • "false" — normal order

KEYBINDINGS CONFIGURATION (keymap.toml) 🔑

[manager]

  • escape — cancel find, exit visual mode, clear selected, cancel filter, or cancel search.
  • --all — do all of the below, all at once, the whole sweep 💅
  • --find — cancel find
  • --visual — exit visual mode
  • --select — clear selected
  • --filter — cancel filter
  • --search — cancel search

By default it just auto-detects what you probably meant (main character energy tbh), and it'll only run the specific operation once you actually name the option — and yes bestie, you can stack multiple options together. Slay.

quit

Exit the process. That's it, that's the whole vibe. 🚪💨

  • --no-cwd-file — don't write the current directory to the cwd-file

close

Close the current tab — but if it's the last tab, it exits the process instead. So it's giving "one more won't hurt" until it literally does 😭

arrow

  • [n] / [n%] — move the cursor up or down by n or n% lines. Negative values move up, positive values move down. Yes, percentages are a thing, we love a flexible queen ✨

leave

Go back to the parent directory of the hovered file — or, if nothing's hovered, the parent of the current working directory. Basically "take me up a level, idk where" 🫶

enter

Enter the child directory. Go 👏 in 👏 side 👏 the 👏 folder.

back

Go back to the previous directory.

forward

Go forward to the next directory. The duality of back and forward, we stan a pair of icons 🌈

seek

Scroll the contents in the preview panel.

  • [n] — negative values seek up, positive values seek down
Heads up: the default scroll keys are Alt + j and Alt + k, so make sure your terminal actually supports Alt key combos — or just change them in your keymap.toml, your call 💅

cd

Change the current directory.

  • [path] — the path to change to
  • --interactive — use an interactive UI to input the path (for when you want the app to hold your hand, no judgement 💖)

reveal

Change the current directory to the parent of the specified file, and hover on it. Like a little spotlight moment for one specific file 🎀

  • [path] — the path to reveal

select

  • --state=true — select the current file
  • --state=false — deselect the current file
  • --state=none — default, toggle the selection state of the current file

select_all

Select all files in the current working directory.

  • --state=true — select all files
  • --state=false — deselect all files
  • --state=none — default, toggle the selection state of all files
Ngl this one trips people up: --state=false will deselect all files in the current working directory only.

So if you've got files selected across multiple directories and you want to nuke the whole selection, use escape --select instead. Different tool, different job 🧚

visual_mode

Enter visual mode (selection mode). Main character selection era 👑

  • --unset — enter visual mode (unset mode)

open

Open the selected files using the rules in [open]. Your very own "idk, you pick" button for opening stuff 🔥

  • --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

yank

Yank the selected files. Copied, bestie, it's in the clipboard of destiny ✨

  • --cut — cut the selected files

unyank

Cancel the yank status of files. Never mind, un-copied 🙈

paste

Paste the yanked files.

  • --force — if the destination file already exists, overwrite it. no questions, no mercy 💅
  • --follow — copy the file that a symbolic link points to, instead of the link itself. heads up: this only works during copying, bestie.

makes a symbolic link to whatever files you've yanked. and yeah, on Windows this is a privileged action — you gotta be running as an administrator or it's simply not happening, periodt.

  • --relative — use a relative path for the symbolic link.
  • --force — overwrite the destination file if it's already there.

remove 🗑️

moves your files to the trash/recycle bin on macOS/Windows. on Linux it follows The FreeDesktop.org Trash specification — the spec lives at https://specifications.freedesktop.org/trash-spec/trashspec-1.0.html, iykyk.

tiny lil Android caveat: on the Android platform you can only use this with the --permanently option, because Android straight up doesn't have the concept of a trash bin. it's giving "no bin, no problem" 😭
  • --force — don't show the confirmation dialog, just trash/delete the files directly.
  • --permanently — permanently delete the files. they're gone-gone, fr fr.
  • --hovered — always remove the hovered file regardless of the selection state. (Nightly version of Yazi is required ATM)

create ✨

creates a file or a directory. the trick? end the name with / (Unix) or \ (Windows) and you get a directory. iconic behaviour tbh.

  • --force — overwrite the destination file directly if it exists, without showing the confirmation dialog.

rename 🦋

renames a file or directory — or does a bulk rename if multiple files are selected ($EDITOR is used to edit the filenames by default). chef's kiss 🌸

  • --hovered: always rename the hovered file regardless of the selection state. (Nightly version of Yazi is required ATM)
  • --force: overwrite the destination file directly if it exists, without showing the confirmation dialog.
  • --empty: empty a part of the filename. pick your fighter:
    • "stem": empty the stem. e.g. "foo.jpg" -> ".jpg".
    • "ext": empty the extension. e.g. "foo.jpg" -> "foo.".
    • "dot_ext": empty the dot and extension. e.g. "foo.jpg" -> "foo".
    • "all": empty the whole filename. e.g. "foo.jpg" -> "".
  • --cursor: specify the cursor position of the renaming input box.
    • "end": the end of the filename.
    • "start": the start of the filename.
    • "before_ext": before the extension of the filename.

you can also combo --cursor with --empty — for example, rename --empty=stem --cursor=start empties the file's stem and moves the cursor to the start. 💫

which means the input box content for the filename foo.jpg becomes |.jpg, where | is the cursor position. so satisfying.

copy 📋

copies the path of the files or directories that are selected or hovered on. literally the easiest way to get a path into your clipboard-adjacent life.

  • 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.

shell 🐚

runs a shell command. yes queen, go off.

  • [run] — optional, and it's the command template to be run.
  • --confirm — when the template is provided, run it directly, and no input UI is shown.
  • --block — open in a blocking manner. after you set this, Yazi hides into a secondary screen and displays the program on the main screen until it exits. during that time it can receive I/O signals, which is highkey useful for interactive programs.
  • --orphan — keep the process running even if Yazi has exited. once specified, the process gets detached from the task scheduling system. it's giving main character energy, living its own life 🧚

you can use the following shell variables in [run]:

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

hidden 🙈

sets the visibility of hidden files. do you see them or not, bestie.

  • show — show hidden files.
  • hide — hide hidden files.
  • toggle — default, toggles the hidden state.

linemode ⭐

set the line mode.

🎀 linemode arguments, bestie

So linemode takes one of these, and here's the whole menu:

  • none — no line mode at all, we're keeping it clean ✨
  • size — shows the file size in bytes. Heads up tho: file sizes only get evaluated when you're sorting by size, so this only actually works after you've set sort_by = "size". And this behavior might change in the future — so don't get too attached 💀
  • permissions — shows the file's permissions. Unix-like systems only, sorry Windows girlies 🫶
  • mtime — shows the last modified time. Obsessed with a timestamp, honestly 🕐
  • owner — shows the file's owner. Unix-like systems only. (Nightly version of Yazi required atm 👑)

And here's the fun part: you can also specify any 1 to 20 characters, and then extend it inside a UI plugin. Which literally means you can build your own linemode by just overriding the Folder:linemode method — main character energy fr fr:

https://github.com/sxyazi/yazi/blob/latest/yazi-plugin/preset/components/folder.lua

  • [engine] — the search engine, and your options are: fd, rg, none (which cancels the search ✋)
  • --args — extra arguments passed straight to the engine you picked. Like, for example, search fd --args='-e -H' 💅 (Nightly version of Yazi required atm)
Fun trick, iykyk: you can search with an empty keyword ("") via fd to get that flat view. It's giving everything, all at once 🌈

🕵️ find

  • [query] — optional! The query you're finding for. If you don't give one, an interactive UI pops up so you can type it in 🎀
  • --previous — find the previous occurrence instead. Going backwards bestie ⬅️
  • --smart — smart-case finding, meaning it's case-sensitive if your query has uppercase characters, otherwise it's case-insensitive ✨
  • --insensitive — case-insensitive find, periodt.

🏹 find_arrow

Moves the cursor to the next or previous occurrence — that's it, that's the whole vibe.

  • --previous — move to the previous occurrence instead of the next one.

🧺 filter

  • [query] — optional, the query you're filtering for. Don't pass one and an interactive UI shows up so you can type it 🦋
  • --smart — smart-case filtering: case-sensitive if the query contains uppercase characters, otherwise case-insensitive, no cap.
  • --insensitive — case-insensitive filter, periodt.

🗂️ sort

  • [by] — optional. If you don't provide it, the sort method stays exactly as it was, unchanged 💜

The values you can pass to [by] are:

  • "none" — don't sort. Chaos. We love her 🙈
  • "modified" — sort by last modified time.
  • "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 😭)
  • "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.

And the flags:

  • --reverse — display files in reverse order. --reverse or --reverse=yes to reverse, --reverse=no to cancel it out 🔄
  • --dir-first — display directories first. --dir-first or --dir-first=yes to enable, --dir-first=no to cancel.
  • --translit — transliterate filenames for sorting, see sort_translit for the details. --translit or --translit=yes to enable, --translit=no to cancel 🌸

🆕 tab_create

  • [path] — optional, creates a new tab using the path you specify.
  • --current — optional, creates a new tab using the current path.
And if you specify neither [path] nor --current, it'll use the startup directory to create the tab. Default behavior stays winning ✨

❌ tab_close

  • [n] — closes the tab at position n, counting from 0. Zero-indexed babies, that's just how it is 💅

🔀 tab_switch

  • [n] — switches to the tab at position n, starting from 0.
  • --relative — switch to the tab at a position relative to the current tab. With this parameter, n can totally be negative — go backwards, girl 🦋

🔁 tab_swap

Okay so back to that tab-swap command from the last bit — its arg table is literally:

  • [n] — swap the current tab with the tab at position n, where negative values move the tab forward, and positive values move it backward. tab gymnastics, periodt 💅

Then the rest of the manager-side commands:

  • tasks_show — show the task manager. task-manager main character moment ✨
  • help — open the help menu. 🫶
  • plugin — see yazi-plugin (7).

[tasks] 🧚

  • close — hide the task manager.
  • arrow — move the cursor in the task manager:
    • -1 — move the cursor up 1 line.
    • 1 — move the cursor down 1 line.
  • inspect — inspect the task (press q to exit the inspect view). 🔍
  • cancel — cancel the task. 💀
  • help — open the help menu.
  • plugin — see yazi-plugin (7).

[select] 💅

  • close — cancel selection.
    • --submit — submit the selection. ✅
  • arrow — move the cursor around:
    • [n] — move the cursor up or down n lines. Negative value for up, positive value for down.
  • help — open the help menu.
  • plugin — see yazi-plugin (7).

[input] 🎀

  • close — cancel input.
    • --submit — submit the input. 🫡
  • escape — go back to normal mode, or cancel input.
  • move — move the cursor left or right.
    • [n] — move the cursor n characters left or right. Negative value for left, positive value for right.
    • --in-operating — move the cursor only if it’s currently waiting for an operation.
  • backward — move back to the start of the current or previous word.
  • forward — move forward to the start of the next word.
    • --end-of-word — move forward to the end of the current or next word.
  • insert — enter insert mode. This command is only available in normal mode.
    • --append — insert after the cursor.
  • visual — enter visual mode. This command is only available in normal mode.
  • delete — delete the selected characters. This command is only available in normal mode.
    • --cut — cut the selected characters into clipboard, instead of only deleting them.
    • --insert — delete and enter insert mode.
  • yank — copy the selected characters. This command is only available in normal mode.
  • paste — paste the copied characters after the cursor. This command is only available in normal mode.
    • --before — paste the copied characters before the cursor.
  • undo — undo the last operation. This command is only available in normal mode.
  • redo — redo the last operation. This command is only available in normal mode.
  • help — open the help menu. This command is only available in normal mode.
  • backspace — delete the character before the cursor. This command is only available in insert mode.
    • --under — delete the character under the cursor.
  • kill — kill the specified range of characters. This command is only available in insert mode.

okay so the argument table continues, and it’s giving precision 💅:

  • 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.
  • plugin — See yazi-plugin (7). This command is only available in insert mode.

🎀 [completion] 🎀

  • close — Hide the completion menu.
    • --submit — Submit the completion.
  • close_input — Close the input box. Arguments are the same as [input] close.
  • arrow — takes [n]: Move the cursor up or down n lines. Negative value for up, positive value for down.
  • help — Open the help menu.
  • plugin — See yazi-plugin (7).

🦋 [help] 🦋

  • close — Hide the help menu.
  • escape — Clear the filter, or hide the help menu.
  • arrow — takes [n]: Move the cursor up or down n lines. Negative value for up, positive value for down.
  • filter — Apply a filter for the help items.
  • plugin — See yazi-plugin (7).

🎨 COLOR SCHEME CONFIGURATION (theme.toml) 💅

okay so if you want ready-made themes and you do not wanna build one yourself, go check out the yazi-rs/flavors repository at https://github.com/yazi-rs/flavors — it’s giving pre-made slay ✨

🌈 Types

🎨 Color

A color can be in Hex format with RGB values, like '#484D66'. Or it can be one of these 17 values, no cap:

  • reset
  • black
  • white
  • red
  • lightred
  • green
  • lightgreen
  • yellow
  • lightyellow
  • blue
  • lightblue
  • magenta
  • lightmagenta
  • cyan
  • lightcyan
  • gray
  • darkgray

💅 Style

Style shows up in a format similar to '{ fg = "#e4e4e4", bg = "black", ... }', and it supports these properties:

  • fg (Color) — Foreground color 💖
  • bg (Color) — Background color 🎀
  • bold (Boolean) — Bold
  • dim (Boolean) — Dim (not supported by all terminals, heads up 🫶)
  • italic (Boolean) — Italic
  • underline (Boolean) — Underline
  • blink (Boolean) — Blink
  • blink_rapid (Boolean) — Rapid blink
  • reversed (Boolean) — Reversed foreground and background colors
  • hidden (Boolean) — Hidden
  • crossed (Boolean) — Crossed out

🌸 [flavor]

🗂️ [manager]

  • cwd (Style) — CWD text style.

💖 Hovered

  • hovered (Style) — Hovered file style.
  • preview_hovered (Style) — Hovered file style, in the preview pane.

🔍 Find: The find feature

  • find_keyword (Style) — Style of the highlighted portion in the filename.
  • find_position (Style) — Style of current file location in all found files to the right of the filename.

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

  • marker_selected (Style) — Selected file marker style.
  • marker_copied (Style) — Copied file marker style.
  • marker_cut (Style) — Cut file marker style.

🦋 Tab: Tab bar

  • tab_active (Style) — Active tab style.
  • tab_inactive (Style) — Inactive tab style.
  • 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.

⭐ Border

  • border_symbol (String) — Border symbol. e.g. "│".
  • border_style (Style) — Border style.

🧚 Highlighting: The built-in syntax highlighting feature

  • 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 🔥

💜 [status]

  • separator_open (String) — Opening separator symbol. e.g. "[".
  • separator_close (String) — Closing separator symbol. e.g. "]".
  • separator_style (Style) — Separator style.

🌟 Mode

  • mode_normal (Style) — Normal mode style.
  • mode_select (Style) — Select mode style.
  • mode_unset (Style) — Unset mode style.

🍓 Progress

  • progress_label (Style) — Progress label style.
  • progress_normal (Style) — Style of the progress bar when it is not in an error state.
  • progress_error (Style) — Style of the progress bar when an error occurs.

🔐 Permissions

  • permissions_t (Style) — File type.
  • permissions_r (Style) — Read permission.
  • permissions_w (Style) — Write permission.
  • permissions_x (Style) — Execute permission.
  • permissions_s (Style) — - separator.

🫶 [select]

  • border (Style) — Border style.
  • active (Style) — Selected item style.
  • inactive (Style) — Unselected item style.

💌 [input]

  • border (Style) — Border style.
  • title (Style) — Title style.
  • value (Style) — Value style.
  • selected (Style) — Selected value style.

✨ [completion]

  • border (Style) — Border style.
  • active (Style) — Selected item style.
  • inactive (Style) — Unselected item style.

🌈 Icons

  • icon_file (String) — File icon.
  • icon_folder (String) — Folder icon.
  • icon_command (String) — Command icon.

🛠️ [tasks]

  • border (Style) — Border style.
  • title (Style) — Title style.
  • hovered (Style) — Hovered item style.
  • cols (Number) — Number of columns. The value can be 1, 2, 3.
  • mask (Style) — Mask style.
  • cand (Style) — Candidate key style.
  • rest (Style) — Rest key style.
  • desc (Style) — Description style.
  • separator (String) — Separator symbol. e.g. " -> ".
  • separator_style (Style) — Separator style.

💡 [help]

  • on (Style) — Key column style.
  • run (Style) — Command column style.
  • desc (Style) — Description column style.
  • hovered (Style) — Hovered item style.
  • footer (Style) — Footer style.

🎨 [filetype]

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

┌──────────────────────────────────────────────┐
│ [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" }               │
│ ]                                            │
└──────────────────────────────────────────────┘

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

name = "*"    matches all files.
name = "*/"   matches all directories.

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:

  • 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

🖼️ [icon]

Display icon based on the first matched rule.

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

┌─────────────────────────────────────────────────────────────────┐
│ [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" },                     │
│ ]                                                               │
└─────────────────────────────────────────────────────────────────┘

Or, use rules to rewrite the entire default rules:

┌───────────────────┐
│ [icon]            │
│ rules = [         │
│   # ...Some rules │
│ ]                 │
└───────────────────┘

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

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

👀 SEE ALSO

yazi-config(5), yazi-plugins(7)

okay bestie, that’s the whole YAZI-CONFIG(1) glow-up 💖 the source/version and date are serving footer realness at the very end, and they ate 💅🫶

📦 where this page comes from