Skip to content


leo-arch edited this page Jun 27, 2022 · 309 revisions
Clone this wiki locally

CliFM Specifics

Table of contents


The following variables are read at initialization time:

Variable name Description
CLIFM_FILE_COLORS A colon separated list of file type color codes in the same form specified in the colors section
CLIFM_EXT_COLORS Same as above, but for file extensions
CLIFM_IFACE_COLORS Same as above, but for different elements of CliFM's interface
NO_COLOR Instructs CliFM to run colorless
CLIFM_NO_COLOR Instructs CliFM to run colorless
CLIFM_FORCE_COLOR Force CliFM to use colors (even if the terminal informs that it does not support colors)
CLIFM_FILTER Define a files filter. If set, this variable overrides the Filter option in the configuration file
CLIFM_SUDO_CMD Define the authentication program to use (mostly used to mount an archive or by the prepend-sudo function, by default bound to Alt-v). If not set, defaults to sudo (or doas, if compiled on OpenBSD)
FZF_DEFAULT_OPTS Options to be passed to FZF (if used for TAB completion)

Except when running in stealth mode, CliFM sets the following environment variables:

Variable name Description
CLIFM This variable is set to the path of the configuration directory. By inspecting this variable other programs can find out if they were spawned by CliFM. It can also be used to quickly jump into the configuration directory: cd $CLIFM or just $CLIFM
CLIFM_PROFILE This variable is set to the current profile of CliFM (if using two or more instances of CliFM under different profiles, the last one will be used). Specially useful to develop CliFM plugins on a per profile basis
CLIFM_SELFILE The path to the current selection file
CLIFM_COLORLESS Set to 1 if running colorless (either via the NO_COLOR or CLIFM_NO_COLOR environment variables, or the --no-color command line option)
CLIFM_PLUGINS_HELPER Location of the plugins-helper file
CLIFM_BUS This variable contains the path of a pipe by means of which plugins can talk to CliFM. See the plugins section for more information.

If Notifications is set to false for the current prompt (see the prompt page for more information), the following environment variables are set to the corresponding value, allowing the prompt string itself to handle this information:

Variable name Description
CLIFM_STAT_SEL Current amount of selected files
CLIFM_STAT_TRASH Current amount of trashed files
CLIFM_STAT_ERROR_MSGS Current amount of error messages
CLIFM_STAT_WARNING_MSGS Current amount of warning messages
CLIFM_STAT_NOTICE_MSGS Current amount of notice messages
CLIFM_STAT_WS Current workspace number
CLIFM_STAT_EXIT Exit code of the last executed command
CLIFM_STAT_ROOT 1 if user is root (UID = 0), 0 otherwise
CLIFM_STAT_STEALTH 1 if running in stealth mode, 0 otherwise

Note: Besides these environment variables, escape codes for state information are also available. See the prompt section referenced above.


NOTE: If $XDG_CONFIG_HOME is not set, $HOME/.config/ is used instead.


The configuration file is $XDG_CONFIG_HOME/clifm/profiles/PROFILE/clifmrc. It will be copied from DATADIR/clifm (usually /usr/local/share/clifm), and if not found, it will be created anew with default values. In this file you can permanently set up CliFM options, define aliases, prompt commands, and autocommands.

The following is the list of options provided by the configuration file:

