npm i fls


A type-filtering wrapper for the standard ls Unix utility

by Michael Klement

0.4.0 (see all)License:MITTypeScript:Not Found
npm i fls

npm version license


fls — Introduction

flsfiltering ls — is a type-filtering wrapper for the standard ls Unix utility.

The general idea is to enhance ls with the ability to filter items by filesystem type by specifying a filter expression as the first argument.
A filter expression is composed of one or more optionally negatable filter characters based on the type-identifying chars. supported by find's -type primary and Bash's file-test operators,
such as f for files, d for directories.

Behind the scenes ls is ultimately invoked, so all of its options - except -R / --recursive - are supported.
Specifying a filter is optional, so fls can generally be used in lieu of ls, with a few restrictions detailed in the manual.

The following example lists only subdirectories in the current directory, in long format:

fls d -l

fls also lends itself to creating aliases; for instance, the following alias lists all executable (x) files (f):

  • alias lsbin='fls fx'

This alias can serve as a general ls replacement with fixed options, to which you may optionally pass filters as the first operand:

  • alias lsx='fls -FAhl'

See examples below, read concise usage information further below, or read the manual.


# List all files (not directories) in the current dir.
fls f

# List all subdirs. of the user's home dir.
fls d ~

# List all symlinks to hidden files in long format in the user's home dir.
fls lf -l ~/.*

# List all executable files matching c* in /usr/local/bin
fls xf /usr/local/bin/c*

# List all empty (zero bytes) files in the current dir.
fls fe

# List all empty directories in the current dir, most recent one first.
fls de -t

# Use without filters:
fls           # same as ls
fls -lt ~     # same as ls -lt ~
fls -lt -- pg # same as lf -lt pg; -- unambiguously marks 'pg' as file operand


Supported platforms

  • When installing from the npm registry: Linux and OSX
  • When installing manually: any Unix-like platform with Bash

Installation from the npm registry

With Node.js or io.js installed, install the package as follows:

[sudo] npm install fls -g


  • Whether you need sudo depends on how you installed Node.js / io.js and whether you've changed permissions later; if you get an EACCES error, try again with sudo.
  • The -g ensures global installation and is needed to put fls in your system's $PATH.

Manual installation

  • Download this bash script as fls.
  • Make it executable with chmod +x fls.
  • Move it or symlink it to a folder in your $PATH, such as /usr/local/bin (OSX) or /usr/bin (Linux).


Find concise usage information below; for complete documentation, read the manual online, or, once installed, run man fls (fls --man if installed manually).

$ fls --help

A type-filtering wrapper around the standard ls utility.

    fls [<filter>] [<options-for-ls>] [<dir>]
    fls [<filter>] [<options-for-ls>] <fileOrDir>...

<filter> is a string of filter characters; commonly used are:

    f       file or symlink to file
    d       dir or symlink to dir
    l       symlink
    x       executable file / searchable dir. (by you)
    e       empty file (zero bytes) or empty dir. (no files or subdirs.)

Filters are combined with logical AND, and filters placed after ^ are negated.  
E.g., fls fx^l lists executable files that aren't symlinks.

Standard options: --help, --man, --version, --home


Copyright (c) 2015-2020 Michael Klement mklement0@gmail.com (http://same2u.net), released under the MIT license.


This project gratefully depends on the following open-source components, according to the terms of their respective licenses.

npm dependencies below have optional suffixes denoting the type of dependency; the absence of a suffix denotes a required run-time dependency: (D) denotes a development-time-only dependency, (O) an optional dependency, and (P) a peer dependency.

npm dependencies


Versioning complies with semantic versioning (semver).

  • v0.4.0 (2021-08-19):

    • An attempt to use ls's -R / --recursive option now causes an error; it was never meaningfully supported.
  • v0.3.3 (2020-01-26):

    • [dev] Updated the (design-time only) npm packages.
  • v0.3.2 (2018-07-26):

    • [doc] Read-me formatting fixed.
  • v0.3.1 (2018-07-25):

    • [dev] npm-package security vulnerabilities fixed - note that these vulnerabilities never affected runtime operation.
  • v0.3.0 (2015-09-17):

    • [BREAKING CHANGES] Filter characters streamlined to be (a) all-lowercase (l now accepted in addition to L and h), s in addition to S; (b) new filter e for testing emptiness added, which supersedes the previous s filter with opposite semantics. s now means test for a socket, and what was previously s (non-emptiness test) can now be expressed more intuitively as ^e (negated emptiness test), and, conversely, a simple e tests for emptiness rather than the obsolete double-negative ^s.
  • v0.2.3 (2015-09-16):

    • [doc] man page improvements.
  • v0.2.2 (2015-09-16):

    • [doc] fls now has a man page, and -h outputs concise usage information only.
    • [fix] Filenames with backslashes are now handled correctly.
  • v0.2.1 (2015-09-15):

    • [dev] Makefile improvements; various small behind-the-scenes fixes.
  • v0.2.0 (2015-07-26):

    • [breaking changes]
      • Behavior aligned with ls so as to facilitate use of fls-based aliases as general ls replacements with optional on-demand filtering.
      • The filter argument may now be placed either before or after options; only before options is it unambiguously a filter; alternatively, following the first operand with -- also unambiguously marks it as a filter.
        Options may now be intermingled with operands, even on platforms whose ls implementation doesn't support it.
      • Conversely, use -- in lieu of a filter to explicitly requests that no filtering be performed - the previously used - no longer works.
      • If the first operand is not unambiguously specified as a filter and it is not a valid filter, it is treated as a file/dir. operand.
      • -d, previously only used behind the scenes for multiple operands, can now be used explicitly to request that a single operand that is a directory be targeted as itself, as opposed to its contents.
    • [fix] Filter validation improved to correctly detect mutually exclusive types and duplicate filters.
    • [dev] Improved tests.
  • v0.1.5 (2015-07-18):

    • [fix] Symlinks passed as file operands are now correctly detected, even if their targets do not exist.
    • [dev] Test for above fix added, Makefile improvements.
  • v0.1.4 (2015-06-09):

    • [doc] Attempt to fix problem with read-me formatting in the npm registry.
    • [dev] Makefile updated.
  • v0.1.3 (2015-06-03):

    • [doc] Read-me fixed and improved.
    • [dev] Makefile updated.
  • v0.1.2 (2015-06-03):

    • [doc] Read-me improved.
  • v0.1.1 (2015-06-03):

    • [doc] Read-me improved.
    • [dev] Makefile updated.
  • v0.1.0 (2015-06-03):

    • [dev] Version bumped to 0.1.0 to better reflect the level of maturity.
    • [doc] TOC problem fixed.
  • v0.0.2 (2015-06-03):

    • [fix] Simple, but fundamental bug on Linux fixed (my apologies): no longer tries to use command with exec, which fails on Linux, because command is only a builtin (and was never needed to begin with).
  • v0.0.1 (2015-06-03):

    • Initial release.



GitHub Stars



1yr ago








1yr ago
No alternatives found
No tutorials found
Add a tutorial

Rate & Review

No reviews found
Be the first to rate