keymap.toml

December 26, 2025 · View on GitHub

This file is for mapping keyboard keys to commands.

# keymapping for default view
[default_view]
keymap = [
    { keys = [ "T" ], command = "new_tab" },
    # ...
]

# keymapping for task view
[task_view]
keymap = [
    # ...
]

# keymapping for help view
[help_view]
keymap = [
    # ...
]

For more examples, take a look at config/keymap.toml

Keys available:

To combine keys with Ctrl and Alt, simply have ctrl+key/alt+key where key is a valid key.

In addition to the standard alphabet, Joshuto currently also support the following keys.

backspace
backtab     # this is shift+tab
arrow_left
arrow_right
arrow_up
arrow_down
home
end
page_up
page_down
delete
insert
escape
f1
f2
f3
f4
f5
f6
f7
f8
f9
f10
f11
f12

Commands available:

General
Navigation
Tabs
Search
Integration

General

`quit`: quit joshuto

will not quit if there are pending IO work (paste jobs)
quit
- exit code 0
quit --force: does NOT wait for pending IO work
- exit code 100
quit --output-current-directory: if --output-file argument is set, output the current directory to it
- exit code 101
quit --output-selected-files: if --output-file argument is set, output the selected files to it
- exit code 102

To exit into the current directory you need to add a snippet to your preferred shell's init script to integrate with quit.

POSIX-compliant shells (bash, zsh, dash, ...)

joshuto() {
    ID="$$"
    mkdir -p "/tmp/$USER"
    OUTPUT_FILE="/tmp/$USER/joshuto-cwd-$ID"
    env joshuto --output-file "$OUTPUT_FILE" "$@"
    exit_code="$?"

    case "$exit_code" in
        # regular exit
        0)
            ;;
        # output contains current directory
        101)
            JOSHUTO_CWD=$(cat "$OUTPUT_FILE")
            cd "$JOSHUTO_CWD" || return
            ;;
        # output selected files
        102)
            ;;
        *)
            echo "Exit code: $exit_code"
            ;;
    esac
}

Fish

function joshuto
    set ID %self
    set -l output_file /tmp/$USER/joshuto-cwd-$ID

    mkdir -p /tmp/$USER
    env joshuto --output-file "$output_file" $argv
    set exit_code $status

    switch $exit_code
        case 0
            # Regular exit, do nothing
        case 101
            set JOSHUTO_CWD (cat "$output_file")
            cd "$JOSHUTO_CWD" || return
        case 102
            # Output selected files, no action
        case '*'
            echo "Exit code: $exit_code"
    end
end

`:`: opens the command prompt

this does not execute the command, but merely sets the text to it
Example: :cd / will open up the command prompt with cd / already written

`shell`: runs a shell command

%s and %p are substituted by a list of all selected files or by the file under the cursor, if none is selected
%d is substituted with the current directory's absolute path
When running the external program, the directory shown in Joshuto is set as “working directory”, the file names substituted for %s are given without path. If you want the absolute path, use %p.
Example: :shell touch file.txt will create a file called file.txt
Example for keymap.toml: To open all selected files with nvim, one can add a keybinding like this:
```
keymap = [ //..
   { keys = [ "e", "v" ], commands = ["shell nvim %s"] }
]
```

To set a wallpaper on sway using the absolute path of an image file:

keymap = [ //..
  { keys = ["m", "w"], commands = ["shell swaymsg output * bg %p fit"] }
]

`spawn`: runs a shell command in the background

Supports %s, %p and %d, just like the shell command.
Example for keymap.toml: To open all selected files or directories with sxiv, one can add a keybinding like this:
```
keymap = [ //..
   { keys = [ "i" ], commands = ["spawn sxiv -t %s"] }
]
```

To open a new alacritty terminal in the current folder:

keymap = [ // ..
  { keys = [ "O" ], commands = ["spawn alacritty --working-directory %d"] }
]

`suspend`: suspends the current session

can be mapped to Ctrl+z to behave similarly to other programs