Option Default value Description
ApparentSize false Print files apparent size instead of actual device usage (Linux only)
Autocd true If set to true, a command name that is the name of a directory is executed as if it were the argument to the cd command: DIR works just like cd DIR
AutoLs true Should files be listed automatically when changing the current directory?
AutoOpen true If set to true, a command name that is the name of a file is executed as if it were the argument to the open command: FILE works just like open FILE
AutoSuggestions false If set to true, enable the auto-suggestions system. See also the SuggestFiletypeColor and SuggestionStrategy options
ExpandBookmarks false If set to true, expand bookmark names into the corresponding bookmark path: if the bookmark is name=/path, name will be interpreted as /path. TAB completion is also available for bookmark names
CaseSensitiveList false Enable case sensitive listing for files in the current directory
CaseSensitiveDirJump false Enable case sensitive lookup for the directory jumper function (via the j command)
CaseSensitivePathComp false Enable case sensitive completion for file names
CaseSensitiveSearch false Enable case sensitive searching (via the quick search function)
CdOnQuit false Write the last visited directory to $XDG_CONFIG_HOME/clifm/.last to be later accessed by the corresponding shell function at program exit
Classify true If running with colors, append directory indicator and files counter to directories. If running without colors (via the --no-colors command line option), append file type indicator at the end of file names.1 Bear in mind that when running in light mode the check for executable files won't be performed, and thereby no indicator will be added to executable files
ClearScreen true If set to true, clear the screen before listing files
ColorScheme default Color schemes are stored in the colors directory. By default, the default color scheme is used. Visit to get some more
cpCmd 0 Set the default copy command. Available options are: 0 = cp, 1 = advcp, and 2 = wcp. Both 1 and 2 add a progress bar to cp
DirhistMap false If set to true, print a map of the current position in the directory history list, showing previous, current, and next entries
DiskUsage false Print the disk usage of the file system the current directory belongs to
ExternalCommands true Should CliFM be allowed to run external, shell commands?
FilesCounter true The amount of files contained by a directory is informed next to the directory name (see the interface section). However, this feature might slow things down when, for example, listing files on a remote server. The files counter can be disabled here, via the --no-files-counter option, or using the fc command while in the program itself
Filter unset Use a regular expression to filter file names when listing files. Example: !.*~$ to exclude backup files (ending with ~), or ^\. to list only hidden files
FullDirSize false When running in long view mode, print the size of directories and their contents
Icons false Enable/disable icons
LightMode false Enable the light mode to get some extra performance. See the speed and performance section for details
ListDirsFirst true Whether to list directories first or not
ListingMode 0 How should files be listed. This option accepts two values: 0 (vertically - ls(1)-like), and 1 (horizontally)
LongViewMode false List files properties next to file names instead of just file names
LogCmds false Keep a record of both external commands and internal commands able to modify the files system (e.g. r, c, m, and so on)
MaxFilenameLen unset Maximum file name length for listed files. File names larger than MaxFilenameLen will be trimmed at MaxFilenameLen using a tilde. If unset, no file name is trimmed. If running in long mode this setting is overridden by MinFilenameTrim
MaxDirhist 100 Maximum amount of visited directories to remember
MaxHistory 1000 Maximum amount of commands to remember
MaxLog 500 Maximum amount of logs to keep
MaxPrintSelfiles 0 See description for PrintSelfiles below
mvCmd 0 Set the default command to move files. Available options are: 0 = mv, and 1 = advmv. 1 adds a progress bar to mv
MaxJumpTotalRank 100000 When the sum of all ranks in the jump database reaches MaxJumpTotalRank, all ranks will be reduced 10%, and those falling below MinJumpRank will be deleted (exception made of directories in workspaces, bookmarked and pinned directories)
MaxPath 40 MaxPath is only used for the /p option of the prompt: the current working directory will be abbreviated to its basename (everything after last slash) whenever the current path is longer than MaxPath
MinFilenameTrim 20 Minimum length at which a file name can be trimmed in long view mode (including ELN length and spaces). If running in long mode this setting overrides MaxFilenameLen
MinJumpRank 10 When a directory rank in the jump database falls below MinJumpRank, it will be forgotten (exception made of directories in workspaces, bookmarked and pinned directories)
Opener Choose the resource opener to open files with their default associated application. If not set, Lira, CliFM's built-in opener, is used
Pager false Enable Mas, the files list pager
PrintSelfiles false If set to true, always print the list of selected files. Since this list could become quite extensive, you can limit the number of printed entries using the MaxPrintSelfiles option (-1 = no limit, 0 = auto (never print more than half terminal height), or any custom value)
RestoreLastPath false If set to true, start CliFM in the last visited directory (and in the last used workspace). This option overrides StartingPath
RlEditMode 1 Set readline editing mode: 0 for vi and 1 for emacs
SearchStrategy 2 CliFM provides three search strategies: 0 = glob-only, 1 = regex-only, and 2 = glob-regex. This applies to the quick search function.
ShareSelbox false Should the Selection Box be shared among different profiles?
ShowHiddenFiles false Whether to show or not dot-files (file names starting with a dot)
Sort 1 Choose sorting method. Only numbers are allowed
SortReverse false By default, CliFM sorts files from less to more (ex: from 'a' to 'z' if using the name method). To invert this ordering, set SortReverse to true (you can also use the --sort-reverse command line option or the st command)
SplashScreen false Print CliFM's logo screen at startup
StartingPath Current working directory Specify CliFM's starting path. This option is overridden by RestoreLastPath
Suggestions true Enable auto-suggestions
SuggestFiletypeColor false It set to true, suggest file names using the corresponding file type color (as specified in the color scheme file) instead of the default one (defined by the sf code in the color scheme file). See the suggestions page
SuggestionStrategy ehfjbac A list of checks to be performed when looking for possible suggestions. See the suggestions page
SyntaxHighlighting true Enable/disable syntax highlighting
TabCompletionMode The method used to display possible completions. Available options: standard and fzf. If unset, defaults to fzf, and, if the fzf binary is not found in PATH, it falls back to standard. Consult the TAB completion section
TerminalCmd 'xterm -e' Only used when opening a directory via a new CliFM instance (with the x command), this option specifies the command to be used to launch a terminal emulator to run CliFM on it
Tips true Print a usage tip at startup
TrashAsRm false If set to true, the r command executes trash (see the Trashing files page) instead of the rm shell command to prevent accidental deletions
Unicode true Whether to be Unicode aware or not. If using a 100% ASCII setup (e.g. English), you can turn this off
WelcomeMessage true Print a welcome message at program startup

1 List of file type indicators:

Indicator File type
/ Directories
@ Symbolic links
= Sockets
| FIFO/pipes
* Executable files
? Unknown file types


The profile file is $XDG_CONFIG_HOME/clifm/profiles/PROFILE/profile.cfm. In this file you can add those commands you want to be executed at startup, even before files listing. You can also permanently set here some custom variables (enable the use of internal variables using the --int-vars command line switch). For instance:


This variable may be used as a shortcut to the specified directory, for instance: cd $dir.

Custom variables could also be temporarily defined via the command prompt:

user@hostname ~ $ var="This is a test"

These temporary variables, unlike those defined in the profile file, will be removed at program exit.


This file contains prompts defintions and is found in DATADIR/clifm/prompts.cfm. It is automatically copied as $XDG_CONFIG_HOME/clifm/prompts.cfm. See the prompt section for more information.


The keybindings file is $XDG_CONFIG_HOME/clifm/keybindings.cfm. It will be copied from DATADIR/clifm (usually /usr/local/share/clifm), and if not found, it will be created anew with default values. This file is used to specify the keyboard shortcuts used for some ClifM's functions. The format for each keybinding is always keyseq:function, where keyseq is an escape sequence in GNU emacs style. A more detailed explanation can be found in the keybindings file itself.


The directory used to store programs or scripts pointed to by actions (in other words, plugins) is DATADIR/clifm/plugins. To modify one of these plugins, copy the corresponding plugin to the local plugins directory ($XDG_CONFIG_HOME/clifm/plugins) and edit it to your liking. This local plugins directory takes precedence over the system-wide one.


This directory, DATADIR/clifm/colors, contains available color schemes as files with a .cfm extension. Color schemes are automatically copied into the local directory ($XDG_CONFIG_HOME/clifm/colors) as soon as you ask to edit the current color scheme (via the cs edit command).

If designing or editing a color scheme, the default one (default.cfm) could be used as a guide. Color schemes found in the local directory takes precedence over those in the data directory.


The file used to define custom actions is $XDG_CONFIG_HOME/clifm/profiles/PROFILE/actions.cfm. It will be copied from DATADIR/clifm, and if not found, it will be created anew with default values.


The mime list file is $XDG_CONFIG_HOME/clifm/profiles/PROFILE/mimelist.cfm. It will be copied from DATADIR/clifm. This file, used by Lira, is just a list of file types and file names/extensions and their associated opening applications.


The bookmarks file is $XDG_CONFIG_HOME/clifm/profiles/PROFILE/bookmarks.cfm. Just the list of the user's bookmarks used by the bookmarks function.


The history file is $XDG_CONFIG_HOME/clifm/profiles/PROFILE/history.cfm. A list of commands entered by the user and used by the history function.


The commands logs file is $XDG_CONFIG_HOME/clifm/profiles/PROFILE/log.cfm. For more information see the log command.


