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.

1. Clone the repository:

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

2. 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 <WHEN> | 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 <LEVEL>| Maximum depth to descend. | | --file-depth <LEVEL> | Hide individual files below this depth, summarized as [+N files] (classic mode only). | | --max-items <N> | 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 <FORMAT> | 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. | | --sort <TYPE> | Sort entries by the specified criteria (name, size, modified, extension). | | --dirs-first | Sort directories before files. | | --case-sensitive | Use case-sensitive sorting. | | --natural-sort | Use natural/version sorting (e.g., file1 < file10). Takes precedence over --case-sensitive. | | -r, --reverse | Reverse the sort order. | | --dotfiles-first | Sort dotfiles and dotfolders first (dotfolders → folders → dotfiles → files). Implies --dirs-first. | | --expand-level <LEVEL>| Interactive mode only: Initial depth to expand the interactive tree. | | --editor <COMMAND> | Interactive mode only: Command used to open files, overriding $VISUAL/$EDITOR. |

---

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 <details> 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 <style> the real output ships with, so it renders plainer here than it does in an actual browser):

<ul> <li><details open><summary>data</summary> <ul> <li><a href="examples/sample-directory/assets/data/config.yaml">config.yaml</a> (153 B)</li> <li><a href="examples/sample-directory/assets/data/database.sqlite">database.sqlite</a> (54 B)</li> <li><a href="examples/sample-directory/assets/data/sample.csv">sample.csv</a> (87 B)</li> </ul> </details></li> <li><details open><summary>fonts</summary> <ul> <li><a href="examples/sample-directory/assets/fonts/bold.woff2">bold.woff2</a> (58 B)</li> <li><a href="examples/sample-directory/assets/fonts/regular.ttf">regular.ttf</a> (56 B)</li> </ul> </details></li> <li><details open><summary>images</summary> <ul> <li><a href="examples/sample-directory/assets/images/banner.jpg">banner.jpg</a> (58 B)</li> <li><a href="examples/sample-directory/assets/images/favicon.ico">favicon.ico</a> (56 B)</li> <li><a href="examples/sample-directory/assets/images/logo.png">logo.png</a> (57 B)</li> </ul> </details></li> </ul>

_{3 directories, 8 files}

---

Interactive mode

Launch the TUI with lstr interactive [OPTIONS] [PATH].

Keyboard controls

| Key(s) | Action | | :------ | :------------------------------------------------------------------------------------------------------------------------------------------ | | ↑ / k | Move selection up. | | ↓ / j | Move selection down. | | ← / h | Collapse the selected directory, or jump to and collapse its parent. | | → / l | Same as Enter. | | Enter | Context-aware action:<br>- If on a file: Open it in the configured editor (--editor, $VISUAL, or $EDITOR), then return to the tree.<br>- If on a directory: Toggle expand/collapse. | | / | Search: filter entries by name as you type (substring, or a glob like *.rs / test_?.py if the query contains * or ?). Esc exits search. | | q / Esc | Quit the application normally. | | Ctrl+s | Shell integration: Quits and prints the selected path to stdout. | | Mouse | Scroll wheel moves the selection; click selects a row; clicking the selected entry activates it (open file / toggle directory). Hold Shift for normal terminal text selection. |

Examples

1. List the contents of the current directory

lstr

2. Explore a project interactively, ignoring gitignored files

lstr interactive -g --icons

3. Display a directory with file sizes and permissions (classic view)

lstr -sp

4. See the git status of all files in a project

lstr -aG

**5. Get a tree with clickable file links (in a supported terminal)