A how-to manual: install, panels, moving around, search, copy/cut/paste, trash, select mode, zip and extract, the shell prompt, config.toml, cd on quit and scripting, all tested on a lab
superfile (the command is spf)
spf [PATH]...
superfile is a file manager that runs inside your terminal. It shows a sidebar, one or more file panels, a preview of the file under the cursor, file details, a clipboard and a list of running operations, all at once, and you drive it with the keyboard (arrow keys or vim keys). It is aimed at the moment when "ls, cd, ls, cd, cp" gets tedious but starting a desktop file manager over ssh is not an option. It is a single static program written in Go, so it installs by copying one file.
Every example below ran for real: superfile v1.6.0 on Ubuntu 24.04, in a Docker container, with the screen driven and read through tmux (a 120x30 terminal). Nerd Font icons were switched off so that the screens in this guide are plain text; with the default setting you see small icons next to the names. Things that need a graphical session or extra programs (image preview, the system clipboard, zoxide, exiftool) were not run in the lab and are marked as such.
Install it
The simplest install on any Linux box is to download the release tarball, check it and copy one file. The project publishes a checksums file next to every release:
$ curl -sLO https://github.com/yorukot/superfile/releases/download/v1.6.0/superfile-linux-v1.6.0-amd64.tar.gz
$ curl -sLO https://github.com/yorukot/superfile/releases/download/v1.6.0/superfile-v1.6.0-checksums.txt
$ grep linux-v1.6.0-amd64 superfile-v1.6.0-checksums.txt
d45b0e95072629a6aa7983a84eedca9cd7a98861e67ef91be1415496e3dda309 superfile-linux-v1.6.0-amd64.tar.gz
$ sha256sum superfile-linux-v1.6.0-amd64.tar.gz
d45b0e95072629a6aa7983a84eedca9cd7a98861e67ef91be1415496e3dda309 superfile-linux-v1.6.0-amd64.tar.gz
$ tar xzf superfile-linux-v1.6.0-amd64.tar.gz
$ sudo install -m755 dist/superfile-linux-v1.6.0-amd64/spf /usr/local/bin/spf
$ spf --version
superfile version v1.6.0
The two hashes must be identical. (On the arm64 build, replace amd64 with arm64.) Use the tarball name from the releases page for the version you want; the numbers above are the ones the lab used. The project also documents an install script, Homebrew, Go, Nix and packages for other systems at https://superfile.dev; those were not run here.
Nothing is installed anywhere else. The first start creates the configuration under your home directory (see "Where everything lives"). To remove superfile, delete the spf file and, if you want, those folders.
The first start and the screen layout
Run spf, or give it a folder: spf ~/projects. The very first start shows a welcome box with a few links; esc closes it (it is shown once).
$ spf
╭────────────────────╮╭───────────────────────────────────────╮ budget.csv
│ superfile ││ /home/demo │ notes.txt
│ │├───────────────────────────────────────┤
│ Home ││ (/) Type something │
│ Downloads ││> Documents │
│ Documents ││ Downloads │
│ Pictures ││ logs │
│ Trash ││ Pictures │
│ ││ projects │
│Pinned ─────────── ││ logs.tar.gz │
│ ││ │
│Disks ──────────── ││ │
│ ││ │
╰────────────────────╯╰──────────────┤^ Name├─┤Browser├─┤1/6├─╯
╭─┤ Processes ├──────────────────╮╭─┤ Metadata ├───────────────────╮╭─┤ Clipboard ├────────────────────╮
│ ││Name Documents ││ │
│ No processes running ││Size 4.00 KiB ││ No content in clipboard │
│ ││Date Modified 2026-10...000 UTC ││ │
│ ││Permissions drwxrwxr-x ││ │
│ ││Owner demo ││ │
│ ││Group demo ││ │
╰────────────────────────────────╯╰──────────────────────────┤1/7├─╯╰──────────────────────────────────╯
Reading the screen from the left:
the sidebar Home, Downloads, Documents, Pictures, Trash, then your Pinned folders and your Disks
the file panel the current folder, a search line, and the files. The > marks the cursor. Folders are listed first
the preview to the right of the panel: the text of the file under the cursor, or the contents of the folder
at the bottom three small panels: Processes (copy, move, compress jobs and their progress), Metadata (name, size, date, permissions, owner, group of the item under the cursor) and Clipboard (what you copied or cut)
the panel footer the sort order (^ Name means name, ascending), the mode (Browser or Select) and the position (1/6 means item 1 of 6)
The cursor wraps: down on the last item goes to the first. The folder size is only calculated in the Metadata panel when that panel has focus (press m), because adding up a big tree takes time.
Quit with q or esc. The catch: esc closes a prompt, a menu or a search box that is open, but when you are just looking at the list it quits the program.
Moving around
The keys are the arrows or the vim letters. Each action has two or more keys:
up, k cursor up
down, j cursor down
enter, right, l open the folder, or open the file (see "Opening files")
left, h, backspace go to the parent folder
pgup, pgdown one page up or down
tab, L focus the next file panel
shift+left, H focus the previous file panel
s, p, m focus the sidebar, the processes panel, the metadata panel (press the same key again to go back to the files)
f show or hide the preview
F show or hide the bottom panels (the footer)
. show or hide dotfiles (hidden files)
? the list of all hotkeys, on screen, at any time
A short walk, as it ran (cursor starts on Documents; four down keys reach projects):
$ spf
j j j j enter -> /home/demo/projects (api, web)
j enter -> /home/demo/projects/web (css, js, index.html)
h -> back in /home/demo/projects
Press ? whenever you forget a key. The help is a scrolling list that follows your own hotkeys.toml.
Search and filter
Press / to type in the search line at the top of the panel. The list shrinks as you type, in the current folder only:
/ then type: js
/home/demo/projects/web
js
js <- the only match; the panel footer says 1/1
enter keeps the filter and returns the keys to the list, with the cursor on the first match. esc inside the search box (before you press enter) clears the filter and the full list comes back. Careful: once you have confirmed with enter, the filter stays on, and esc then quits superfile (it did in the lab). To clear a confirmed filter, press / again and then esc.
The search looks at names in the folder you are in; it does not search subfolders. For a search through a tree, use the shell prompt (next sections) with find or grep, or a tool built for it.
Create, rename, copy, move and delete
These are the keys for everyday file work. The file operations act on the item under the cursor, or on the selected items in select mode (next section).
ctrl+n create a file or a folder
ctrl+r rename
ctrl+c copy (to the clipboard panel)
ctrl+x cut
ctrl+v paste (ctrl+w does the same)
ctrl+d move to the trash (delete also works)
D delete permanently
ctrl+p copy the full path of the item to the system clipboard
c copy the current folder path to the system clipboard
Create. ctrl+n opens a small box with the current folder. Type a name and press enter; end the name with a slash to make a folder (the box says: Add "/" transcend folders):
ctrl+n todo.txt enter -> a new empty file todo.txt
ctrl+n newdir/ enter -> a new folder newdir
ctrl+n todo.txt enter -> a second one is created as todo(1).txt, nothing is overwritten
Rename. ctrl+r turns the name into an editable line, with the cursor before the extension. Typing ZZ on index.html and pressing enter gave:
index.html -> indexZZ.html
Copy and paste. Move to the folder with the file, press ctrl+c, go to the target folder, press ctrl+v. The Clipboard panel shows the full path while you wait, and the Processes panel shows the job:
$ ls ~/Downloads
archive.zip backup.bin budget.csv <- after ctrl+c on Documents/budget.csv and ctrl+v here
Processes: Copied budget.csv 100%
Clipboard: /home/demo/Documents/budget.csv
A copy stays in the clipboard after pasting, so you can paste it into several folders. Cut works the same way, but the original disappears when you paste: ctrl+x on two files in Documents and ctrl+v in Downloads left Documents empty and Downloads with both files. If the name already exists in the target, the pasted file gets a (1) in its name.
Delete. ctrl+d asks first:
Are you sure you want to move this to trash can
This operation will move file or directory to trash can.
(enter) Confirm (q) Cancel
and D asks with a stronger warning ("This operation cannot be undone and your data will be completely lost."). The trash is the normal desktop trash of your account, so other tools can list and restore from it too:
$ ls ~/.local/share/Trash/files ~/.local/share/Trash/info
archive.zip archive.zip.trashinfo
A file removed with D never reaches that folder (it stayed unchanged after D in the lab).
Select mode: many files at once
Press v to switch the panel from Browser mode to Select mode (the panel footer says Select). Each item gets a checkbox, and the panel footer counts the selected items, for example Select(1). Move as usual, and mark items:
enter, right, l mark or unmark the item under the cursor
shift+down, J mark or unmark the item and move down
shift+up, K mark or unmark the item and move up
A select all items in this folder
v back to Browser mode
Then use any of the operations on the whole selection. As it ran:
in Documents: v A ctrl+x Clipboard lists both files:
/home/demo/Documents/budget.csv
/home/demo/Documents/notes.txt
in Downloads: ctrl+v -> Downloads has archive.zip backup.bin budget.csv notes.txt, and Documents is empty
Select mode, copy, cut, delete, compress (next section) and paste all work on the selection. Leave select mode with v before you move on. While it is on, enter, right and l mark the item under the cursor instead of opening it.
Zip, tar and extract
Two keys, no prompts:
ctrl+a compress the item under the cursor, or the selection
ctrl+e extract the archive under the cursor
Compress makes a .zip in the same folder, named after the first item. In select mode with both files marked:
$ ls ~/Documents
budget.csv budget.zip notes.txt
$ unzip -l budget.zip
14 2026-10-14 15:10 budget.csv
36 2026-10-14 15:10 notes.txt
2 files
Extract creates a folder named after the archive, next to it, and never mixes the files into the current folder. On archive.zip:
$ find ~/Downloads | sort
/home/demo/Downloads/archive
/home/demo/Downloads/archive.zip
...
A tar.gz works the same way: ctrl+e on logs.tar.gz, with a folder named logs already there, made logs(1), so the existing folder was not overwritten. Check what was in an archive before you trust it; extraction keeps whatever paths the archive holds (the test archive was built with absolute paths, so it produced archive/home/demo/Documents/..., a reminder that the folder name only protects the top level).
Sorting, panels and pins
Sorting. o opens the sort menu: Name, Size, Date Modified, Type and Natural. Choose with the arrows and enter; esc, o or ctrl+c closes it. R reverses the order. Natural sorting puts file2 before file10, which plain name sorting does not.
More than one panel. N opens another file panel in the same folder, n opens a new one, tab (or L) moves to the next panel, shift+left (or H) to the previous one, and w closes the focused one. Two panels give the classic "copy from here to there" layout: ctrl+c in one panel, tab, ctrl+v in the other. In the lab, N on /home/demo split the screen into two panels, each with its own folder and search line, and w closed the extra panel.
Pins. P pins the current folder to the Pinned section of the sidebar (and unpins it if it is already pinned). It pins the folder you are in, not the item under the cursor. The list is a small JSON file:
$ cat ~/.local/share/superfile/pinned.json
[{"location":"/home/demo","name":"demo"}]
The sidebar takes focus with s.
The shell prompt and the spf prompt
Two prompts live at the bottom of the screen, a shell and a command box for superfile itself.
: opens the shell prompt. Whatever you type is run by the shell in the folder of the focused panel, and the box reports how it ended:
: touch made-by-shell.txt enter
Success : Command exited with status 0 (No output)
$ ls ~
Documents Downloads Pictures logs logs.tar.gz made-by-shell.txt projects
You only get the exit status, not the command's output, so it suits actions (touch, mv, chmod, ln, git add) and not commands that are meant to print something. A failing command is reported with its status; a mistyped one in the lab said: Command execution failed ... /bin/sh: 1: q: not found. Press esc or ctrl+c to leave the prompt.
The prompt's own hint line says '>' - Get into SPF mode: a second mode of the same box that takes commands for superfile itself instead of the shell (the hotkey list calls it the SPF prompt). I did not get that mode to show in the lab, so I do not describe its commands here; the project documentation lists them. Because the shell prompt can run anything as you, a mistyped rm in it is as real as one typed in a terminal.
Opening files and editing
enter on a file opens it with the program configured for its type. e opens the file in your editor and E opens the current folder in your directory editor. The editor is the editor line of config.toml, and when that is empty it is the EDITOR variable. In the lab, with editor = "vi", e on notes.txt opened it in vi (inside the same terminal) and returned to superfile when vi quit.
To choose the program for an extension, add an [open_with] table to the very end of config.toml. The file path is added as the last argument:
[open_with]
txt = "logopen"
png = "feh"
pdf = "zathura"
Tested with a small script that only writes its argument to a log: enter on notes.txt ran it, and the log said
opened: /home/demo/Documents/notes.txt
The table has to be the last thing in the file, because TOML cannot close a table. One limit seen in the lab: this launches the program, but it is built for programs that open their own window (an image viewer, a PDF reader). A full-screen terminal program such as vi or less set here did not take over the terminal. Use e for terminal editors.
Preview. The right-hand preview shows the text of a file (the lab showed the lines of notes.txt and budget.csv) and the contents of a folder. According to the project documentation the built-in highlighter colours source code, and code_previewer = "bat" uses bat instead (colours could not be seen in the text capture). Images are previewed when the terminal can show them (not run in the lab). Press f to switch the preview off if it is slow on huge files.
Where everything lives
superfile asks itself:
$ spf path-list
[Configuration file path] /home/demo/.config/superfile/config.toml
[Hotkeys file path] /home/demo/.config/superfile/hotkeys.toml
[Log file path] /home/demo/.local/state/superfile/superfile.log
[Configuration directory path] /home/demo/.config/superfile
[Data directory path] /home/demo/.local/share/superfile
(spf pl is the short form.) What is in them:
~/.config/superfile/config.toml the settings (next section)
~/.config/superfile/hotkeys.toml every key, rebindable
~/.config/superfile/theme/ 21 themes, one file each, among them catppuccin-mocha (the default), dracula, gruvbox, nord, tokyonight, onedark, rose-pine and monokai
~/.local/share/superfile/ pinned.json plus small marker files (first use, footer on or off, dotfiles on or off)
~/.local/state/superfile/superfile.log the log: look here when something does nothing
Several options exist for trying a setup without touching your own: spf -c /path/config.toml and spf --hf /path/hotkeys.toml use other files. After an upgrade, spf --fix-config-file (--fch) adds new settings to your config.toml and spf --fix-hotkeys (--fh) adds new keys to hotkeys.toml, without changing what you set.
config.toml: the settings that matter
The file is commented line by line; the useful settings, with their defaults in v1.6.0:
theme = "catppuccin-mocha" pick any file name from the theme folder, without .toml
nerdfont = true false if your terminal font has no Nerd Font icons (you see empty boxes)
editor = "" empty means use $EDITOR
dir_editor = "" the program for E
default_directory = "." where to start; relative paths work
default_sort_type = 0 0 name, 1 size, 2 date modified, 3 type, 4 natural
sort_order_reversed = false
case_sensitive_sort = false
file_size_use_si = false false shows KiB/MiB (1024), true shows kB/MB (1000)
default_open_file_preview = true
show_image_preview = true
show_panel_footer_info = true
file_panel_extra_columns = 0 more columns next to the name when above 0
sidebar_width = 20 0 hides the sidebar
sidebar_sections = ["home", "pinned", "disks"]
transparent_background = false
code_previewer = "" "" built-in, or "bat"
auto_check_update = true checks once a day when you quit
cd_on_quit = false see the next section
shell_close_on_success = false close the : prompt after a command that worked
page_scroll_size = 0 0 means a full page for pgup/pgdown
zoxide_support = false needs zoxide installed
metadata = false needs exiftool, for detailed metadata
enable_md5_checksum = false needs md5sum
Change one with any editor and restart spf. The lab changed nerdfont to false (the screens in this guide) and editor to "vi" with sed, and both took effect on the next start:
$ sed -i 's/^nerdfont = true/nerdfont = false/' ~/.config/superfile/config.toml
If a line is missing after an upgrade, spf --fix-config-file adds it. To rebind a key, edit hotkeys.toml: each action has a list of keys, for example confirm = ['enter', 'right', 'l'] and quit = ['q', 'esc']. Keys must be unique among the global ones. Vim users should read the hotkeys page of the project's documentation first, since a few defaults (such as shift+h and shift+l for panels) differ from vim's.
cd on quit: leave the shell where you were
A program cannot change the directory of the shell that started it, so superfile writes the last folder into a file, and a small shell function reads it back. Put this in ~/.bashrc (zsh is the same; the project documents fish and PowerShell too):
spf() {
os=$(uname -s)
if [[ "$os" == "Linux" ]]; then
export SPF_LAST_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/superfile/lastdir"
fi
command spf "$@"
[ ! -f "$SPF_LAST_DIR" ] || {
. "$SPF_LAST_DIR"
rm -f -- "$SPF_LAST_DIR" > /dev/null
}
}
Then open a new shell. Quit with Q (shift+q) to change directory, or set cd_on_quit = true in config.toml to make plain q do it as well. In the lab, in a real bash session:
demo@lab:~$ pwd
/home/demo
demo@lab:~$ spf (j j j j enter to get into projects, then Q)
demo@lab:~/projects$ pwd
/home/demo/projects
The macOS path differs (the function in the project's documentation handles it); only the Linux branch was run here.
Using superfile in scripts
Two options turn superfile into a file picker for other programs.
spf --chooser-file FILE: when you open a file, superfile writes its path to FILE and exits instead of opening it.
$ spf --chooser-file /tmp/pick.txt ~/Documents (enter on the first file)
$ cat /tmp/pick.txt
/home/demo/Documents/budget.csv
The idea: a script or another tool starts spf this way, lets you browse, and reads the path from the file afterwards.
spf --print-last-dir (--pld): prints the folder you were in when you quit, on standard output, so a script can use it:
$ spf --print-last-dir ~/projects (enter on api, then q)
/home/demo/projects/api
Other options: --config-file / -c and --hotkey-file / --hf choose other files; --debug-info prints versions and paths for a bug report; --help lists them all:
Usage: spf [COMMAND] [OPTIONS] [PATH]...
Commands: path-list, pl help, h
Options: --debug-info --fix-hotkeys --fix-config-file --print-last-dir --config-file --hotkey-file --chooser-file --help --version
Cheat sheet
Start / quit spf [PATH] q or esc quit Q quit and cd (with the shell function) ? help
Move j k or arrows enter or l open h or backspace parent tab/L next panel shift+left/H previous
Panels N split here n new panel w close s sidebar m metadata p processes f preview F footer
Look . dotfiles o sort menu R reverse sort / search (esc clears) P pin this folder
Create / rename ctrl+n new file (end with / for a folder) ctrl+r rename
Copy / move ctrl+c copy ctrl+x cut ctrl+v paste
Delete ctrl+d trash D permanent (both ask first)
Select v select mode enter mark J K mark and move A all v leave
Archives ctrl+a zip the item or the selection ctrl+e extract
Open enter open (open_with) e editor E folder in editor
Paths ctrl+p copy file path c copy folder path
Prompts : shell command in this folder (status only, no output)
Options spf pl paths spf --fix-config-file spf --chooser-file F spf --print-last-dir
Common problems
Boxes or odd symbols instead of icons the terminal font is not a Nerd Font: set nerdfont = false in config.toml, or install a Nerd Font and select it in the terminal
The screen is garbled or too small superfile needs room for its panels: make the window at least about 110 columns by 26 rows, or press F to hide the bottom panels and f to hide the preview
esc quit the program esc quits when you are just looking at the list, and after a confirmed search. Clear a search before confirming it, or press / and then esc
Nothing happens when I press enter on a file no program is set for that type: add it under [open_with], or use e to edit. The log file ~/.local/state/superfile/superfile.log shows errors
A terminal editor will not start from open_with open_with is for programs that open their own window; use e (editor = "vi" or $EDITOR)
Pasted file got (1) in its name a file with that name was already there: nothing was overwritten
I deleted something with D it is gone, D does not use the trash. Use ctrl+d by default
Could not copy a path ctrl+p and c use the system clipboard, which needs a graphical session (or a clipboard tool such as xclip or wl-copy). On a bare ssh session there is none; this was not run in the lab
Config line missing after an upgrade spf --fix-config-file and spf --fix-hotkeys add the missing lines
Keys do something else in select mode leave select mode with v before navigating
Preview is slow on a huge file f toggles the preview off
Tips
Learn three keys first: ? (help), / (search) and ctrl+v/ctrl+c. Everything else you can look up in the help.
Use ctrl+d, not D. The trash is free insurance. Keep D for files you are sure about.
Leave select mode with v before moving on. Half of the "why did that happen" moments are a forgotten select mode.
Put the cd-on-quit function in .bashrc on day one. It makes superfile feel like part of the shell instead of a detour.
Pin the folders you visit every day with P, and use the sidebar (s) to jump to them.
Use two panels (N) for copying between folders instead of copying, walking and pasting.
Compress before you move a big folder over a slow link: select, ctrl+a, send one file. Extract with ctrl+e at the other end, and look inside first.
Edit config.toml once: theme, nerdfont, editor and sort order are the four that people change.
When something does nothing, read ~/.local/state/superfile/superfile.log. It is short and it usually says why.
superfile is a convenience, not a replacement for the command line: for a big recursive job, find, rsync and tar are still the right tools. Use the : prompt to run them in the folder you are looking at.