The messages log file is $XDG_CONFIG_HOME/clifm/profiles/PROFILE/messages.cfm. A file containing a list of system messages, either errors, warnings, or simple notices. The messages log format is: [date] message.


The directory jumper database is stored in $XDG_CONFIG_HOME/clifm/profiles/PROFILE/jump.cfm.

Kangaroo's Frecency Algorithm

The database

Kangaroo, the directory jumper (invoked via the j command), is designed to learn the navigation habits of the user. The information is stored in a database used to get the best match for a given string provided by the user. In this sense, Kangaroo is like a quick, smart, and evolved cd function.

The information stored in the database, always per directory, is:

a) Number of visits
b) Date of first visit (seconds since the Unix epoch)
c) Date of the last visit
d) The full path of each visited directory

With this information it is possible to construct a ranking of directories to offer the user the most accurate matches for each query string. The matching algorithm takes into account mainly two factors: frequency and recency (which is why this kind of algorithm is often called a frecency algorithm).

After getting an initial list of matches based on the query string(s) entered by the user, the frecency algorithm is applied on each entry in the list. The algorithm is quite simple: (visits * 100) / days-since-first-visit. As a result, we get the average of visits per day since the day of the first visit (what we call the directory rank).


There are however some further steps in the ranking process: Bonus points.

Extra credits or penalties are assigned based on the directories last access time according to the following simple algorithms:

Lapse Algorithm
Within last hour rank * 4
Within last day rank * 2
Within last week rank / 2
More than a week rank / 4

If the last query string matches the basename of a directory, the entry for this directory gets 300 extra credits. This is done simply because we normally use directory basenames as query strings: they are easier to remember.

In the same way, pinned directories get 1000 extra credits, bookmarked directories 500 credits, and directories currently in a workspace 300 credits.

For example: if the query string is test, /media/data/test will be matched. Now, if this directory was accessed within the last hour, and its rank was 200, it becomes 800. But, because the search string matches its basename, it gets 300 extra credits, and, if this directory is in addition bookmarked and pinned, it gets 1500 extra credits. In this way the total rank of this directory in the matching process is 2600. In doing this, we have more chances of matching what the user actually wanted to match.

Once all entries in the initial list of matches have been filtered via the above procedure and ranked, we can return the best ranked entry. The higher rank a directory has, the more priority it has over the remaining entries in the initial list of matches.

Shrinking the database

Automatic maintenance is done on the database applying two simple procedures:

a) Each entry in the database is checked at startup to remove non-existent directories.

b) Once the sum total of ranks reaches MaxJumpTotalRank (by default 100000), each individual rank is divided by a dynamic factor so that the total rank becomes less than or equal to MaxJumpTotalRank. If some directory rank falls in the process below MinJumpRank (by default 10), the directory is removed from the database.

Both MinJumpRank and MaxJumpTotalRank can be modified in the configuration file. The higher the value of MaxJumpTotalRank, the more time directories will be kept in the database. By contrast, the higher the value of MinJumpRank, the quicker directories will be removed from the database.

Note: Directories visited in the last 24 hours, just as bookmarked/pinned directories, and current directories in one or more workspaces, will not be removed from the database, no matter what their rank is. This is why the total rank could be higher than MaxJumpTotalRank and nonetheless no entry in the database gets deleted.

Note 2: The idea of frecency was, as far as I know, first devised and designed by Mozilla. See However, it is also implemented, though using different algorithms, by different projects like autojump, z.lua, zoxide, and fasd. Recently, since version 0.1.5, lsx has also implemented a frecency algorithm.

Resource opener

NOTE: Since version 1.4, there have been a few modifications to Lira's configuration file syntax.

As CliFM's built-in resource opener, Lira takes care of opening files when no opening application has been specified in the command line (or when used as standalone resource opener). It does this by automatically parsing a MIME list file (see the files section): it looks first for a matching pattern (either a MIME type or a file name), then checks the existence of the command associated with this pattern, and finally executes it.

Lira is controlled via the mime command. File associations are stored in the MIME list file.

When running for the first time, or whenever the MIME list file cannot be found, CliFM will copy the MIME definitions file from the DATADIR system directory (usually /usr/share/clifm/mimelist.cfm).

Lira will check this file line by line, and if a matching line is found, and if at least one of the specified applications exists, this application will be used to open the corresponding associated file. Else, the next line will be checked. In other words, the precedence order is top to bottom (for lines) and left to right (for applications).

NOTE: In case of directories (whose MIME type is inode/directory), the entry will be used only for the open-with command.

This file follows a few simple syntax rules:


Each line in the MIME list file consists of:

a) X or !X to specify GUI and non-GUI environments respectively;

b) E, to instruct Lira to match a file extension instead of a MIME type;
b) N, to instruct Lira to match a file name instead of a MIME type;

c) A left value, containing either a file extension name or a MIME type to be matched. Regular expressions are supported (see the examples below);

d) A right value, a list of semicolon separated commands (and optionally the commands parameters) to be associated to the corresponding left value;

Note that the syntax departs here from the Freedesktop specification in that we do not rely on desktop files (mostly used by desktop environments), but rather on commands and parameters. In general thus, the syntax is this:

[!]X[:E]:REGEX=CMD [ARGS] [%f]; ...

[!]X[:N]:REGEX=CMD [ARGS] [%f] [![E,O]] [&]; ...

The %f placeholder

Use the %f placeholder to specify the position of the file to be opened in the command, for example:

mpv %f --terminal=no

will be translated into: mpv FILE --terminal=no

If the placeholder is not specified, the file to be opened will be appended to the command string. Thus, this: mpv --terminal=no amounts to this: mpv --terminal=no FILE

Running the opening application in the background

  • For GUI applications:
APP %f &
  • For terminal applications:
TERM -e APP %f &

Replace TERM and APP by the appropriate values (say, xterm and vi respectively). The -e option might vary depending on the terminal emulator used.

NOTE: In case of archives, the built-in ad command could be used as opening application.


Sometimes you might want to silence either standard error (STDERR), standard output (STDOUT), or both. Use !E and !O to silence them respectively. Both could be used together, for example, !EO.


  • Match a file name exactly: X:N:some_filename:leafpad;mousepad;kate;gedit Note: If the file name contains a dot, quote it like this: some_file\.ext to prevent the REGEX parser from interpreting it.

  • Match a file name partially (every file name starting with str): X:N:^str.*:leafpad;mousepad;kate;gedit

  • Match single file extension:


