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 --format html json markdown toml --output my_project

Show file metadata:

rtree --metadata all --depth 3

Command Options

rtree [DIRECTORY] [OPTIONS]

Core Options

Flag	Short	Description
--depth	-d	Maximum depth of recursion (0 = unlimited)
--output	-o	Output file path (extension determined by format)
--format	-f	Export format(s): text, markdown, html, json, svg, toml, xml
--metadata	-m	Metadata to display: size, lines, created, modified, all, none
--json-shape		JSON output shape: nested (default, tree of dicts) or flat (list of files)

Filtering Options

Flag	Short	Description
--exclude	-e	Exclude files/directories matching patterns
--gitignore	-g	Use .gitignore file (optionally specify path)
--sort	-s	Sort order: files, dirs, size, modified, created

Display Options

Flag	Short	Description
--icons	-i	Icon style: emoji, glyphs, plain
--no-color		Disable colored output
--no-console		Suppress terminal output (export only)
--summary		Display aggregate size, line, largest-file, and extension statistics
--version	-v	Show version

Configuration File

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

[defaults]
max_depth = 3
metadata = ["size", "modified"]
icons = "emoji"
sort_order = "files"
no_color = false
no_console = false
summary = false
output_format = ["text"]
exclude = ["node_modules", "__pycache__", ".git", "*.pyc"]
gitignore_path = "~/.gitignore"

Available Options

Option	Type	Description
max_depth	int	Default max depth (0 = unlimited)
metadata	list	Default metadata fields: size, lines, created, modified, all
icons	string	Icon style: emoji, glyphs, plain
sort_order	string	Sort order: files, dirs, size, modified, created
no_color	bool	Disable colors by default
no_console	bool	Suppress console output by default
summary	bool	Display the aggregate summary report
output_format	list	Default output format(s)
json_shape	string	JSON output shape: nested or flat (default: nested)

The exclude list in [defaults] is merged with any --exclude patterns you provide.

Named Profiles

Profiles inherit [defaults] and override only the settings they specify:

[profiles.docs]
max_depth = 3
metadata = ["size", "lines"]
output_format = ["markdown"]

[profiles.audit]
output_format = ["json"]
json_shape = "flat"
summary = true

Select one with --profile. CLI arguments still have the final word:

rtree --profile docs --depth 5

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 markdown --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

# Stream one format directly into another command
rtree --format json --json-shape flat --output - | jq '.files[]'

# Include aggregate size, line, largest-file, and extension statistics
rtree --summary

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

---