Skip to main content

keymap.toml

note

If you haven't created and used your own configuration file yet, please see Configuration.

You can change Yazi's keybindings in your keymap.toml file, which consists of the following 6 layers:

In each layer, there are two attributes: prepend_keymap and append_keymap. Prepend inserts before the default keybindings, while append inserts after them.

Since Yazi selects the first matching key to run, prepend always has a higher priority than default, and append always has a lower priority than default:

[manager]
prepend_keymap = [
	{ on = [ "<C-a>" ], run = 'my-fev-command1', desc = "Just for test!" },
]
append_keymap = [
	{ on = [ "<C-b>" ], run = 'my-fev-command2', desc = "Just for test!" },
]

Or in another different style:

[[manager.prepend_keymap]]
on   = [ "<C-a>" ]
run  = 'my-fev-command1'
desc = "Just for test!"

[[manager.prepend_keymap]]
on  = [ "<C-b>" ]
run = 'my-fev-command2'

[[manager.append_keymap]]
on  = [ "<C-c>" ]
run = 'my-fev-command3'

But keep in mind that you can only choose one of them, and it cannot be a combination of the two, as TOML language does not allow this:

[manager]
prepend_keymap = [
	{ on = [ "<C-a>" ], run = 'my-fev-command1', desc = "Just for test!" },
]

[[manager.prepend_keymap]]
on   = [ "<C-b>" ]
run  = 'my-fev-command2'
desc = "Just for test!"

When you don't need any default and want to fully customize your keybindings, use keymap, for example:

[manager]
keymap = [
	# This will override all default keybindings, and just keep the two below.
	{ on = [ "<C-a>" ], run = 'my-fev-command1', desc = "Just for test!" },
	{ on = [ "<C-b>" ], run = 'my-fev-command2', desc = "Just for test!" },
]

[manager]​

escape​

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

Argument/OptionDescription
--allDo all of the below.
--findCancel find.
--visualExit visual mode.
--selectClear selected.
--filterCancel filter.
--searchCancel search.

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

quit​

Exit the process.

Argument/OptionDescription
--no-cwd-fileDon't write the current directory to the cwd-file.

close​

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

arrow​

