lstr Brandon Greenwell

cli command-line command-line-tool developer-tools filesystem git ls nerd-fonts rust-lang tree tui

Use this command to install lstr:

winget install --id=bgreenwell.lstr -e

A fast, minimalist directory tree viewer, written in Rust

lstr

A fast, minimalist directory tree viewer, written in Rust. Inspired by the command line program tree, with a powerful interactive mode.

An interactive overview of a project's structure using lstr.

Philosophy

Minimalist: Provides essential features without the bloat. The core experience is clean and uncluttered.
Interactive: An optional TUI mode for fluid, keyboard-driven exploration.

Features

Classic and interactive modes: Use lstr for a classic tree-like view, or launch lstr interactive for a fully interactive TUI with keyboard and mouse navigation, filename search (/), and in-place file opening that returns to the tree when your editor exits.
Theme-aware coloring: Respects your system's LS_COLORS environment variable for fully customizable file and directory colors.
Rich information display (optional):
- Display file-specific icons with --icons (requires a Nerd Font).
- Show file permissions with -p, including symlink and setuid/setgid/sticky indicators.
- Show file sizes with -s, or cumulative directory sizes with --du.
- Git integration: Show file statuses (M, A, ?, etc.) with -G; directories reflect the status of their contents.
Flexible sorting: By name, size, modification time, or extension, with directories-first, natural/version, case-sensitive, and reverse variants.
Smart filtering:
- Respects your .gitignore files with the -g flag.
- Control recursion depth (-L) or show only directories (-d).
- Summarize deep or crowded directories with --file-depth and --max-items.
Scriptable: JSON output (--output json), a self-contained HTML directory index (--output html), pipe-friendly text, and a Ctrl+s file-picker mode for shell integration.

Installation

With Homebrew (macOS)

The easiest way to install lstr on macOS is with Homebrew.

brew install lstr

Arch Linux (AUR)

A community-maintained lstr-git package (thanks, @bakatrouble!) builds the latest commit from this repository. Install it with your preferred AUR helper, e.g.:

paru -S lstr-git

From source (all platforms)

You need the Rust toolchain installed on your system to build lstr.

Clone the repository:

git clone https://github.com/bgreenwell/lstr.git
cd lstr

Build and install using Cargo:
```
cargo install --path .
```

NetBSD

On NetBSD a package is available from the official repositories. To install it, simply run:

pkgin install lstr

Usage

lstr [OPTIONS] [PATH]
lstr interactive [OPTIONS] [PATH]

Note that PATH defaults to the current directory (.) if not specified.

Option	Description
`-a`, `--all`	List all files and directories, including hidden ones.
`--color`	Specify when to use color output (`always`, `auto`, `never`).
`-d`, `--dirs-only`	List directories only, ignoring all files.
`-g`, `--gitignore`	Respect `.gitignore` and other standard ignore files.
`-G`, `--git-status`	Show git status for files and directories.
`--icons`	Display file-specific icons; requires a Nerd Font.
`--hyperlinks`	Render file paths as clickable hyperlinks (classic mode only)
`-L`, `--level`	Maximum depth to descend.
`--file-depth`	Hide individual files below this depth, summarized as `[+N files]` (classic mode only).
`--max-items`	Show at most N entries per directory, summarized as `[+N more]` (classic mode only).
`--du`	Show directories with the cumulative size of their contents, like `tree --du`; implies `-s` (classic mode only).
`--output`	Output format: `text` (default), `json`, or `html` (classic mode only).
`-p`, `--permissions`	Display file permissions (Unix-like systems only).
`-s`, `--size`	Display the size of files.

Output formats

Besides the default tree view, lstr can emit JSON for scripting or a self-contained HTML directory index for browsing offline. Directories render as collapsible `` elements and files as relative links, so the page can be saved next to the tree it describes and opened directly in a browser; -s, -p, and -G add size, permissions, and git-status annotations, same as the other output formats. This is the live output of lstr --output html -s assets on examples/sample-directory/assets (GitHub strips the `