`sort`: change the sort method

sort lexical: sort lexically (10.txt comes before 2.txt)
sort natural: sort naturally (2.txt comes before 10.txt)
sort mtime: sort via last modified time
sort size: sort by file size
sort ext: sort by extension
sort reverse: reverse the sorting

All methods (except reverse) support the --reverse flag:

--reverse=true applies sort method and sets reverse to true
--reverse=false applies sort method and sets reverse to false

`linemode`: change the line-mode (textual representation of files and directories in the “current view”)

linemode size: show the entry’s size (bytes for files, number of entries for directories) (default) ^✻
linemode mtime: show the entry’s modified time (aka. “mtime”) ^✻
linemode sizemtime: show the entry’s size and modified time ^✻

^{✻: file- or directory-name is shown on left, the respective meta-data is shown on the right, preceded by a symlink indicator}

`show_workers`: show the pending IO operations and the current progress

press escape to exit view

`toggle_hidden`: toggle hidden files

`line_nums`: switch displaying of entry numbers

line_nums 0 or line_nums none: disable displaying
line_nums 1 or line_nums absolute: enable absolute numbers for each entry
line_nums 2 or line_nums relative: enable numbers relative to selected entry

`flat`: flattens the directory view up to the specified depth.

flat 3: flatten directory up to 3 directories deep. depth of 0 corresponds to the current directory. its direct descendents have depth 1, and their descendents have depth 2, and so on.

`cursor_move_up`: moves the cursor up by x amount

cursor_move_up: moves the cursor up by 1
cursor_move_up x: moves the cursor up by x where x is a non-negative number

`cursor_move_down`: moves the cursor down by x amount

cursor_move_down: moves the cursor down by 1
cursor_move_down x: moves the cursor down by x where x is a non-negative number

`cursor_move_home`: moves cursor to beginning of directory list

`cursor_move_end`: moves cursor to end of directory list

`cursor_move_page_up`: moves the cursor up by `x`

where x is the number of items that can be seen on the screen

`cursor_move_page_down`: moves the cursor down by `x`

where x is the number of items that can be seen on the screen

`parent_cursor_move_up`: same as `cursor_move_up` but for parent directory

`parent_cursor_move_down`: same as `cursor_move_down` but for parent directory

`preview_cursor_move_up`: moves the preview up

`preview_cursor_move_down`: moves the preview down

`cd`: change directory

cd ..: go to parent directory
cd ~: go to home directory
cd -: go to previous directory in history (If it exists)

`open`: open file or directory

if joshuto does not know how to open the file format (via extension currently), it will prompt :open_with to open with a specific command
if xdg_open is true in joshuto.toml, joshuto will try to open it via xdg settings

`numbered_command`: opens a new mode where user can input numbers and jump to the specified location via hard-coded keybindings

numbered_command 3: initial input is 3

Tabs

`new_tab [--last] [--current|--cursor|dir]`: opens a new tab

new_tab, without any argument, opens a new tab with the default directory.

(Note: the default directory for new tabs is specified in joshuto.toml in the tab section.)

new_tab some-dir opens new tab with directory some-dir
new_tab --current opens new tab with the same directory as the current tab
new_tab --cursor opens new tab with the directory which is currently marked by the cursor
new_tab --last new tab will be placed at the end of the stack. This is the only flag that can be combined with the others described above.

`close_tab`: close current tab

`tab_switch`: switch to next/previous tab by `x`

where x is an integer
tab_switch 1: go to next tab
tab_switch -1: go to previous tab

`tab_switch_index`: switch to a given tab index

tab_switch_index 3: go to third tab if it exists, create one if it does not exist and there is already 3 - 1 = 2 tabs open

File Operations

`reload_dirlist`: reloads the current directory listing

`mkdir`: create a new directory (usually used as `:mkdir` )

`cut_files`: store selected files (or current file if none were selected) to be moved later

`copy_files`: store selected files (or current file if none were selected) to be copied later

