Skip to content

Get started

Thanks for giving pls a try. We hope you like using it as much as we do.



These are the different ways you can install pls on your machine.


pls is available to install for macOS and Linux via our official Homebrew tap. Currently pls is not available through Homebrew core, but it is planned for the future.

Terminal window
brew install pls-rs/pls/pls

This command will fetch and install the latest release of pls from GitHub.

Build from source

If you have the Rust toolchain installed on your computer, you can build from source locally for your operating system and architecture. Also, we welcome your contributions!

Terminal window
cargo install --git

You can use --tag to install a specific version, The current latest version is v0.0.0 . Or you can use --branch main to get the latest, unreleased version.

Download binary

The CI + CD job compiles binaries for each supported OS on every code push. Additionally, we also cut periodic releases from the main branch of the repository. You can download the binary for your operating system and architecture by following these steps.

  1. Download the binary file. You can either download the binary associated with a release or a commit.

    • Release

      1. Go to the GitHub Releases page for pls .
      2. Find the latest release i.e. v0.0.0 .
      3. Expand the "Assets" attached to the release.
    • Commit

      1. Visit the page for pls 's CI + CD workflow.
      2. Click on the last successful workflow.
      3. Scroll down to the "Artifacts" section.
  2. Download the binary as per your operating system.

    • pls-x86_64-apple-darwin for macOS
    • pls-x86_64-unknown-linux-musl for Linux
  3. Unzip the archive and find the single pls executable.

  4. Place the executable on your $PATH. To do this, you can either add the directory that contains it to the path, or move/symlink the binary to a directory that is already on your $PATH.


You can check if pls was installed correctly and present on your $PATH by running the following command. If you see a version number, you're good to go!

Terminal window
pls --version # or -V

pls 0.0.0


To run pls , type the following command into any terminal.

Terminal window

By default, pls lists the contents of the current working directory, but you can pass any number of different files or directories as positional arguments.

If a directory path is passed, all the files and directories within that directory are listed. This is useful to see what's in the folder. If a file path is passed, only the file itself is listed. On its own, that's not very useful except to see if that file exists. But with the --det/-d flag, pls can display quite a lot of metadata for the file.


To see what pls is capable of, and how to use those features, check out the built-in help. You can see the detailed help or a quick reference using the --help/-h flags respectively.

Terminal window
pls --help # or -h

pls is a prettier and powerful ls for the pros.   Usage: pls [OPTIONS] [PATHS]... ...