Note the N character: it indicates that this rule is intended to match a file name instead of a MIME type, just as X means that this rule is aimed to graphical environments, and !X that the rule is aimed to non-graphical environments.

  • Match multiple extensions:
    X:E:^(sh|c|py|pl)$:geany;leafpad;nano \
  • Match single MIME type:
X:^audio/mp3$=mpv %f --terminal=no;ffplay -nodisp -autoexit;mpv;mplayer
  • Match multiple MIME types:
  • In case of MIME types, you can also write the entire expression without relying on any regular expression. For example:
!X:text/plain=$TERM -e $EDITOR %f &;$VISUAL;nano;vi
  • Open the file in the foreground and silence STDERR:
X:^video/.*=mpv %f !E
  • Open the file in the background and silence both STDERR and STDOUT:
X:^video/.*=mpv %f !E !O &
# or
X:^video/.*=mpv %f !EO &

Environment variables

Environment variables (e.g. $TERM, $EDITOR, $VISUAL, $BROWSER, and even $PAGER) are also recognized by Lira. You can even set custom environment variables to be used exclusively by CliFM. For example, you can set CLIFM_TERM, CLIFM_EDITOR, and CLIFM_PDF, and the use them to define some associations:

X:text/plain=$CLIFM_TERM -e $CLIFM_EDITOR %f &
X:N:.*\.pdf$=$CLIFM_PDF %f &

For more information take a look at the mimelist file itself. Access this file by pressing F6 or entering mm edit.

Using CliFM as a standalone resource opener

Thought CliFM is a file manager, it can be used as a simple resource opener via the --open command line option. For example:

clifm --open /path/to/my_file.jpg
clifm --open /path/to/my_dir
clifm --open https://some_domain

NOTE: When opening web resources CliFM will query the mimelist file using text/html as MIME type. Whatever association it finds for this specific MIME type will be used to open the web resource.

Positional parameters could be used as well, provided the parameter does not point to a directory name, in which case it will be used as CliFM starting path. For instance:

clifm /path/to/my_file.jpg
clifm https://some_domain

Expansions, completions, and suggestions

TAB completion

CliFM provides two TAB completion modes: standard and fzf.

Standard mode


FZF mode


By default, CliFM uses the fzf mode if the fzf binary is found in PATH.1 Otherwise, the standard mode (readline) is used. To force the use of the standard completion mode, run CliFM with --std-tab-comp or set TabCompletionMode to standard in the configuration file.

1 You can get fzf from the git repository or install it via your distribution's package manager.

TAB completion is available for the following commands/cases:

Observation Multi-selection in FZF mode
Command names Both internal commands (CliFM specific) and program names in PATH No
Command parameters Both internal and command names in PATH. Nested parameters, just as parameters not starting with a dash, are not supported No
Environment variables Example: $tTAB$TERM No
Users home directory Example: ~rTAB~root/ No
Paths Yes1 2
Search patterns Example: /TAB No
Wildcards Example: s *.[ch]TAB ➔ All files ending with .c and .h will be listed. Only glob expressions in the last path component will be expanded Yes
File types Example: =xTAB ➔ List all executable files in the current directory. See the files filter section for more information Yes
ELN's Example: s 12TABs filename (or, if 12 refers to a directory, s dir/). See the ELN's section No
ELN ranges See the ELN's section Yes1
sel keyword See the sel keyword Yes1
Deselection Via the ds, desel command Yes1
Bookmarks Via the bm command. To make use of the bookmarks completion, make sure to specify some name for your bookmarks, since these names are used by the completion function No
File tags Via the tag command and the t:TAG construct Yes1 (only for the t:TAG construct and for tagged files when using the untag tu command)
Color schemes Via the cs command No
Profiles Via the pf command No
Prompts Via the prompt command No
Sort method Via the st command No
Open-with Via the ow command No
Directory history Via the j command No
Commands history Via the ! command No
Aliases Via the alias command No
Network resources Via the net command No
Remove from trash Via the trash del command Yes1
Undelete trashed file Via the undel command Yes1

1 Press TAB to expand possible matches, then press TAB again over the desired entry to select it. Once desired entries are selected, press Enter or Right: selected entries will be inserted into the command line. The following keybindings are available:

Ctrl-s: select all entries
Ctrl-d: deselect all entries
Ctrl-t: toggle selected entries

2 Multi-selection, provided there is no slash in the query string, is available for the following commands: ac, ad, bb, br, d/dup, p/pr/prop, r, s, t/tr/trash , and te.

The FZF mode

If using the fzf mode, the completions interface could be customized using the FzfTabOptions option in the color scheme file.1 --height, --margin, +i/-i, --query, --read0, and --ansi will be appended to set up some details of the completions interface. Set this value to none to pass no option, to the empty string ("") to load the default values,2 or to any other custom value. Unless set to none, any option specified here will override FZF_DEFAULT_OPTS.

If set neither in FzfTabOptions nor in FZF_DEFAULT_OPTS (in this order), the height of the FZF window is set to the default value: 40% of the current terminal amount of lines/rows.

To use fzf global settings (defined in FZF_DEFAULT_OPTS), just set FzfTabOptions to none.

NOTE: For compatibility reasons, CLiFM uses by default a simple 16 colors theme. For some nicer, more modern color schemes visit

1 FZF options, just as the prompt and the warning prompt strings, might be defined in the configuration file as well to keep backwards compatibility. However, this will be removed in a future release.

2 Default values for this option are: --color=16,prompt:6,fg+:-1,pointer:4,hl:5,hl+:5,gutter:-1,marker=2 --bind tab:accept,right:accept,left:abort --inline-info --layout=reverse-list.

Quoting system

CliFM uses a Bash-style quoting system, so that this file name: this is a test@version{1} is expanded as follows: this\ is\ a\ test\@version\{1\}

Case sensitivity

By default, path completion via the TAB key is performed ignoring case. To change this behavior, set CaseSensPathComp to true in the configuration file, or run CliFM using the --case-sens-path-comp command line option.

Fuzzy match

CliFM can perform fuzzy completion (just as suggestions) for file names and paths. For example dwnTAB will be completed as Downloads and suggested as dwn > Downloads. To enable this feature use the --fuzzy-match command line switch.

