Get started

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

Prerequisites

• macOS or Linux: Windows is currently not supported.
• Terminal: iTerm2 and VSCode's have good Nerd Font support.
• Nerd Fonts: Needed to render icons in the terminal.

Tip

Nerd Fonts are good for more than just pls . A number of CLI tools, like Starship and Powerlevel10k, recommend using Nerd Fonts.

When picking a Nerd Font, we recommend you opt for one that has programming ligatures, such as JetBrains Mono (used in the examples on this site).

Installation

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

Note

We are working on adding pls to more package managers like apt and dnf.

Homebrew

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.

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!

cargo install --git https://github.com/pls-rs/pls

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.

Verification

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!

pls --version # or -V

pls 0.0.0 

Usage

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

pls

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.

Help

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.

pls --help # or -h

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