Rich Tree CLI

Rich Tree CLI provides a beautiful, colorful representation of your directory tree using the rich library. Generate stunning visual directory trees with custom icons, multiple export formats, and intelligent filtering - perfect for documentation, project exploration, and sharing repository structures.

Features

• Beautiful terminal output with colors and custom icons
• Multiple export formats: HTML, JSON, Markdown, SVG, TOML, XML, and plain text
• Smart filtering with built-in gitignore support and custom patterns
• Rich metadata including file sizes, line counts, and file types
• VS Code integration with clickable file links in HTML output
• Fast and lightweight with sensible defaults
• Highly configurable sorting, depth limits, and display options

Quick Start

Installation

Install the CLI globally so it's available from anywhere:

pip install rich-tree-cli

Or with uv:

uv pip install rich-tree-cli

Basic Usage

Generate a tree for the current directory:

rtree

Limit recursion depth:

rtree --depth 2

Export to multiple formats:

rtree --output-format html json markdown toml --output my_project

Show file metadata:

rtree --metadata all --depth 3

Command Options

rtree [DIRECTORY] [OPTIONS]

Core Options

Filtering Options

Display Options

Configuration File

You can set default options in ~/.config/rich_tree_cli/config.toml. CLI arguments always override config file settings.

[defaults]
depth = 3
metadata = ["size", "modified"]
icons = "emoji"
sort = "files"
no_color = false
no_console = false
format = ["text"]
exclude = ["node_modules", "__pycache__", ".git", "*.pyc"]
gitignore_path = "~.gitignore"

Available Options

Exclude patterns in [exclude].patterns are merged with any --exclude flags you provide.

Export Formats

HTML Export

Creates a beautiful web page with VS Code integration:

• Clickable file links that open in VS Code
• Custom CSS styling with terminal aesthetics
• Professional presentation ready for documentation

Markdown Export

Perfect for README files and documentation:

• Clean, readable format
• Integrates seamlessly with GitHub/GitLab
• Great for project overviews

JSON/TOML Export

Machine-readable formats for automation:

• Complete directory structure data
• File metadata included
• Easy integration with other tools
• TOML output uses [metadata] and [tree] tables mirroring the JSON structure

JSON Shapes

JSON exports come in two shapes, selected with --json-shape:

nested (default) — hierarchical tree of dictionaries, one node per directory:

{
  "metadata": {"total_dirs": 8, "total_files": 22, "root_path": "..."},
  "tree": {
    "src/": {
      "app.py": {"size": 2062, "lines": 56}
    }
  }
}

flat — one record per file, directory structure implicit in the path:

{
  "metadata": {
    "schema_version": 1,
    "root": "...",
    "total_files": 22,
    "total_dirs": 8
  },
  "files": [
    {"path": "src/app.py", "size": 2062, "lines": 56}
  ]
}

The flat shape is friendlier for downstream tooling (grep, jq '.files[]', spreadsheets, data pipelines). Paths are POSIX-normalized and relative to the walked root; entries are sorted by path so identical trees produce identical output (no timestamps in the payload).

XML Export

Structured data for XML pipelines:

• Human and machine readable
• Works well with XSLT and other tooling

SVG Export

Vector graphics for presentations and documentation:

• Scalable visual representation
• Embeddable in web pages and documents
• High-quality output for any size

Examples

Documentation Generation

# Generate project overview for README
rtree --format md --output project-structure --depth 3

# Create interactive HTML documentation
rtree --format html --metadata all --output docs/structure

Development Workflows

# Quick project exploration
rtree --depth 2 --icons emoji

# Share repository structure with team
rtree --format html json --output project-overview --exclude "*.pyc" "__pycache__"

# Generate structure for AI assistance
rtree --format text --metadata size --depth 4

# Show size and modification dates
rtree --metadata size modified --depth 3

# Flat JSON for downstream tooling (grep-friendly, jq-friendly)
rtree --format json --json-shape flat --output audit
jq '.files | sort_by(.lines) | reverse | .[0:10]' audit.json  # 10 biggest files by line count

Advanced Filtering

# Exclude build artifacts and dependencies
rtree --exclude "node_modules" "dist" "build" "*.log"

# Use custom gitignore
rtree --gitignore .gitignore-custom --depth 5

# Show only directories
rtree --sort dirs

Why Rich Tree CLI?

• Developer-focused: Built by developers, for developers, with real workflow needs in mind
• Beautiful output: No more ugly ASCII trees - get professional, presentation-ready visualizations
• Flexible exports: One command, multiple formats - perfect for documentation, sharing, and automation
• Smart defaults: Works great out of the box with sensible gitignore patterns and file detection
• VS Code integration: Seamlessly integrates with your development environment

Built With

• Rich - Beautiful terminal output and formatting
• Jinja2 - Powerful HTML template generation
• pathspec - Gitignore pattern matching