When fuzzy matching is enabled the matching process is as follows (where NEEDLE is the query string and HAYSTACK is the string to be compared to):

  1. Regular matching: check whether the string HAYSTACK starts with or equals the string NEEDLE. Ex: doc matches "docs"
  2. Check whether the string NEEDLE is contained in the string HAYSTACK (beginning, middle or end). Ex: doc matches "mydocs"
  3. Check whether each character in NEEDLE is contained in HAYSTACK (in the same order they appear in NEEDLE). Ex: doc matches "needle-on-cup"

If any of the above steps (in this order) is true, we have a match.

The sel keyword

CliFM will automatically expand the sel keyword: sel indeed amounts to file1 file2 file3 .... In this way, you can use the sel keyword with any command.

TAB completion is available for this keyword. Just type sel and, without appending a space char, press TAB: selected files will be listed. Choose one to operate on one specific selected file. If you want to operate rather on all selected files, just use the sel keyword, without TAB completing it.

If you want to set the executable bit on several files, for instance, simply select the files you want and then run this command: chmod +x sel. Or, if you want to copy or move several files into some directory: c sel 12, or m sel 12 (provided the ELN 12 corresponds to a directory), respectively.

If the destiny directory is omitted, selected files are copied into the current working directory, that is to say, m sel amounts to m sel ..

To trash or remove selected files, simply run t sel or r sel respectively.

The same goes for wildcards and braces: chmod +x *, for example, will set the executable bit on all files (excluding hidden files) in the current working directory, while chmod +x file{1,2,3} will do it for file1, file2, and file3 respectively.

ELN ranges

ELN's and ELN ranges will be also automatically expanded, provided the corresponding ELN's actually exist, that is to say, provided some file name is listed on the screen under those numbers.

For example: diff 1 118 will only expand 1, but not 118, if there is no ELN 118.

In the same way, the range 1-118 will only be expanded provided there are 118 or more entries listed on the screen.

If this feature somehow conflicts with the command you want to run, say, chmod 644 ..., because the current amount of files is equal or larger than 644 (in which case CliFM will expand that number), then you can simply run the command as external: ;chmod 644...

Of course, combinations of all these features is also possible. Example: c sel file* 2 23-31 will copy all selected files, plus all files whose name starts with "file", plus those files corresponding to the ELN's 2, and 23 to 31, into the current working directory.

To make it easier to identify which files are contained in a range, TAB completion for ranges is available, not to complete though, but to list the file names comprised in a given range of ELN's.


Gemini is a built-in auto-suggestions system (similar to the one provided by the Fish shell). As you type, Gemini will suggest already used commands, internal parameters (fixed and non-fixed parameters like profiles, color schemes, and remotes names), file names, visited directories, bookmarks, aliases, and programs in your PATH.

The white text before the cursor is what is actually typed so far, while the text after the cursor (here printed in a dimmed magenta color), is the suggested text.

To accept the entire suggestion just press Right or Ctrl-f (otherwise, keep typing and the suggestion will be ignored). The whole line will turn white (or whatever is the color you use for the text typed in the command line) and the cursor will be moved to the end of the line. Then you can press Enter as usual to execute the suggested command.

To accept the first suggested word only, press Alt-Right or Alt-f.

When looking for suggestions, Gemini will perform one or more of the following checks:

Description When
1 CliFM commands and parameters (including the sel keyword)3 First word for commands and second or more for parameters
2 Entries in the commands history list (already used commands) First word
3 File names in the current working directory Always1
4 Directories in the jump database (already visited directories) Always1
5 Path completion Always1
6 Program names in PATH3 First word
7 Shell builtins2 3 First word
8 Aliases names Always
9 Bookmarks names Always
10 ELN's Always

1 Only provided autocd (for directories) and/or auto-open functions are enabled (default). Otherwise, the checks are made only for the second or more words.

2 The shell name is taken from /bin/sh. The following shells are supported: bash, dash, fish, ksh, tcsh, and zsh.

3 Command names are checked in the following order: CliFM internal commands, command names in PATH, shell builtins.

Bear in mind that suggestions for ELN's, aliases and bookmarks names, and the jump function do not work as the remaining suggestions: they do not suggest possible completions for the current input string, but rather the value pointed to by it. For example, in the following image, the string 4 is said to point to .github because the current list of files includes a file named .github whose ELN is 4.

When accepting the suggestion (by pressing Right or Ctrl-f), the string typed so far will be replaced by the corresponding suggestion.

Suggestion checks order

The order of these checks could be customized via the SuggestionStrategy option in the configuration file. Each check is assigned a lowercase letter:

Letter Check
a Aliases names
b Bookmarks names
c Path completion
e ELN's
f Files in the current directory
h Commands history
j The directory jumper database
- Skip a check

The value taken by SuggestionStrategy is a string of seven characters containing the above letters. The letters order in this string specifies the order in which the suggestion checks will be performed. For example, to perform all checks in the same order above, the value of the string should be abcefhj. Or, if you prefer to run the history check first: habcefj. Finally, you can ignore one or more checks using a dash (-). So, to ignore the bookmarks and aliases checks, set SuggestionStrategy to h--cefj. The default value for this option is ehfjbac.

Note: The check for program names in PATH is always executed at last, except when the ExternalCommands option (see also the --no-ext command line option or the ext command) is disabled, in which case suggestions for them are simply skipped.

Suggestions color

The color of the suggested string could be customized in the color schemes file using the appropriate codes:

Code Description Default color
sb Shell builtins (7 above) 02;33 (dimmed yellow)
sc Aliases and commands suggestions (program names in PATH) (6 above) 02;31 (dimmed red)
sf Bookmarks, file and directory names suggestions (3-5, and 8-9 above) 02;04;36 (dimmed underlined cyan)1
sh Command history suggestions (2 above) 02;35 (dimmed magenta)
sp Suggestions pointer: Greater-than sign (>) used when suggesting ELN's, bookmarks and aliases names 02;31 (dimmed red)
sx Suggestions for CliFM internal commands and parameters (1 above) 02;32 (dimmed green)

1 You can set SuggestFiletypeColor to true in the configuration file to suggest file names using the corresponding file type color instead of the generic one defined by the sf code. This applies to checks 3-5 and 8-9 above.

