F:st is a file manager that runs in your terminal.
In project management there is an iron law: “Cheap, fast, good. Choose two”.
Miraculously, f:st manages to escape this law. Its motto goes something more like this: "Free, fast, good... simple, extensible, customizable, minimalistic, powerful, versatile, consistent, cohesive, flexibile, efficient, modular, portable. Take all of them!".
It is a program at once as revolutionary as a comet, and as familiar as an old sock. It takes the greatest ideas for command-line tools in recent history, and combines them into a cohesive experience that makes interacting with the filesystem so fluid, so efficient it will feel like you were born in it, moulded by it. Once adopted, the only barriers that remain will be those imposed by your own thoughts; and if you ever again return to the old ways, you will be blinded by their slowness.
It all starts with the pane, a dropdown list of all the items in your current directory. Type to filter, navigate with the arrow keys, a preview window to the side shows you the contents of the files, press alt-h to show a dynamic help menu with all available actions, and you can even use your mouse1. Everything that should run asynchronously does, so that the UI never stutters, and all effects are accompanied by toasts, so that you always know what exactly is going on.
All the rest of this app revolves around this interface, providing efficient ways to navigate, robust and optimized filesystem primitives2, smart previews, recents tracking, alterrnate views & lists, and a system for contextual actions. All of this on the same interface, with the help menu only ever being one keypress away, the net effect being that everything is within the reach of a few taps and nothing is overwhelming.
Install the required dependencies:
cargo install fd-find ripgrep
# (optional)
cargo install bat eza kreuzberg mediainfo
# If you don't have cargo, all of these are available on almost any package manager of your choiceGet the binary with the install script (or choose one of the options below)
curl -fsSL https://raw.githubusercontent.com/Squirreljetpack/fist/main/install.sh | shpowershell -ExecutionPolicy Bypass -c "irm https://github.com/Squirreljetpack/fist/releases/latest/download/fist-installer.ps1 | iex"Call as:
fs: Directory navigationfs [..paths] pattern: interactive findz [query]: directory jump (requires shell integration)
Finally, when you're ready, initialize the configuration files, and download some menu actions!
fs --dump-configbrew install Squirreljetpack/tap/fistyay -S fist-bin
npm install -g @squirreljetpack/fistBuild from a clone3:
git clone https://github.com/Squirreljetpack/fist
cd fist
cargo build --releaseUp/Down: Navigate (orUpin the initial position to to enter prompt).Left/Right: Back/Enter.Enter: Default (system) open.Alt-Enter: Print / Alternate open.Ctrl-Enter: Open in background.alt-n: Reveal (in editor).
ctrl-f/ctrl-r: Find files / Search text.ctrl-g: History view (Folders and files).ctrl-z/alt-z: Undo / Redo.
ctrl-x/ctrl-c/ctrl-v: Move, Copy, Paste.ctrl-y: Copy the path.delete/shift-delete: Trash/Delete.alt-e: Open menu.alt-u: Open queue.alt-p: Open options.ctrl-s/alt-h: Toggle hidden.ctrl-d: Cycle filter/sort.
Tab: Toggle select.alt-enter: Print.?: toggle preview.alt-/: toggle informative preview.ctrl-l: Maximize preview.alt-l: Maximize extended preview./and~: Jump to homectrl-1..ctrl-9: JumpOrAcceptalt-space: JumpOrAccept(prompt)ctrl-space,alt-hyphen: toggle prompt lock
For a full list of binds, press alt-h within the app4.
Documentation for configuration can be found in config.md, mm.md.
You can also get it straight from the source: Main Config, Panes, Styling, Miscellaneous UI, Lessfilter, Lessfilter, Matchmaker Config.
fs :tool check checks your configuration files and installed menu actions for errors.
To begin, call fs without any positional arguments.
Once inside, you can navigate and re-enter from other panes by pressing the left/right arrow keys (corresponding to the Parent/ Advance actions).
Note
The following describes what is probably the least straightforward feature of F:st. Hopefully, it will make more sense when you start to use it. If not, the behavior comes from a block of bind definitions in mm.toml5 that you can delete to disable.
F:st binds left/right to actions to emulate a traditional file manager experience and to keep all the (most useful) navigation keys together. Unfortunately, because the prompt is also available for typing, the ForwardChar/BackwardChar actions end up bound to shift-left/right, and this can be a bit unexpected at first. To prevent accidents in query-reliant panes like Find or Search, the query bar locks when entering these panes: indicated by a red underline. When the prompt is locked, the left/right and shift-left/right keys switch roles, so that left/right reverts to only moving the caret in your query.
On macos, cmd+delete also returns to DeleteWord instead of Trash.
The locked state can also be entered by entering the prompt -- pressing up at the first result, (or down at the last with results.cycle). Note that in_prompt ⇒ locked_prompt: in this state, the prompt displays your current directory, and all actions apply to that instead. To exit the prompt, just press up or down again. To toggle the locked state, press ctrl-space or alt-hyphen6 -- but this is not often necessary. alt-space jumps to the locked cwd and then accepts it.
You can search through all files recursively by
- using the subcommand:
fs :: [OPTIONS] [PATHS]... [PATTERN] - by calling
fsdirectly with the same arguments - or by triggering the
Findaction (ctrl-f) in-app.
The results will be available for filtering, navigating, editing, previewing etc. Filtering and sort order can be adjusted through the Options overlay.
Note
f:st uses fd for this internally, and that search parameters can be passed through directly following --. However, it is not a strict wrapper and several differences in behavior in the command specification exist:
- The last positional argument is treated as the query instead of the first
- queries beginning with
.auto-enables the inclusion of hidden files - Default parameters, directory-specific ignores, and other parameters can be set in the config.
- The
-t(type) flag has be overloaded to support more conditions. In addition to file types (directory/d, symlink/l, ..etc.), it now supports extensions (-t .ext), pre-set categories (image/i, video/v), and custom categories as well.
You can perform a full text search
- using the subcommand:
fs : [OPTIONS] [PATTERNS]... [-- <RG_ARGS>...] - or by triggering the
Searchaction (ctrl-r) in-app.
In f:st, each result displays two columns: the filepath, and a context column7.
In this pane, the context column contains the query matches and surrounding context.
This pane operates in a query and a filter mode, which can be switched between with ctrl-r:
- In query mode, the results are populated with all text matches of a your main query.
- In filter mode, the results are filtered to only lines matching your filter query.
- By default, the filter applies to the main (first) column. This allows you to easily look for all text matches restricted the results to a specific file extension or pattern8.
- In query mode, multiple queries (results must match at least one) are seperated by whitespace. Queries containing whitespace can be grouped together by single quotes. Single quotes can be escaped as
\'. - The default mode treats the given queries as regexes (as opposed to the filter input, which does not).
Note
When the active item is advance/executed on, the matched line and column are saved in the environment variables HIGHLIGHT_LINE and HIGHLIGHT_COLUMN. If your $EDITOR is supported, the Lessfilter::Edit action (which advance dispatches to) automatically opens the file to the corresponding position (you can also configure this manually).
f:st can also accept arbitrary lists of files from a command or input stream through the :custom subcommand (fs :custom [CMD]..., where an empty command reads from stdin), where all the usual operations are available:
- directory traversal
- file create/edit/delete/custom actions relative to the current item/directory.
- enriched display
- full text search
- reversible actions
- preview
- filtering and sorting
- and so on.
A complete example of a notes manager this can be used for can be found here.
f:st records the files, directories and applications that you've visited in a local database, where they are displayed in the Files/Folders (ctrl-g) and Apps panes, sorted by relevance9.
The Files and Folders panes are most useful when integrated into the ambient context where you usually access files. For example, the shell, or a command launcher.
PushStash(name) adds the selection (or the current directory while the cursor is disabled) to a named stash, and OpenStash(name) switches to its pane. Stash panes are transient or database-backed collections of paths, useful for scratch space or bookmarking.
By default, alt-s and alt-b are bound to "smart" Stash(name) actions for the default (transient) and bookmark (persistent) stashes:
- if items are selected, they are pushed
- if you are already in the stash, it backs you out
- otherwise, it enters the stash pane
Note
Combined with contextual Menu actions, they are f:st's answer to all cross-directory workflows, such as comparing files and folders, archiving, or bulk-renaming: just push everything to the stash and run your action on there.
The apps pane comes prepopulated from the existing applications on your system, and can be accessed either through
fs :o -w [..FILES]on the command-line- the
open withmenu action - a custom binding for the
Appaction.
It can be used to select a launch method for a given set of files (provided through the command line, or collected in the app view's pending files).
Every pane has a Options overlay (alt-p), with settings for filtering, sorting, and other pane-specific controls for the displayed results.
Selecting a sort does not interrupt the current results; items are resorted on the fly. The active sort key is displayed on the right.
Panes can also configure a default sort. This applies a soft sort to the results: the ordering reflects a combination of query relevance and the sort order. The sort key is not displayed when soft sorting is active. In the Files/Folders/Apps/Search panes, sorting is always soft: the initial ordering is still faithful to the sort key.
Panes can be navigated between using the Undo/Redo actions.
For more information on any of the panes, run fs [pane] --help with the appropriate subcommand (i.e. :rg), trigger the in-app help menu, or consult the docs.
The Menu (alt-e) houses all the actions available in the current context.
Custom actions can be added in actions.toml and from files in actions/. They consist of 3 parts:
- Action: The lua script to execute.
- Conditions: The various conditions which must be satisfied to show this action in the menu.
- Execution: Parameters controlling how the action is executed.
You can find a couple official actions here, providing contextual actions for compression and comparison (of files/folders). Just download them into <FIST_CONFIG_PATH>/actions to enable them.
For more information, consult the docs.
Another way to define arbitrary execution flows is by adding to the [binds] section in your mm.toml configuration file10.
A typical binding looks like this:
"tab" = ["ToggleSelection", "Down"]
where a key is bound to a sequence of actions11. The full list of actions is available here, a couple the ones you may be interested in for customization are:
Lessfilter: Execute an action on the current item according to lessfilter rules.Preview/LfPreview/RunPreview/ShowPreview: Change the preview display, run or maximize the current Preview.- The
Execfamily: run a command and wait for it/forget about it/display it in pager/copy it/transform f:st into it (Become($EDITOR {})) etc. - Queue-related actions, as mentioned below.
For example, the default mm.toml binds Ctrl-Esc to Execute($SHELL): the inner string is executed in your shell environment, allowing you to drop into a shell from your current directory in f:st.
Moreover, f:st uses the same system for bindings as matchmaker, with only the app-specific actions differing. This entails some niche but maybe cool features, such as that not only keys, but events can be bound to, and also that bindings can also be mode-specific, such as being present only on certain pane types, or when the prompt is locked.
The Queue overlay (alt-u) lists the pending file operations. Rows show their kind, source, destination, and progress, and can be edited, rearranged, cancelled, filtered, removed and executed from the overlay.
The Move and Copy12 actions enqueue items under the move and copy kinds. Paste (ctrl-v) executes every queued copy, move and symlink item without enterring the overlay, transferring files into the active directory. The other relevant actions are: ExecuteQueue(selector), Enqueue(kind) and ClearQueue(selector)13.
Menu actions with the Queue/Enqueue/QueueBatch strategies enqueue their targets under the action's key. On execution the action's lua script runs once per queued item with (paths, to, nav_cwd?)14.
f:st comes with several secondary subcommands for reference and utilitary purposes. They can listed with fs :tool.
The output of fs :tool shell will, when sourced, provide the jump, nav, history-open, and interactive line-editor widget functions:
eval "$(fs :tool shell)"fs :tool shell --shell=fish | source# 1. Generate the script once in your terminal:
fs :tool shell --shell=nu | save -f ~/.config/nushell/fist.nu
# 2. Add to your config.nu ($nu.config-path):
source ~/.config/nushell/fist.nuThe jump function (z) is a replacement for cd, except that incomplete queries are matched to a most likely destination drawn from the unified f:st database. This behavior is inspired by zoxide15.
Note
In addition, a couple special queries can be used to start an interactive search:
- the only argument is a valid path:
cd. - no arguments: interactively select from history.
- last argument is
.: interactively search subdirectories of the best match. - a valid path directly before a trailing
././is that pane's target rather than a query. - otherwise: cd into the best match for the search term (if one exists)16.
One final change from zoxide is the introduction of the history.refind setting.
When no match is found, or when the top result is the current directory, this setting automatically start the interactive interface.
The open function (Z) brings a similar functionality to files, opening17 matches from your file history (open directories with a trailing .).
The line-editor widget functions push your selected paths onto your command line. By default, shift-left binds to recursive directory search, shift-right binds to recursive file search. There is also a full-text search widget bound to shift-down: the default action opens your editor at the match, but you can still push paths using alt-enter.
To disable any function/widget, just set its bind to an empty string.
Note
These are also fzf's default keybinds (and function similarily), so it's recommended to disable those when using f:st.
Also, before adding them to your shell startup, you can also run the output directly to try them out. On POSIX shells, this is just eval "$(fs :tool shell --myshell)".
Including the --aliases flag will add a few simple alias definitions into the initialization:
- lessfilter
lz: directory displayl: lessfilter (display preset)la: lessfilter (extended preset)ll: lessfilter (info preset)n: edit (lessfilter with edit preset)o: open
For speed and safety, it is recommended pass your actual shell through to --shell18.
The previewer is controlled by the lessfilter tool.
The lessfilter tool dispatches to 9 presets:
preview: the preview panedisplay: terminal displayextended: terminal interaction or verbose displayinfo: metadata and raw informationopen: system openedit: editingalternateandalternate2: extra presets for custom use
Images are rendered using the best supported graphics protocol of your terminal (sixel, kitty, or iTerm2), falling back to Unicode halfblocks otherwise.
Each preset is configured by a rules table in the config file. Each rule is a pair (Actions, Patterns), and for a given file, the rule whose patterns score the highest is selected -- its actions are invoked on the target file.
The score modifiers and their prefix syntax are:
>n|pattern:Max(n)— take the max of the current score withn.- The minimal syntax
n|(such as1|cat:...) is also supported.
- The minimal syntax
<n|pattern:Min(n)— take the min of the current score withn.+n|pattern:Add(n)— addn(or 1) to the current score.-n|pattern:Sub(n)— subtractn(or 1) from the current score.^|pattern:Req— require the condition; sets the score to 0 if the test fails.^patternis also supported.
The patterns and their default scores (used when no score prefix is specified) are:
glob: match the full path —Max(50)child: match a child name (or a sibling name for a file) —Max(50)ext: match a file extension —Max(30)mime: match a MIME type such astext/plainorimage/*—Max(20)cat: match a built-in or configured file category —Max(20)application: match a platform-specific application bundle, launcher, or executable —Max(60)*: match any path —Max(0)have: require an executable to exist —Reqfiletype: require a matching filesystem type —Reqgit: require a path inside a Git work tree —Req
Though the syntax has many parts, configuration should be fairly straightforward. f:st comes with a sane set of defaults with wide coverage for a variety of filetypes, and declaring overrides is as simple as declaring the desired action together with the conditions which it requires. For example:
### --- lessfilter.toml -- ###
preview = [
# ...
# On an file with mime-type sqlite-3 and a system with sqlite3, this rule gets a score of 20.
# sqlite is a custom action whose definition can be found in the default lessfilter.toml configuration file.
[["sqlite"], ["application/vnd.sqlite3", "have:sqlite3"]],
# ...
]
# When invoking the edit action (in `fist` or through the `n` alias),
# any file belonging to this category will be opened with the system's default preferred application.
# Since this rule has minimal priority (at most 1), any subsequent rule will override it.
edit = [
[
["Open"],
[
"1|cat:document",
"1|cat:spreadsheet",
"1|cat:email",
"1|cat:academic",
],
],
]The built-in actions are:
DirectoryApplicationTextImageExtractMetadataOpenHeaderNone
Additional actions can be defined via the same same shell + templating syntax as actions under [bind]. For example:
[rules]
alternate = [
[["code"], ["*/*"]],
]
[actions]
code = 'code --add {}'Note that certain default previews will not display without the required dependencies.
If something is not resolving properly, fs :tool lessfilter --diagnose <PATH> shows you how and why your configuration resolves as it does on a given file.
A list of all supported types, used by the -t parameter of the find subcommand and the cat condition of the lessfilter.
fs exposes several of the more generally useful functionalities it uses internally:
-
diskspace: A stupid fast parallel directory tree/size lister, using the same background worker that is used in the main app for sorting by size. -
trash: cross platform tool for easily moving files to the system trash. -
pager: smart compatible pager that feedsbatfor syntax highlighting intominusfor modern aesthetics. -
action: run a menu action directly -
check: verify your configuration -
as for the rest, run
fs :toolto see a full listing.
fist integrates into CommandSpace, which you may also enjoy checking out.
-
Remove binary:
# Installed via cargo: cargo uninstall fist # Installed via install script: rm -f ~/.cargo/bin/fs /usr/local/bin/fs
-
Remove shell integration:
- Bash / Zsh / POSIX: Remove
eval "$(fs :tool shell)"from~/.bashrcor~/.zshrc. - Nushell: Remove
source ~/.config/nushell/fist.nufrom~/.config/nushell/config.nuand delete~/.config/nushell/fist.nu. - Fish: Remove
fs :tool shell --shell=fish | sourcefrom~/.config/fish/config.fish.
- Bash / Zsh / POSIX: Remove
-
Remove configuration, state, and cache:
rm -rf ~/.config/fist ~/.local/state/fist ~/.cache/fist
Help is plentiful and always readily accessible: in the user documentation, from the command line via --help, or in-app via alt-h.
F:st is licensed under the GNU Affero General Public License, version 3. See LICENSE.
Footnotes
-
We hope you have a grand time with clicking, dragging, and scrolling. ↩
-
Fast and error-proof copying, transparent decompression, re-filtering/sorting that runs on the fly etc. ↩
-
f:st depends on patched crates, so it must be cloned and built in place;
cargo install fistcannot apply those patches. ↩ -
For more information on bindings (how they are defined, key testing, and default generic binds), see matchmaker. ↩
-
One of the guiding heuristics of the project is to provide the best out-of-the-box experience through opiniated defaults, but full power should always remain with the user: underneath the surface, everything is customizable or extensible. ↩
-
necessarily, this will also drop you out of the prompt if you were in it ↩
-
In the previous panes, the secondary column was simply empty and therefore not displayed. ↩
-
To switch to filtering the second column, type
%(i.e.path_filter % context_filter). ↩ -
frequency, recency, and similarity to query. ↩
-
fs --dump-configto initialize it ↩ -
These are code-styled and camel-cased throughout this document (i.e.
PushStash). ↩ -
This action also copies the file to your system clipboard. ↩
-
selectoris similar tokind, but with the addition of the reserved stringsall(default),first,last, andbuiltins(i.e. Paste is justExecuteQueue(builtins)). Enqueue(kind) enqueues the current selection under the referenced kind (for custom actions, the conditions must be satisfied). ↩ -
f:st uses an improved implementation by default I adopted after seeing this project, although the simple zoxide implementation can be enabled by disabling lambda:
Event clock: zoxide score decay is coupled to wall-clock time. The problem is that after any extended period of inactivity, all scores decay toward zero, and the first directories visited on return immediately dominate the ranking regardless of prior history. f:st replaces wall-clock time with an event clock: each cd action advances the clock by one tick. The clock stands still during inactive periods and no score decay occurs during such periods.
Scoring: Items are sorted by score. In zoxide, the score is computed as count * recency bucket. f:st replaces this with a monoexponential decay kernel. The decay rate is controlled by
lambda(default8e-3, equating to a half-life of about 87 actions).Unified database: f:st maintains a single SQLite database tracking files, directories, and applications together.
Pruning: Pruning happens automatically and lazily once db exceeds a certain size. For more information, see
fs :tool bump --help.Interactive fallback: When no match is found, or when the top result is the current directory, f:st can be configured to start an interactive search interface instead of failing. ↩
-
using the lessfilter edit preset. ↩
-
Another optimization you can make is to cache the generated command: my zcomet fork supports this. ↩












