tls (tagged ls)

A fast, colorized directory lister and interactive file manager bridging directory exploration and metadata management via filesystem extended attributes (xattr).

---

Features

• Fast & Colorized Directory Listing: Colorized output with Nerd Font icons, human-readable sizes, permissions, and tag badges.
• Tag-Header Multi-Column Layout: Files are visually organized under clean tag column headers (#todo, #wip, untagged, etc.).
• Interactive Tagging (tls tag): Navigate with hjkl or Tab, cycle tags with [Space], and save changes in-place.
• Interactive Tag Config Editor (tls config): Add (a), remove (x), and reorder (H/L) custom tag presets with live visual feedback.
• Interactive Directory Navigation & File Opener (tls cd):
  • Navigate file trees visually with [Enter], [l], or mouse clicks.
  • Move up to parent directory with [-] (minus key), [Backspace], [u], or clicking ...
  • Toggle hidden files on/off with [.].
  • Open source code and text files in terminal editor ($EDITOR / nvim / vim / nano).
  • Open PDFs, images, media, and docs with system default application (xdg-open / open).
  • Tag files on the fly while browsing directories.
  • Automatically change the parent shell's working directory upon exit.

---

Shell Integration (zsh, bash, fish)

To enable seamless directory changing when exiting tls cd, add the shell wrapper to your configuration:

Zsh (~/.zshrc)

Add the following line to your ~/.zshrc:

eval "$(tls init zsh)"

Then reload your shell (source ~/.zshrc). You can now run tcd to navigate directories interactively and stay in your chosen folder upon exit!

Bash (~/.bashrc)

Add the following line to your ~/.bashrc:

eval "$(tls init bash)"

Fish (~/.config/fish/config.fish)

Add the following line to your ~/.config/fish/config.fish:

tls init fish | source

---

Usage

1. Listing Files and Directories

# Default listing of current directory
tls

# List a specific directory or file
tls src
tls Cargo.toml

# List multiple directories and files (standard ls behavior)
tls src tests Cargo.toml

# Detailed long format
tls -l

# Show hidden files
tls -a

# Filter by specific tag
tls -t todo

# Show only untagged files
tls -u

# Group tagged files first
tls -S

# Disambiguation: Listing a directory named like a subcommand ('config', 'tag', 'cd')
tls ./config
tls config/
tls -- config
tls list config

2. Interactive Directory Browser & Opener (tls cd / tcd)

# Open interactive browser in current directory
tcd
# or: tls cd

# Open interactive browser in a specific path
tcd /path/to/project

Controls inside tls cd:

• [Enter] / [l] / [Click]: Enter selected directory or open selected file.
• [-] (Minus) / [Backspace] / [u]: Move up to parent directory.
• [.]: Toggle hidden files on/off.
• [Space]: Cycle tag on selected file/directory.
• [x] / [Delete]: Clear tags on selected file/directory.
• [Tab] / [Shift+Tab] / [hjkl] / [Arrows]: 2D navigation across columns.
• [q] / [Esc]: Exit and remain in current directory.

3. Interactive Tagging (tls tag)

# Launch inline tagging prompt for current directory
tls tag

# Non-interactive batch tagging
tls tag -a "rust,core" src/*.rs
tls tag -r "done" README.md
tls tag -c old_file.txt

4. Tag Configuration (tls config)

# Launch interactive tag configuration TUI (global)
tls config

# Launch interactive tag configuration TUI (local .tls.toml)
tls config --local

# Set custom tags non-interactively
tls config --set "feature,bugfix,review,done"

---

License

MIT OR Apache-2.0