Skip to content

Specifics

leo-arch edited this page Mar 6, 2024 · 526 revisions

Clifm Specifics

Table of contents


Environment

The environment (if not running in secure environment mode) is inherited from the currently running shell. Once in clifm, use env(1) to get the list of currently set environment variables.

The following variables are read (if set) at initialization time:

Variable name Description
CLIFM_FILE_COLORS A colon separated list of file type color codes.1
CLIFM_EXT_COLORS Same as above, but for file extensions.1
CLIFM_IFACE_COLORS Same as above, but for different elements of clifm's interface.1
CLIFM_DATE_SHADES A comma separated list of colors used to print timestamps according to the file's age.1
CLIFM_SIZE_SHADES Same as above, but for file sizes.1
NO_COLOR / CLIFM_NO_COLOR / CLICOLOR Instruct clifm to run colorless. CLICOLOR must be set to 0.
CLIFM_FORCE_COLOR Force clifm to use colors (even if the terminal informs that it does not support colors).
COLORTERM If set to truecolor or 24bit clifm will attempt to run in 256 color mode (using the default-256 color scheme), provided the ColorScheme option in the main config file is unset.
CLIFM_HISTFILE Path to a custom commands history file.
CLIFM_FILTER Define a files filter. If set, this variable overrides the Filter option in the configuration file.
CLIFM_SUDO_CMD Name of the authentication program to use (used to mount an archive, by the prepend-sudo function (bound by default to Alt-v) or to launch a new instance as root (X command). If not set, defaults to sudo (or doas, if compiled on OpenBSD). Example: CLIFM_SUDO_CMD=doas clifm.
SHELL An absolute path to the shell used by clifm to run external commands. Only shells defined in /etc/shells are allowed.
CLIFM_SHELL Same as SHELL (takes precedence over SHELL).
TERM Terminal type for which output is to be prepared.
TMPDIR Path to a directory where temporary files will be created.
CLIFM_TMPDIR Same as TMPDIR, but specific to clifm (takes precedence over TMPDIR).
FZF_DEFAULT_OPTS Options to be passed to FZF (if used for TAB completion).
LS_COLORS If running with --lscolors, read colors from this variable.
TIME_STYLE If set from neither --time-style nor TimeStyle (in the configuration file) use this time style for the long view. See Time styles for more information.
CLIFM_TIME_STYLE Same as TIME_STLYE, but specific to clifm (takes precedence over TIME_STYLE).
PTIME_STYLE If set from neither --ptime-style nor PTimeStyle (in the configuration file) use this time style for the p/pp command and the --stat/--stat-full command line switches. See the p command for information about available styles.

1 Consult the colors section for more information.

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

Variable name Description
CLIFM This variable is set to the path to the configuration directory (by default ~/.config/clifm/profiles/default). 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 selections file.
CLIFM_PID This variable is set to clifm's process ID (current instance).
CLIFM_VERSION Version number of clifm's running instance.
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 (set immediately before running a plugin, and removed immediately afterwards) contains the path to a pipe by means of which plugins can talk to clifm. See the plugins section for more information.
CLIFM_VIRTUAL_DIR This variable is set to the path to the currently used virtual directory only if (and while) the virtual directory function is executed.
CLIFM_LINE When running a plugin via a keybinding, this variable holds the content of the current line buffer. For a usage example see the xclip.sh plugin.
SHLVL Incremented by one each time a new shell is started.
CLIFMLVL Same as SHLVL, but specific to clifm.

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.


Files

New extension for configuration files

Up to version 1.6, most config files (exception made of clifmrc, the main configuration file) used the .cfm file extension. However, in order to avoid conflicts with ColdFusion Markup Language files, which uses the same file extension, we moved to a different and unused file extension: .clifm.1

1 For more details see this issue.

Automatic transition (recommended)

Those already using previous versions of clifm will be asked, after installing and running the latest version for the first time, whether they want to automatically rename their configuration files using the new file extension. Files will only be renamed, so that nothing will be lost and the transition should be as smooth as possible.

Note: In case some keyboard bindings do not work, restart clifm.

Manual transition

In case you wish to perform the transition manually instead, follow these steps:

  1. Run clifm, and, after being asked whether to automatically rename config files, press n. Clifm will start as usual, but using the new configuration files. Old config files will be kept, but won't be read.
  2. cd into the appropriate directories (those containing .cfm files, i.e, clifm, clifm/colors, and /clifm/profiles)
  3. Bulk rename old .cfm files as .clifm files (new config files will be replaced by the old ones, but using now the new names):
br *.cfm

or, file by file:

m FILE.cfm FILE.clifm
  1. Restart clifm

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

CONFIGURATION FILE

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.

Access the configuration file via the config command or pressing F10.

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

Option Default value Description
ApparentSize true Print file sizes as used bytes (apparent size), instead of used blocks (actual disk usage).
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.
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. Note: Setting this option to false disables the files counter as well.
ClearScreen true If set to true, clear the screen before listing files.
ColorLinksAsTarget false Symbolic links are colored according to the target file. An indicator character (@) is placed at the beginning of the name to mark it as a symbolic link (note that this character is not printed if the file is selected or if icons are enabled).
ColorScheme default Color schemes are stored in the colors directory. By default, the default color scheme is used. Visit https://github.com/leo-arch/clifm-colors to get some more.
cpCmd 0 Set the default copy command. Available options are: 0 = cp -iRp, 1 = cp -Rp, 2 = advcp -giRp, 3 = advcp -gRp, 4 = wcp, and 5 = rsync -avP. Options 2-5 include a progress bar for the copy command.
Dirhistignore unset A regular expression to exclude directories from the directory history list (including the jump database). For example, use ^/home/user/Downloads.*|^/media.* to exclude the ~/Downloads and /media directories (including all subdirectories).
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 disk usage of the file system the current directory belongs to (in the form FREE/TOTAL (FREE_PERCENTAGE) FS_TYPE DEV_NAME).
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. The Classify option must be set to true.
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.
FuzzyMatching true Enable fuzzy matching for filename/path completions and suggestions.
FuzzyAlgorithm 2 Either 1 (faster, but not Unicode aware) or 2 (slower, Unicode aware).
FzfPreview true Enable file previews for TAB completion (fzf mode only) via shotgun. Set to hidden to start with the preview window hidden (toggle it via Alt-p).
Histignore ^[q,Q]$|^quit$|^exit$|^ .|^#.|^[0-9]+$|^\.+$ A regular expression to exclude command lines from the commands history list. The default value excludes: 1. exit commands (q, Q, exit, quit), 2. commands starting with a space character, 3. commented lines, 4. single numbers (ELN's), and 5. commands consisting only of dots (., .., and backdir expressions (three or more consecutive dots).
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.
LogMsgs false Log errors and warnings generated by clifm. See the log command for more information.
LogCmds false Log commands entered in the command line. See the log command for more information.
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 (same as TrimNames=false).
MaxDirhist 100 Maximum amount of visited directories to remember.
MaxHistory 1000 Maximum amount of commands to remember.
MaxLog 1000 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 -i, 1 = mv, 2 = advmv -gi, and 3 = advmv -g. Options 2 and 3 include a progress bar for the move command.
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.
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). If set to 0, directories are kept indefinitely.
Opener unset Choose the resource opener to open files with their default associated application, for example, Ranger's rifle(1) or xdg-open(1). If unset, Lira, clifm's built-in opener, is used instead.
Pager false Enable Mas, the files list pager. Consult the pg command for more information.
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).
PrivateWorkspaceSettings false If set to true, settings changed in the current workspace (only via the command line or keyboard shortcuts) are kept private to that workspace and made persistent (for the current session only), even when switching workspaces. See the workspaces section for more information.
PTimeStyle %Y-%m-%d %H:%M:%S.%N %z Same as TimeStyle (see below), but for the p/pp command. Available styles: default, iso, long-iso, full-iso, full-iso-nano, and +FORMAT (FORMAT is interpreted like in strftime(3)). Nano-second precision is available via the %N modifier.
PropFields xfpIms Customize fields displayed in long view. See the File details section for more information.
PropFieldsGap 1 Single or double space between fields in long view. See File details for more information.
PurgeJumpDB false If set to true, remove non-existent directories from the jump database at startup. Note that this will remove paths pointing to unmounted file systems (like removable devices or remote locations) which you still might want to keep for later access. Non-existent directories, however, will be eventually removed anyway due to their low rank value (see the frecency algorithm).
QuotingStyle backslash How to quote expanded ELN's (regular files only). Available options: backslash, single, and double (quotes).
ReadAutocmdFiles false Read and run autocommand files.
Readonly false Run in read-only mode.
RestoreLastPath false If set to true, start clifm in the last visited directory (and in the last used workspace). This option is overridden by StartingPath.
RlEditMode 1 Set readline editing mode: 0 for vi and 1 for emacs.
rmForce false If set to true, the r command will never prompt before removals: rm(1) is invoked with the -f flag.
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 dot-files (file names starting with a dot) or not.
SkipNonAlnumPrefix true When sorting files (either by version or name) skip non-alphanumeric characters. For example, __gfile is sorted as gfile, and thereby after ffile. This also impacts on hidden files: if set to false, .hidden will be listed before afile; otherwise, after gfile.
Sort version Choose sorting method.
SortReverse false Sort in reverse order (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 overrides RestoreLastPath.
Suggestions true Enable auto-suggestions.
SuggestCmdDesc true Suggest a brief description for internal commands (since version 1.9.2).
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 ehfj-ac A list of checks to be performed when looking for possible suggestions. See the suggestions page.
SyntaxHighlighting true Enable/disable syntax highlighting.
TabCompletionMode unset The method used to display possible completions. Available options: standard, fzf, fnf, and smenu. 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.
TimeStyle %b %e %H:%M for recent files (< 6 months), or %b %e %Y Style used to print times/dates in long view mode. See Time styles for more information.
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.
TrimNames true Trim file names longer than MaxFilenameLen.
Umask Value inherited from the shell Set the file mode creation mask (077 is recommended). This option is ignored in secure mode.
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.
WelcomeMessageStr unset Set a custom welcome message, for example, some inspirational phrase like "Do not forget to feed the dogs!".
WorkspaceNames unset A comma separated list of workspace names in the form NUM=NAME. Example: "1=Main,2=Extra,3=GIT". If unset, workspaces are unnamed.

1 List of file type indicators:

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

PROFILE FILE

The profile file is $XDG_CONFIG_HOME/clifm/profiles/PROFILE/profile.clifm. In this file you can add those commands you want to be executed at startup, even before files listing, for example, to display some ascii art, which can be done as follows:

  1. Install arttime:
mkdir build && cd build
git clone https://github.com/reportaman/arttime
cd arttime
./install.sh
  1. Add this line to the profile file:
~/.local/bin/artprint -t "Welcome to CliFM" -a $(ls ~/.local/share/arttime/textart | shuf | sed -n 1p); read -r

This will print a random ascii art (taken from the arttime gallery) followed by a "Welcome to CliFM" message.

Or, maybe you want to make cow say a few smart lines:

fortune | cowsay; read -r

Custom variables

You can also permanently set here some custom variables (enable the use of internal variables using the --int-vars command line switch). For instance:

dir="/path/to/dir"

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.

PROMPTS FILE

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

KEYBINDINGS FILE

The keybindings file is $XDG_CONFIG_HOME/clifm/keybindings.clifm. 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.

PLUGINS DIRECTORY

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.

COLORS DIRECTORY

This directory, DATADIR/clifm/colors, contains available color schemes as files with a .clifm 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.clifm) could be used as a guide. Color schemes found in the local directory takes precedence over those in the data directory.