`symlink_files`: store selected files (or current file if none were selected) to be symlinked later

--relative=true: relative symlink paths
--relative=false: absolute symlink paths

`paste_files`: move/copy files stored from a previous `cut_files` or `copy_files` command

`delete_files`: delete selected files (or current file if none were selected).

--foreground=true: will delete files in the foreground
--permanently: force permanent deletion regardless of use_trash value.
--noconfirm: files will be deleted without asking for confirmation (can be dangerous when use_trash is false)
will permanently delete files if use_trash is false in joshuto.toml/wiki/Configuration#joshutotoml)
if use_trash is true, joshuto will try to use the following command-line tools to try to put the files in the trash can instead of permanently deleting them
- gio trash
- trash-put: https://github.com/andreafrancia/trash-cli
- trash
- gtrash put

`rename`: rename the current file the cursor is on

:rename new_name

`rename_append`: opens the command prompt with the rename command and the current file name filled in.

cursor will be set to the end of the file name

`rename_append_base`: opens the command prompt with the rename command and the current file name filled in.

cursor will be set right after the base name of the file. (beginning of the file name if no base name)

`rename_prepend`: opens the command prompt with the rename command and the current file name filled in.

cursor will be set to the beginning of the file name

`rename_keep_ext`: opens the command prompt with the rename command and the extension of the current file filled in.

cursor will be set right before the extension of the file

`copy_filename`: copy the file name to clipboard

clipboard support requires xsel, xclip, or wl-copy

`copy_filename_without_extension`: copy the file name without the extension to clipboard

`copy_filepath`: copy the current file path to clipboard

`copy_dirpath`: copy the current directory path to clipboard

`set_mode`: Set read, write, execute permissions of current file

`touch`: create a new file or update the modified date of an existing file

Search and Selection

`search`: search the current directory via a string

`search_glob`: search the current directory via shell globbing (exact match)

:search_glob *.png

`search_regex`: search the current directory via regex (exact match)

:search_regex .+\.(jpg|png|gif)

`search_next`: go to next search result in the current directory

`search_prev`: go to previous search result in the current directory

`select`: select current file

--toggle=true: toggle the selected state rather than selecting the entry (default)
--toggle=false: select the current file (doesn't change anything if the current file is already selected)
--deselect=true: deselect rather than select the entry
--all=true: select/deselect/toggle all visible files in the current view. (Files not visible due to a set filter are not affected.)
when a pattern is given, joshuto selects files whose names contain the pattern
- select png

This example keybinding can be used for deselecting all files:

keymap = [ //..
   {keys = [ "x" ], command = "select --all=true --deselect=true"}
]

`select_glob`: select files in the current directory via globbing (exact match)

:select_glob --toggle=false '*.png'

This command has the same options for select. Notice that it's necessary to quote the pattern when spaces are contained.

`select_regex`: select files in the current directory via regex (exact match)

:select_regex --toggle=false '.+\.(jpg|png|gif)'

This command has the same options for select. Notice that it's necessary to quote the pattern when spaces and \ are contained.

`select_fzf`: select files in the current directory via fzf

This command has the same options for select. Use tab to select or deselect files in fzf.

`filter`: filter the current directory list.

:filter ca: filter the current directory and show only items with ca in the name

`filter_glob`: filter the current directory list via globbing.

:filter_glob *.png

`filter_regex`: filter the current directory list via regex.

:filter_regex .+\.(jpg|png|gif)

Options
- --type=string: change configurations of operations using substring matching
- --type=glob: change configurations of operations using glob matching
- --type=regex: change configurations of operations using regex
- --type=fzf: change configurations of operations using fzf
- when no option is added, type is set to string by default
Value
- insensitive
- sensitive
- smart

An example:

:set_case_sensitivity --type=fzf sensitive

this will create a file inside $TMP_DIR (or /tmp if $TMP_DIR is not set) and open up your text editor of choice via $EDITOR environment variable
once you've made your changes to the file, saved and quit, it will use the mv command to rename everything