NOTE: Bear in mind that the warning prompt depends on the suggestions system, so that it won't be available if this system is disabled.

Known issues

Suggestions won't work on the default FreeBSD console (vt, AKA Newcons), since it does not support ECMA-48 status report commands, necessary to get the current cursor position to print suggestions. As a workaround, you can switch to the sc console (AKA syscons), which does support ECMA-48 commands. Edit /boot/loader.conf and set kern.vty to sc:


You might need to reboot the computer for changes to take effect.

Now, set CLIFM_FREEBSD_CONSOLE_SC environment variable to 1 and run CliFM:

export CLIFM_FREEBSD_CONSOLE_SC=1 && clifm

However, there are two drawbacks with this workaround:

  1. X won't work
  2. Alt keybindings won't work either. To fix this issue consult the Keybindings issues section.

Syntax highlighting

CliFM provides syntax highlighting for the following cases:

Element Default color Color code
Brackets (()[]{}) cyan (00;36) hb
Expansion chars (~*) cyan (00;36) he
Comments (starting with #) dimmed red (02;31) hc
Numbers magenta (00;35) hn
Option parameters (starting with -) cyan (00;36) hp
Process separators (;|&) green (00;32) hs
Quoted strings (' and ") yellow (00;33) hq
Slashes cyan (00;36) hd
Stream redirection (>) red (00;31) hr
Variable names (preceded by $) green (00;32) hv

Highlighting colors could be customized editing the corresponding color code in the InterfaceColors section of the current color scheme file. For example, to get quoted strings highlighted in bold green:

... hq=01;32 ...

To edit the color scheme file just press F8 or enter cs edit.

To disable syntax highlighting you can either set SyntaxHighlighting to false in the configuration file (F10), or run CliFM with the --no-highlight command line option.


Actions are just names given to specific plugins, so that we only need to run this "name" just as if it were any other command. So, supposing the action ab is linked to the plugin, you only need to enter ab in order to execute

To list currently available plugins and associated action names, just enter actions.

For more information about actions and plugins, see the plugins section.


Heavily inspired by vifm, the autocommands function allows the user a fine-grained control over CliFM settings.

This function was mostly devised as a way to improve performance for remote file systems (usually slower than local ones) by allowing you to turn off some features (like the files counter) that might greatly affect performance under some circumstances (like remote connections). However, this function is not restricted to this use: use it for whatever purpose you find useful, for example, to display a kind welcome message for your documents directory, or some friendly reminder like "Do not touch!".

Add a line preceded by the autocmd keyword to the config file. The general syntax is:

autocmd PATTERN cmd,cmd,cmd

PATTERN is a glob expression to match directory names. If no glob metacharacter is provided, the string will be compared as is to the current working directory. To invert the meaning of a pattern, prepend an exclamation mark: !PATTERN

To recursivelly match a directory and all subirectories, use the double asterisk. For example: /media/remotes/**

PATTERN is followed by a comma separated list of commands:

  • !CMD: The exclamation mark allows you to run shell commands, custom binaries or scripts
  • The following codes are used to control CliFM's files list:
Code Description Example
cs Color scheme cs=amber-256
fc Files counter fc=0
hf Hidden files hf=0
lm Light mode lm=1
lv Long/detail view lm=0
mf Max files mf=100
mn Max file name length mn=20
od Only directories od=1
pg Pager pg=0
st Sort method st=5
sr Reverse sort sr=1

A few example lines:

#1. Run in light mode and disable the files counter for the remotes directory
autocmd /media/remotes/** lm=1,fc=0

#2. Just a friendly reminder
autcomd ~/important !printf "Important: keep your fingers outta here!\n" && read -n1

#3. This directory has thousands of files. Show only the first hundred and enable the pager
autocmd /usr/bin mf=100,pg=1

#4. Lots of media files (with large file names). Trim file names to 20 chars max and run the files previewer
autocmd ~/Downloads mn=20,!~/.config/clifm/plugins/

#5. Mmm, just because I can. Be creative!
autocmd /home/user hf=0,cs=amber-256,lv=1
autocmd / lv=1,fc=0,cs=solarized,st=5

The first example is the recommended configuration for directories containing remote file systems.

As seen in the fifth example, plugins could be used here as well: in this case, we want to run fzfnav (to make use of the files preview capability) whenever we enter into the Downloads directory, usually containing videos, music, and images.

NOTE: If you decide to use a plugin, bear in mind that it won't be able to communicate with CliFM, because autocommands always executes commands as external applications using the system shell.

Autocommand files: and .cfm.out

Two files are specifically checked by the autocommands function: and .cfm.out.

The content of these files is a single instruction, either a shell command or, if you need more elaborated stuff, a script (or custom binary). Note that codes to modify CliFM's settings (as described above) are not available here.

If a directory contains a file named, CliFM will execute (via the system shell) its content when entering this directory (before listing files). If the file is named rather .cfm.out, its content will be executed immediately after leaving this directory (and before listing the new directory's content).

For example, if you want a simple notification whenever you enter or leave your home directory, just create both and .cfm.out in the home directory with the following content:


printf "Entering %s ...\n" "$PWD"

For .cfm.out:

printf "Leaving %s ...\n" "$OLDPWD"


Note: The above image shows CliFM running in the second workspace ([2])

CliFM supports up to eight workspaces (also known as tabs). Each workspace has its own persistent path (or current directory), though everything else, like profile, settings, and selected files, is shared among workspaces. Workspaces allows the user to easily switch between the most used directories: do one thing in a workspace and then switch to a second or third one to continue working.

To switch between workspaces you can use the ws command or press Alt-[1-4]. For example, to switch to workspace 3:




You can also select your starting workspace via command line parameters using the -w, --workspace option. This option could be used in combination with positional parameters to set the starting path as well. So, to start in /etc in the workspace 4, run CliFM as follows:

clifm -w4 /etc

By default, the prompt shows the current workspace number enclosed in square brackets, as shown in interface description image.

Each workspace path is stored in $XDG_CONFIG_HOME/clifm/profiles/PROFILE/.last, so that workspaces paths are persistent across CliFM runs.

When switching to a new, empty workspace, the current working directory is used as the new workspace path.


A profile is an independent and isolated set of settings for CliFM. Though by default all new profiles are created with the default settings, each profile may have its own color color scheme (useful to clearly distinguish among profiles), its own command and directory history, files and interface settings, and so on.

There is no limit for the number of existent profiles.

Profile data is stored in $XDG_CONFIG_HOME/clifm/profiles/PROFILE.

Creating profiles

To create a new profile you can start CliFM with the -P, --profile option, specifying the profile name (for instance: clifm -P new_profile), or using the pf command as follows:

pf add new_profile

Switching profiles

To switch between profiles while running CliFM, issue this command:

pf set my_profile

You can also use Ctrl-Atl-o and Ctrl-Atl-p to switch to the previous and next profile respectively.

Deleting a profile

To delete a profile, use, again, the pf command:

pf del my_profile

NOTE: TAB completion is available for profile names.

Light mode

In default or normal mode, fstatat(3) is used to gather information about listed files. Since this function, especially when executed hundreds (and even thousands) of times, is quite time consuming, the light mode1 was implemented as an alternative listing process omitting all calls to this function. Compared to the normal mode, CliFM in light mode list files 40% faster.2

1 Enable the light mode using the -y, --light-mode command line option, the LightMode option in the configuration file, the lm command or pressing Alt-y.

2 For more performance information consult the statistics section.

What is lost when running in light mode?

Since we cannot rely on the information provided by fstatat(3):

  • Only basic file classification is performed, namely, that provided by the d_type field of a dirent struct (see readdir(3)), so that we cannot know in advance if a file is readable by the current user, if it is executable, if it has capabilities, if it is SUID, SGID, if a symlink is broken, and so on.

  • The marker for selected files (*) is disabled: we use files inode and device number to identify selected files, but this information, again, is provided by fstatat(3).

  • The file extension check is ignored as well for performance reasons, so that the color per extension feature is disabled.

Note: Bear in mind, however, that in case of d_type returning a value of DT_UNKNOWN, CliFM will fall back to stat(3) to get basic file classification: we might be facing a file system not returning the d_type value (in which case DT_UNKNOWN is returned for all file types), for example, loop devices.

Stealth mode

CliFM's commitment to privacy and anonymity is reflected not only in the complete lack of spying and anti-privacy features in the source code (no data collection at all), but also via the so called Stealth mode. When running in stealth mode indeed no file is read, just as no file is written to the filesystem: CliFM runs entirely in memory, so that no trace of your presence is left on the host system (besides whatever remains in memory itself). Of course, the user still can modify the file system as she pleases via regular file management commands, but needles to say, this is not CliFM's responsibility.

Because no file is read, options and settings are set to the default values. However, this does not mean that customization isn't possible in stealth mode. In fact, command line options and several environment variables have been implemented to make this possible. Note, however, that the use of environment variables, if not properly reset after use, somehow defeats the idea of a program running in stealth mode.

There is however one drawback: Since no file is read, all those features depending on files will not be available in stealth mode. Among these features we find: permanent directory history and files selection, just as bookmarks, the jump database, logs, etc.

To start CliFM in stealth mode use the -S, --stealth-mode command line option.

An uppercase s (by default bold blue) at the left of the prompt indicates that you are running in stealth mode.

Testing stealth mode

To make sure CliFM won't access the file system while running in stealth mode, you can use inotifywait(1), from the inotify-tools package, to monitor CliFM's directories as follows:1

inotifywait -m -r /usr/share/clifm/ ~/.config/clifm

Leave inotiofywait running and then launch CliFM as usual (in stealth mode, of course). If some file is somehow accessed, inotifywait will immediately let you know.

1 You can also use fswatch.

NOTE: If you only need to temporarily disable history, because you'll enter some sentive information in the command line, you can prevent your commands from being written into the history file by just disabling history. Just enter history off, that's all. Once you're done, reenable history: history on. Also, commands entered with a leading space will not be recorded at all. To disable history for the whole session use the --no-history switch.

Disk usage analyzer

When running in disk usage analyzer mode (-t, --disk-usage-analyzer or Alt-TAB / Ctrl-Alt-i) CliFM allows you to navigate the files system having file sizes for each entry in the current directory in view: here you can operate on files as usual, for example, removing unneeded/old large files. It is equivalent to --long-view --sort=size --full-dir-size --no-dirs-first --apparent-size.

The total size of the current directory, plus the name and size of the largest file, will be printed after the list of files. Sizes are apparent sizes (rather than actual device usage (blocks)) and calculated using powers of 1024. To use powers of 1000 instead use the --si switch. It could be a good idea to run with the --disk-usage command line switch to keep in sight free/total size of the current files system as well.

Note: A plugin,, bound by default to the da action, is also available to perform a similar function using du(1) and fzf.


Since CliFM executes OS commands, it needs to provide a way to securely run these commands, specially when it comes to untrusted environments. Two features are provided to achieve this aim:

  • Secure environment
  • Secure commands

Both features are aimed to protect the program and the system as such from malicious input, either coming from environment variables or from indirect input, that is to say, input coming not from the command line (which is to be taken as trusted input), but from files: this is the case of default associated applications (the mime command), autocommands, (un)mount commands (via the net command), just as profile and prompt commands.

In an untrusted environment, an attacker could cause unexpected and insecure behavior (even command injection) using environment variables,1 or inject malicious commands via indirect input, commands which will be later executed by CliFM without the user's consent (i.e. automatically). This is why we provide a mechanism to minimize this danger: if running in an untrusted environment, the secure environment and secure commands features are there to prevent (at least as far as possible) this kind of attacks.2

1 See the Shellshock vulnerability

2 For increased security you can run CliFM sandboxed via some application like firejail (the ranger profile, provided by default by firejail, can be used for CliFM as well):

firejail --proflie=ranger clifm

A) Secure environment

Programs inherit the environment from the parent process. However, if this inherited environment is not trusted, not secure, it is always a good idea to sanitize it using only sane values, preventing thus undesired and uncontrolled input that might endanger the program and the system itself.

The secure-environment function forces CliFM to run on such a sanitized environment.

There are two secure-environment modes, the regular, and the full one. To enable the regular mode, run CliFM with the --secure-env command line option. Otherwise, enable the full mode using --secure-env-full.

a) Regular: in this mode, the inherited environment is cleared, though a few variables are preserved to keep CliFM running as stable as possible. These preserved variables are: TERM, DISPLAY, LANG, TZ, and, if FZF TAB completion mode is enabled, FZF_DEFAULT_OPTS.

The following variables are set in an environment agnostic way (that is, securely):

  • HOME, SHELL, and USER are retrieved using getpwuid(3)
  • PATH is set consulting _PATH_STDPATH (or _CS_PATH if the former is not available)
  • IFS is set to a sane, hard-coded value: " \n\t"

b) Full: this mode is just like the regular mode, except that nothing is imported from the environment at all and only PATH and IFS are set (as described above). Everything else remains unset, and it's the user's responsibility to set environment variables (via the export function) as needed. In this case, you might want to set, at least, TERM, and, if running in a graphical environment, DISPLAY.

Be aware that enabling secure-environment (specially in the full mode) might break some functions, depending on the system configuration.

Consult the resources section for more information.

B) Secure commands

Some commands are automatically executed by CliFM: (un)mount commands (via the net command), opening applications (via Lira), just as prompt, profile, and autocommands. These commands are read from a configuration file and then executed. Now, if an attacker has access to any of these files, she might force CliFM to run any arbitrary command, and thereby possibly exposing the whole system.

Every time a command is thus automatically executed via the system shell (i.e. without the user's direct consent), the secure commands function performs three different, though intrinsically related tasks aimed to mitigate command injection and/or unexpected behavior:

a) Only command base names are allowed: nano, for instance, is allowed, while /usr/bin/nano is not. In this way we can guarantee that only commands found in a sanitized PATH (see the point c below) will be executed. This is done in order to prevent the execution of custom binaries/scripts, for example: /tmp/exec_file.

b) Commands are validated using a whitelist of safe characters (mostly to prevent stream redirection, conditional execution, and so on, for example, your_command;some_injected_command). This set of safe characters slightly vary depending on the command being executed (because they allow different syntaxes):

  • Net command: a-zA-Z -_.,/=
  • Prompt, profile, autocommands: a-zA-Z -_.,/"'
  • Mime command: az-AZ -_.,%&1

1 Though Lira, who takes care of automatically choose available applications to open a given file, does not execute commands via the system shell, it still allows the user to use environment variables (like TERM and EDITOR), and insofar as the content of these variables comes from an untrusted source (the environment), this content must be checked as well. Needless to say, Lira allows the use of a single ampersand character to run the opening application in the background. However, two consequtive ampersand characters are not allowed: this construct conditionally executes a second, possibilly arbitrary command, next to the first one (supposedly the opening application).

Commands containing at least one unsafe character will be rejected. Of course, we cannot (and should not) prevent what looks like legitimate, benign commands from being executed. But we can stop commands that, in an untrusted environment, look suspicious. This is specially the case of stream redirection (>), pipes (|), sequential (;) and conditional execution (&&, ||), command substitution ($(cmd)), and environment variables ($VAR).

c) Unless already running in a secure environment (via the --secure-env or --secure-env-full options), a sanitized environment will be created for the command to be executed via the system shell (restoring immediately afterwards the original environment). The values for this secure environment are:

Variable Value
PATH Taken from _PATH_STDPATH (or _CS_PATH if the former isn't defined)
IFS " \t\n"
USER, HOME, SHELL Retrieved from the password database via getpwuid(3)
DISPLAY, TZ, LANG, TERM Imported from the environment and sanitized

Consult the resources section for more information.

A Note about Secure Deletion

When security is at stake, securely deleting files is one of those things that always comes to the forefront, and for very good reasons: deleting a file is not as simple or clear as it might seem at first sight. You don't simply delete a file, at least not with standard commands or applications, such as rm(1).

As Dave MkCay states: "When you delete a file with rm, the filesystem frees up the appropriate inode and adjusts the directory file. This marks the space on the hard drive that the file used to occupy as unused. Imagine you walk into a library and go through the card index, find a book’s catalog card, and rip it up. The book is still on the shelf. It’s just harder to find."1

In very brief terms, this is why secure deletion is a real issue when it comes to security/privacy/anonimity: by normal means, the deleted file is still there, and as such, it can be recovered by means of specific procedures and commands, such as undelete and company.2

Now, why don't we provide a built-in mechanism to securely delete files?

1) Today, solid state drives (SSD) are the standard, but traditional secure deletion mechanisms only work for mechanical drives (HHD).

2) The only secure means of protecting your data is via drive encryption (provided as an option by most distributions nowadays at installation time)

3) Even if we decide to implement such mechanism, we could only wrap some external command (like shred): writing a secure deletion algorithm from scratch is simply a bad idea: not only it is hard to implement, but there are good, perfectly valid alternatives out there. Wrapping a command is mostly aimed to simplify the command's operation under some specific circunstance or environment by taking some sane, default decisions (regarding option parameters, for example). But when it comes to sensible operations like securely deleting files, such decisions should not be made in advance.

4) If, despite all the above, you really want to securely delete some files, you still can use the command line as usual from within CliFM itself: just issue the command you want, that's all. Take a look at shred(1), wipe(1), and the secure-delete suite.

2 Consult the resources page for more information

A Note on Tiling Window Managers and Terminal Multiplexers

Since version 1.6, CliFM implements a feature called refresh-on-resize: it will attempt to keep the contents of the screen, mostly the files list, in sync with the terminal window's size. This feature is specially relevant for tiling window managers and terminal multiplexers, where opening applications and/or files usually implies creating new windows and resizing existing ones.

The procedure is quite simply, but twofold (depending on whether the application/file was opened in foreground or in the background):

a. Foreground applications:

The opening application is executed as usual. CliFM's screen remains untouched while the process is running (in a separate window). Once it finishes, the screen (provided it has been resized by the window manager) is automatically updated and put in sync with the new terminal window size.

b. Background applications:

Just like in the case above, the opening application is executed in a new window and CliFM's screen remains untouched. Normally, the focus will be on the new window. Change the focus to CliFM's window and just press Enter to update the screen.

The same thing applies when you close the window of the application running in the background: the window manager will automatically switch the focus to CliFM's window, and you only need to press Enter to udate the screen contents.

If creating new windows (usually by pressing MOD-Enter), the procedure is the same: go back to CliFM's window and press Enter to update the screen.

Briefly put, when running applications in the foreground everything should be automatic. If running in the background, by contrast, just press Enter.

The refresh-on-resize feature can be disabled via the --no-refresh-on-resize command line switch.