ACTIONS FILE

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

MIMELIST FILE

The mime list file is $XDG_CONFIG_HOME/clifm/profiles/PROFILE/mimelist.clifm. 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.

PREVIEW FILE

The preview file is $XDG_CONFIG_HOME/clifm/profiles/PROFILE/preview.clifm. It will be copied from DATADIR/clifm. This file is shotgun configuration file and makes use of the same syntax used by Lira in the mimelist.clifm file.

BOOKMARKS FILE

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

HISTORY FILE

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

COMMAND LOGS FILE

The command logs file is $XDG_CONFIG_HOME/clifm/profiles/PROFILE/cmdlogs.clifm. Command logs keep track of commands entered in the command line. These logs have this form: [date] current_working_directory:command. For more information about logs see the log command.

MESSAGE LOGS FILE

The message logs file is $XDG_CONFIG_HOME/clifm/profiles/PROFILE/msglogs.clifm. Message logs are a record of errors and warnings and have the following form: [date] message. For more information about logs see the log command.

KANGAROO'S DATABASE

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


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 (~/.config/clifm/profiles/PROFILE/jump.clifm) 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) Permanent entry (+): this directory won't be deleted no matter its rank (since version 1.17) b) Number of visits
c) Date of first visit (seconds since the Unix epoch)
d) Date of the last visit
e) The full path to each visited directory