Argument/OptionDescription
[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.

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.

enter​

Enter the child directory.

back​

Go back to the previous directory.

forward​

Go forward to the next directory.

seek​

Scroll the contents in the preview panel.

Argument/OptionDescription
[n]Use negative values to seek up and positive values to seek down.

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.

cd​

Change the current directory.

Argument/OptionDescription
[path]The path to change to.
--interactiveUse an interactive UI to input the path.

reveal​

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

Argument/OptionDescription
[path]The path to reveal.

select​

Argument/OptionDescription
--state=trueSelect the current file.
--state=falseDeselect the current file.
--state=noneDefault, toggle the selection state of the current file.

select_all​

Select all files in the current working directory.

Argument/OptionDescription
--state=trueSelect all files
--state=falseDeselect all files
--state=noneDefault, toggle the selection state of all files

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.

visual_mode​

Enter visual mode (selection mode).

Argument/OptionDescription
--unsetEnter visual mode (unset mode).

open​

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

Argument/OptionDescription
--interactiveOpen the hovered/selected file(s) with an interactive UI to choose the opening method.
--hoveredAlways open the hovered file regardless of the selection state.

yank​

Yank the selected files.

Argument/OptionDescription
--cutCut the selected files.

unyank​

Cancel the yank status of files.

paste​

Paste the yanked files.

Argument/OptionDescription
--forceOverwrite the destination file if it exists.
--followCopy the file pointed to by a symbolic link, rather than the link itself. Only can be used during copying.

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

Argument/OptionDescription
--relativeUse a relative path for the symbolic link.
--forceOverwrite the destination file if it exists.

remove​

Move the files to the trash/recycle bin on macOS/Windows. For Linux, it will follow The FreeDesktop.org Trash specification.

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

Argument/OptionDescription
--forceDon't show the confirmation dialog, and trash/delete files directly.
--permanentlyPermanently delete the files.

create​

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

Argument/OptionDescription
--forceOverwrite the destination file directly if it exists, without showing the confirmation dialog.

rename​

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

  • --force: Overwrite the destination file directly if it exists, without showing the confirmation dialog.
  • --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.
  • --empty: Empty a part of the filename.
    • "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" -> "".

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.

copy​

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

Argument/OptionDescription
pathCopy the absolute path.
dirnameCopy the path of the parent directory.
filenameCopy the name of the file.
name_without_extCopy the name of the file without the extension.

shell​

Run a shell command.

Argument/OptionDescription
[run]Optional, command template to be run.
--confirmWhen the template is provided, run it directly, no input UI was shown.
--blockOpen 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.
--orphanKeep the process running even if Yazi has exited, once specified, the process will be detached from the task scheduling system.

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​

Set the visibility of hidden files.

Argument/OptionDescription
showShow hidden files.
hideHide hidden files.
toggleDefault, toggle the hidden state.

linemode​

Set the line mode.

Argument/OptionDescription
noneNo line mode.
sizeDisplay 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.
permissionsDisplay the permissions of the file.
mtimeDisplay the last modified time of the file.

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 Folder:linemode method.

search​

Argument/OptionDescription
fdSearch files by name using fd.
rgSearch files by content using ripgrep.
noneDefault, cancel the ongoing search.

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

Demonstrate flat view

find​

Argument/OptionDescription
[query]Optional, the query to find for. If not provided, an interactive UI will be used to input with.
--previousFind for the previous occurrence.
--smartUse smart-case when finding, i.e. case-sensitive if the query contains uppercase characters, otherwise case-insensitive.
--insensitiveUse case-insensitive find.

find_arrow​

Move the cursor to the next or previous occurrence.

Argument/OptionDescription
--previousMove to the previous occurrence.

filter​

Argument/OptionDescription
[query]Optional, the query to filter for. If not provided, an interactive UI will be used to input with.
--smartUse smart-case when filtering, i.e. case-sensitive if the query contains uppercase characters, otherwise case-insensitive.
--insensitiveUse case-insensitive filter.

sort​

  • by: Optional, if not provided, the sort method will be kept unchanged.
    • "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, 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.
  • --reverse: Display files in reverse order.
  • --dir-first: Display directories first.

tab_create​

Argument/OptionDescription
[path]Optional, create a new tab using the specified path.
--currentOptional, create a new tab using the current path.

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

tab_close​

Argument/OptionDescription
[n]Close the tab at position n, starting from 0.

tab_switch​

Argument/OptionDescription
[n]Switch to the tab at position n, starting from 0.
--relativeSwitch to the tab at a position relative to the current tab. The value of n can be negative when using this parameter.

tab_swap​

Argument/OptionDescription
[n]Swap the current tab with the tab at position n, where negative values move the tab forward, and positive values move it backward.

tasks_show​

Show the task manager.

help​

Open the help menu.

plugin​

See Functional plugin.

[tasks]​

close​

Hide the task manager.

arrow​

Argument/OptionDescription
-1Move the cursor up 1 line.
1Move 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 Functional plugin.

[select]​

close​

Cancel selection.

Argument/OptionDescription
--submitSubmit the selection.

arrow​

Argument/OptionDescription
[n]Move the cursor up or down n lines. Negative value for up, positive value for down.

help​

Open the help menu.

plugin​

See Functional plugin.

[input]​

close​

Cancel input.

Argument/OptionDescription
--submitSubmit the input.

escape​

Go back the normal mode, or cancel input.

move​

Move the cursor left or right.

Argument/OptionDescription
[n]Move the cursor n characters left or right. Negative value for left, positive value for right.
--in-operatingMove the cursor only if its 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.

Argument/OptionDescription
--end-of-wordMove forward to the end of the current or next word.

insert​

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

Argument/OptionDescription
--appendInsert 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.

Argument/OptionDescription
--cutCut the selected characters into clipboard, instead of only deleting them.
--insertDelete 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.

Argument/OptionDescription
--beforePaste 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.

Argument/OptionDescription
--underDelete the character under the cursor.

kill​

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

Argument/OptionDescription
bolKill backwards to the BOL.
eolKill forwards to the EOL.
backwardKill backwards to the start of the current word.
forwardKill forwards to the end of the current word.

plugin​

See Functional plugin. This command is only available in insert mode.

[completion]​

close​

Hide the completion menu.

Argument/OptionDescription
--submitSubmit the completion.

close_input​

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

arrow​

Argument/OptionDescription
[n]Move the cursor up or down n lines. Negative value for up, positive value for down.

help​

Open the help menu.

plugin​

See Functional plugin.

[help]​

close​

Hide the help menu.

escape​

Clear the filter, or hide the help menu.

arrow​

Argument/OptionDescription
[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 Functional plugin.