With this information it is possible to build 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 (see the note 2 below).

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 * VISIT-CREDIT) / 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).

Note: VISIT-CREDIT is hardcoded to 200.

Credits

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 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 users 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, directories currently in a workspace 300 credits, and directories marked as permanent 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, pinned, and marked as permanent, it gets 1800 extra credits. In this way the total rank of this directory in the matching process is 2900. In doing so, 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 as follows:

a) If PurgeJumpDB is set to true (see the main configuration file), each entry in the database is checked at startup to remove non-existent directories. This option is set to false by default to avoid removing paths pointing to unmounted file systems (like removable devices and remote locations) which you still might want to keep for later access. Non-existing directories, however, will be automatically removed anyway due to their low rank value (see point b below).

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.

Whenever a directory rank falls below MinJumpRank (by default 10), it is forgotten (removed from the database). If set to 0, however, directories will never be forgotten.

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. If you want a directory to be indefinitely kept in the database, bookmark it or mark it as permanent (see Excluding and keeping directories).

Note 2: The idea of frecency was, as far as I know, first devised and designed by Mozilla. See https://wiki.mozilla.org/User:Mconnor/Past/PlacesFrecency. 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

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: 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.clifm).

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).

Bear in mind that these commands will be executed directly without shell intervention, so that no shell goodies (like pipes, conditions, loops, etc) are available. In case you need something more complex than a single command (including shell capabilities) write your own script and place the path to the script in place of the command. For example:

X:^text/.*:~/scripts/my_cool_script.sh

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:

Syntax

Each line in the MIME list file consists of:

a) X or !X to specify GUI and non-GUI environments respectively. Omit it if the corresponding command works on both, GUI and non-GUI environments.

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

c) A left value, containing either a file 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][: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.

STDERR and STDOUT

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

Examples

Rule Description
X:N:some_filename:leafpad;mousepad;kate;gedit Match a file name exactly1 (GUI only)2
X:N:^str.*:leafpad;mousepad;kate;gedit Match a file name partially (all file names starting with str)
!X:^audio/mp3$=mpv %f --terminal=no Match a single MIME type (non-GUI only)
N:.*\.txt$:nano;vim;vi;emacs Match a single file extension (this rule applies to both GUI and non-GUI environments)
X:N:.*\.(sh|c|py|pl)$:geany;leafpad;nano Match multiple extensions
X:^audio/.*=mplayer;mplayer2;vlc;gmplayer Match multiple MIME types3
X:^video/.*=mpv %f !E Open the file in the foreground and silence STDERR
X:^video/.*=mpv %f !EO & Open the file in the background and silence both STDERR and STDOUT

1 If the file name contains a dot, quote it like this: some_file\.ext to prevent the REGEX parser from interpreting it.

2 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.

3 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

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 then 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 a third-party opener

This can be done in two ways:

a. Set Opener in the configuration file to the name of the desired opener. For example, to use Ranger's rifle(1):

Opener=rifle

or, if you prefer xdg-open(1):

Opener=xdg-open

b. Tell Lira to open all files, no matter the MIME type or file name, via the desired opener. For example:

.*=rifle

Using clifm as a standalone resource opener

Even though clifm is a file manager, it can be used as a standalone resource opener as well 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 main TAB completion modes: standard and fzf (though fnf and smenu are also supported. See below)

Standard mode

stdtabcomp

FZF mode

fzftabcomp

By default, clifm uses the fzf mode if the fzf binary is found in PATH.1 Otherwise, if neither --fnftab nor --smenutab are set, the standard mode (readline's built-in) is used. To force the use of the standard completion mode, run clifm with --stdtab or set TabCompletionMode to standard in the configuration file. Likewise, you can force the use of the fzf mode, even if TabCompletionMode is set to a different value, using the --fzftab command line switch.

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 (fzf/fnf mode) File previews (fzf mode)3
Command names Both internal commands (clifm specific) and program names in PATH
Command parameters Both internal and command names in PATH. Nested parameters, just as parameters not starting with a dash, are not supported
Environment variables Example: $tTAB$TERM
Users home directory Example: ~rTAB~root/
Paths ✔️ 1 2 ✔️
Search patterns history Example: /*TAB
Search patterns (quick search) Example: /*.pdfTAB ✔️ ✔️
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 ✔️ ✔️
File types Example: =xTAB ➔ List all executable files in the current directory. See the files filter section for more information ✔️ ✔️
ELN's Example: s 12TABs filename (or, if 12 refers to a directory, s dir/). See the ELN's section
ELN ranges See the ELN's section ✔️ 1 ✔️
sel keyword See the sel keyword ✔️ 1 ✔️
Deselection Via the ds, desel command (only for second word or more) ✔️ 1 ✔️
Bookmark paths Via the b:NAME construct ✔️ ✔️
Bookmark names Via the bm command and the b: construct. 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
Workspaces Via the ws command
File tags Via the tag command and the t: construct ✔️ 1 (only for the t:TAG construct and for tagged files when using the untag tu command) ✔️ (only for t:TAG)
Color schemes Via the cs command
Profiles Via the pf command
Prompts Via the prompt command
Sort method Via the st command
Open-with Via the ow command
Directory history Via the j command
Commands history Via the ! command
Aliases Via the alias command
Network resources Via the net command
Remove from trash Via the trash del command ✔️ 1
Undelete trashed file Via the undel command ✔️ 1

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.

3 See the file previews section below for further information.

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), 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 https://github.com/junegunn/fzf/wiki/Color-schemes.

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,border:7:dim --bind tab:accept,right:accept,left:abort,alt-p:toggle-preview,change:top,alt-up:preview-page-up,alt-down:preview-page-down --inline-info --layout=reverse-list --preview-window=wrap,border-left.

TAB completion with file previews?

Yes, if running in fzf mode file previews are available by default (disable this feature via the --no-fzfpreview command line switch or setting theFzfPreview option in the main configuration file to false). See the shotgun section for more information.

Image previews are also available via the clifmimg plugin.

Troubleshooting fzf

  • With default options, clifm should work without any hassle with fzf version 0.27 (released April 6, 2021). As far as we know, the only option not supported by fzf 0.18 (at least) is the border-left argument used in the --preview-window option. Removing this argument from FzfTabOptions should result in full 0.18 compatibility.

  • The window borders (mostly the preview window) are drawn with weird characters: you might need to install a proper Unicode font. In case this is not possible, add --no-unicode to FzfTabOptions to run fzf without Unicode support.

  • Image previews are misplaced: Consult the image previews section.

No FZF? Try with FNF

If fzf is not available for any reason, or if you just want to try a different fuzzy finder, clifm provides support for fnf, a fork of fzy (forked, hacked, and maintained by clifm devs themselves). The procedure is quite straightforward:

  1. Install fnf

  2. Tell clifm to run with fnf

clifm --fnftab

or set TabCompletionMode in the configuration file to fnf.

Clifm runs fnf with the following options:

--read-null --pad=NUM --query="STR" --reverse --tab-accepts --right-accepts --left-aborts --lines=NUM

For more information consult fnf(1).

A different alternative: smenu

smenu can also be used to display TAB completion matches. Run clifm with the --smenutab switch, or set TabCompletionMode to smenu in the configuration file.

smenu is executed using the following parameters:

smenu -t -d -nNUM -P$'\n'

Use the t key to select multiple entries.

Type /QUERY to search for entries matching QUERY in the list of matches (a fuzzy search is performed by default, but can be customized via a configuration file). Consult smenu(1) for more information.

The smenu interface can be customized via the CLIFM_SMENU_OPTIONS environment variable. For example:

-a t:1,b b:3 c:r ct:2,r sf:5,r st:6,r mt:6,b

If this variable is unset, the following options are used instead:

-a t:2,b b:4 c:r ct:2,r sf:6,r st:5,r mt:5,b

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". However, beggining of words is prefered, so that "day-of-calendar" will be prefered in this case over "needle-on-cup".

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

Two fuzzy matching algorithms are available:

  1. Version 1: Faster, but not Unicode aware.
  2. Version 2: Slower, but Unicode aware.

Version 2 is used by default, though only if the query string contains at least one Unicode character. Otherwise, it falls back to version 1. To force the use of version 1, set FuzzyAlgorithm to 1 in the config file or run with --fuzzy-algo=1 in the command line.

The sel keyword

Clifm will automatically expand the sel keyword: sel indeed amounts to file1 file2 file3 ....

Note: Since version 1.9.9, s: can be used in place of sel, to be in line with t: (for tags) and b: (for bookmarks). This avoids the conflict between sel as command and sel as keyword.

Usage examples

Command Description
sel<TAB> / s:<TAB> / sb List currently selected files1
p sel List file properties of all selected files
c sel Copy selected files into the current directory2
chmod +x sel Set the executable bit on all selected files

1 s: works exactly as sel, except that it does not need to be preceded by a command. sb will open the deselection screen.

2 If the destiny directory is omitted, selected files are copied/moved into the current working directory, that is to say, c sel amounts to c sel .. The same goes for the m command. If you want to copy or move several files into some specific directory, specify the desired directory: c sel 12 or m sel 12 (provided the ELN 12 corresponds to a directory).


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 attempt to expand that number), then you can 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.


Auto-suggestions

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 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
4 Directories in the jump database (already visited directories) Always1
5 Path completion Always1 4
6 Program names in PATH3 First word
7 Shell builtins2 3 First word
8 Aliases names Always
9 Bookmark names Always
9 ELN's Always
10 Brief description for internal commands First word5

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.

4 Fuzzy suggestions are supported. For example, dwn > Downloads. Enable this feature via the --fuzzy-matching command line switch or setting FuzzyMatching to true in the configuration file. There are two fuzzy matching algorithms available: 1 (faster, but not Unicode aware), and 2 (slower, Unicode aware). You can set this option via the --fuzzy-algo command line switch or the FuzzyAlgorithm option in the configuration file. It defaults to 2.

5 You can disable this feature via the SuggestCmdDesc option in the configuration file (since version 1.9.2).

Bear in mind that suggestions for ELN's, aliases, bookmark names, the jump function, just as file names and paths (if fuzzy-suggestions are enabled) 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 Bookmark 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)
sd Internal commands description 02;37 (dimmed gray)
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)
sz File names (fuzzy) (3-5 above) 02;04;35 (dimmed underlined magenta)

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.

Troubleshooting

Some suggestions are not visible

Try modifying the color for the corresponding suggestion type. It might be the case that your terminal is not able to print some specific color or attribute. See tyhe Suggestions color section above.

Some suggestions are never displayed

This might be due to the suggestions strategy order. For example, if an alias name is found in the commands history, its definition will simply not be suggested, because by default history entries are checked before alias names. See the Suggestions check order above.

Note: The following fixes apply to versions 1.7 and below. For later versions the suggestions system should work out of the box.

a. FreeBSD

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:

kern.vty="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.
b. NetBSD

For the time being, suggestions won't work for the default NetBSD console (wsvt25).


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 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

Actions are 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 ab.sh, you only need to enter ab in order to execute ab.sh.

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

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


Autocommands

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, the autocommands function is not restricted to this specific use case: 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 TARGET cmd,cmd,cmd

TARGET specifies the object to which subsequent commands will apply. It can match either directory names (paths) or workspaces.

  1. To match directory names use a glob pattern. 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. To match all directories under a specific directory (including this directory itself) use the double asterisk (**). A few examples:
Target Description
~/Downloads Match exactly the Downloads directory (and only this directory) in your home directory
~/Downloads/* Match all subdirectories in ~/Downloads (excluding the Downloads directory itself)
~/Downloads/** Recursively match all subdirectories in ~/Downloads (including the Downloads directory itself)
~/Downloads/*.d Match all subdirectories in ~/Downloads ending with .d (excluding the Downloads directory itself)
!~/Downloads Match everything except the ~/Downloads directory
  1. TARGET is also able to match workspaces using the ampersand character (@) followed by the ws keyword and then the workspace number. For example, to match the third workspace: @ws3, and to match the first workspace: @ws1.

TARGET 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=nord
fc Files counter fc=0
hf Hidden files hf=0
lm Light mode lm=1
lv Long/detail view lv=1
mf Max files mf=100
mn Max file name length mn=201
od Only directories od=1
pg Pager pg=0
st Sort method st=52
sr Reverse sort sr=1

1 Set to a high value (say 999) to disable this limit.

2 Only numbers are allowed. For available values see the st command.

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/fzfnav.sh

#5. I want the second workspace, no matter what the current directory is, to list files in long/detail mode:
autocmd @ws2 lv=1

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

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

As seen in the fourth 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.

Bear in mind that autocmd directives are evaluated from top to bottom, so that only the first matching target will be executed. This can be used to exclude some target from a subsequent directive. For instance, if you want all subdirectories in ~/Downloads, except mydir, to be listed in light mode, write the following directives:

autocmd ~/Downloads/mydir/** lm=0
autocmd ~/Downloads/** lm=1                                                                                                                  

Since the first directive is evaluated before the second one, this latter will apply to everything under Downloads (including this directory itself), exception made of mydir (and subdirectories).

Autocommand files: .cfm.in and .cfm.out

Note: Since version 1.16.11, this feature must be enabled first by setting ReadAutocmdFiles to true (defaults to false) in the main configuration file. Since version 1.17.7 this option is automatically set to false if running on an untrusted environment (i.e. if running with --secure-cmds, --secure-env or --secure-env-full).

Two files are specifically checked by the autocommands function: .cfm.in and .cfm.out (they must be non-empty regular files of at most PATH_MAX (usually 4096) bytes, and no NUL byte must be contained in them).

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

If a directory contains a file named .cfm.in, 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, create both .cfm.in and .cfm.out in the home directory with the following content:

For .cfm.in:

printf "Entering %s ..." "$PWD" && read -n1 && clear

For .cfm.out:

printf "Leaving %s ..." "$OLDPWD" && read -n1

Workspaces

Note: The above image shows clifm running in the first workspace ([1])

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:

ws3

or

Alt-3

Via the WorkspaceNames option in the configuration file you can name your workspaces whatever you like. For example, setting WorkspaceNames to "1=α,2=β,3=γ" you have the frist three workspaces named as the first three greek letters. Workspace names can be used in place of workspace numbers:

ws NAME

TAB completion is available for workspaces. Type ws <TAB> to get the list of available workspaces (by name, if defined, of by number).

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

clifm -w4 /etc

By default, the prompt displays the current workspace number (or name, if defined) enclosed in square brackets, as shown in interface description image.

Workspace settings

1. Autocommands

Using the @wsN notation, where N is a workspace number [1-8], you can handle workspace settings in a persistent way. For example, to have the second workspace listing files always in long view, add this line to the autocommands section in the configuration file:

autocmd @ws2 lv=1

See the autocommands section for more information.

2. Private workspace settings

Except when some autocommand is defined (see above), all settings, as defined in the configuration file, are by default applied to all workspaces. In the same way, changing settings in a workspace (either via the command line or keyboard shortcuts) affects all workspaces. In other words, settings are by default global.

However, you can use private settings for workspaces using the PrivateWorkspaceSettings option in the configuration file. If set to true, settings changed in the current workspace are kept private to that workspace and made persistent (for the current session only), even when switching workspaces. This is the list of currently supported options (mostly those controlling the list of files):

Option Command/keybinding
Color scheme cs
Dirs first Alt-g
Files counter fc
Filter ft
Hidden files Alt-.
Long view Alt-l
Light mode Alt-y
Max files mf
Only dirs Alt-,
Pager pg
Sort st, Alt-z / Alt-x
Toggle max name length Ctrl-Alt-l

Bear in mind:

  1. Workspace options set via autocommands (see point 1 in this section) override any of the above options.
  2. These settings are local and will not be kept across clifm runs. At startup, all workspaces are initialized using the values set in the configuration file, which are global.

The only truly persistent setting for workspaces (leaving autocommands aside) is the current path. Each workspace's path is stored in $XDG_CONFIG_HOME/clifm/profiles/PROFILE/.last, so that workspaces paths are persistent even across clifm runs.

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


Profiles

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.


Read-only mode

Sometimes you may just want to browse the file system without actually modifying anything in it. See for example this feature request. Clifm's read-only mode allows you to do exactly that: commands able to modify the file system (provided they were invoked directly and excplicitly) are disabled.1 Note, however, that this mode provides only a weak and basic protection: aliased commands, plugins, scripts, etc. can still be executed as usual, no matter what commands they run.

When running in this mode, the prompt will let you know by printing RO at the left of the prompt. The color used to print this indicator can be customized via the ro color code in the color scheme file.2

To enable the read-only mode run clifm with --readonly or set the Readonly option to true in the config file.

1 List of disabled commands: ac, ad, bb, bl/bleach, br/bulk, c, dup, l, le, m, md, n/new, oc, paste, pc, r, rr, t/trash, tag, te, u/undel/untrash, and vv, plus the shell commands cp, rm, mv, ln, mkdir, rmdir, link, and unlink (in BSD systems, GNU command names are included as well: gcp, grm, gmv, and so on).

2 Consult the colors section for more information.


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 (aka incognito or private mode) 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, including temporary files, stored in P_tmpdir, usually /tmp, and removed immediately after use).1 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 is not 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 unset 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, plugins, 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.

1 Nowadays, /tmp is almost always mounted as a tmpfs (RAM) file system. However, bear in mind that this is required neither by the POSIX nor the FSH standards: even running in stealth mode, clifm might be writing to disk after all.

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 will enter some sentive information in the command line, you can prevent your commands from being written into the history file by disabling history. 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 command line 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.

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 by default (can be changed via --no-apparent-size) 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, disk_analizer.sh, bound by default to the da action, is also available to perform a similar function using du(1) and fzf.


Desktop notifications

Errors, warnings, and notices are sent to the notification daemon instead of being printed immediately before the next prompt.

To enable this feature use the --desktop-notifications command line flag or set DesktopNotifications to true in the configuration file (F10).

Notifications are sent using the following command:

OS Command
Linux/BSD notify-send -u "TYPE" "TITLE" "MSG"
MacOS osascript -e 'display notification "MSG" subtitle "TYPE" with title "TITLE"'
Haiku notify --type "TYPE" --title "TITLE" "MSG"

Note: It is the notification daemon itself who takes care of actually printing notifications on your screen. For troubleshoting, consult your daemon's documentation.

Disclaimer: A working notification system is required for this feature to work. See https://wiki.archlinux.org/title/Desktop_notifications

Tip: You can always check notifications using the msg command.


Security

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" (space, new line, and horizontal TAB)

As a plus:

  1. Core dumps are disabled.1
  2. The umask value is set to 0077 at startup, and the files creation mode (if using the new command) is forced to 0600 for files and 0700 for directories.
  3. Non-standard file descriptors (>2) are closed.
  4. SUID/SGID privileges, if any, are dropped (since 1.15.10).
  5. Autocommand files are never read (since 1.17.7).

1 If you still need core dumps, you can compile using the ALLOW_COREDUMPS flag. See the compilation page for more information.

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, LANG, and TZ, and, if running in a graphical environment, DISPLAY.

Be aware that enabling secure-environment (specially in full mode) might break some functions and/or programs, 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) A sanitized environment is set.

To enable the secure-commands mode use the --secure-cmds command line switch. Note that secure-environment is implied: running clifm --secure-cmds is equivalent to clifm --secure-cmds --secure-env. To run on a fully sanitized environment, run as follows: --secure-cmds --secure-env-full.

Consult the resources section for more information.

Note: If security is a concern, you might want to take a look at the stealth mode as well.


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: issue the command you want, that's all. Take a look at shred(1), wipe(1), and the secure-delete suite.

1 https://www.howtogeek.com/425232/how-to-securely-delete-files-on-linux/
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 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, press Enter.

Clone this wiki locally