trls-cli 0.5.0

A modern tree-style CLI for humans and AI prompts.

trls

trls is a modern tree-style CLI that renders file structures for humans and AI prompts.

It is built for two common workflows:

• inspect a project in the terminal with a cleaner, more readable tree view
• export a stable directory snapshot that can be pasted into prompts, docs, or automation

Why trls

Classic tree output is useful, but trls focuses on modern developer workflows:

• rich tree output by default for a polished terminal experience
• prompt output for AI-friendly, copy-pasteable directory snapshots
• snapshot diff by default, so each run shows what changed since last time
• -c clipboard copy for a compact, paste-ready LLM format
• --skill output for agent workflows, with automatic clipboard copy
• always-on progress feedback during scans in interactive terminals
• richer colors for common media, office, and data files
• text output for universal shell compatibility
• markdown output for docs and prompt sharing
• json output for tooling and automation

The first release keeps the scope intentionally small: one command, predictable output, and formats that are easy to copy into AI conversations.

Install

pip install trls-cli

Quick start

Show the current directory:

trls

By default, this compares the current tree against the previous run for the same path. On first run, it simply prints the current tree and creates the baseline.

Export an AI-friendly directory snapshot:

trls . --format prompt

Copy a compact LLM-friendly version to the clipboard while keeping the normal terminal output:

trls . -c

Print the built-in agent skill text and copy it to the clipboard:

trls --skill

In interactive terminals, trls also shows live scan progress so large trees do not feel stuck.

Snapshots are saved automatically after each run. If you want to refresh the baseline without showing any diff markers, force-save it explicitly:

trls . -save

Compare against the previous run for the same path:

trls . -diff

Compare against an explicit snapshot file:

trls . -compare snapshot.json --format prompt

Show a specific directory:

trls path/to/project

Limit traversal depth:

trls . --depth 2

Include hidden files:

trls . --hidden

Ignore noisy paths:

trls . --ignore ".git" --ignore "__pycache__" --ignore "*.pyc"

Export machine-readable output:

trls . --format json

Example output

Prompt output:

[dir] project/
  [doc] README.md
  [meta] pyproject.toml
  [dir] src/
    [dir] trls/
      [py] cli.py
      [py] tree.py

Text output:

project/
|-- README.md
|-- pyproject.toml
`-- src/
    `-- trls/
        |-- cli.py
        `-- tree.py

Markdown output:

- `project/`
  - `README.md`
  - `pyproject.toml`
  - `src/`
    - `trls/`
      - `cli.py`
      - `tree.py`

Prompt diff output:

[dir] project/
  ~ [doc] README.md
  [meta] pyproject.toml
  [dir] src/
    - [py] old.py
    + [py] new.py

Clipboard copy output with -c:

project/
src/trls/: cli.py
root: ~README.md
src/: +new_file.py, -old_file.py

Python API

trls can also be used as a small Python library:

from trls import render_prompt, scan_tree

tree = scan_tree("src", max_depth=2, ignore_patterns=["__pycache__", "*.pyc"])
print(render_prompt(tree))

Snapshot Diff

trls automatically persists a file tree snapshot after each run and can compare future scans against it.

Diff markers:

• + added file or directory
• - removed file or directory
• ~ modified file or directory

Current behavior in v0.5.0:

• every successful run updates the latest snapshot for that path
• default trls output compares against the previous run for that path
• the first --diff-last run creates the baseline automatically if none exists yet
• modification detection is hash-based for files
• directories are marked modified when any descendant changes
• explicit snapshots and automatic "last snapshot" comparison are both supported

Clipboard Copy

Use trls -c to keep the normal terminal render while also copying a compact prompt-oriented version to your clipboard.

Clipboard behavior:

• the first line keeps the root directory name
• later lines group entries by directory, such as src/: cli.py, tree.py
• top-level files are collected under root:
• +, -, and ~ stay inline with each item to preserve diff meaning
• the clipboard payload is intentionally different from the terminal render to save tokens
• WSL-aware clipboard fallbacks are attempted before reporting an error

Agent Skill Output

Use trls -skill or trls --skill to print a built-in English skill block for Cursor-style agents and copy it to the clipboard automatically.

Skill behavior:

• prints a ready-to-paste agent instruction block to stdout
• copies the same text to the clipboard automatically
• tells agents to prefer trls for file structure analysis before broad manual exploration
• suggests --format prompt, --depth, --ignore, and -diff as the primary workflow

Recommended agent command order:

1. Run trls <path> --format prompt for the first structure pass.
2. Add --depth <n> if the repository is too large.
3. Add repeated --ignore <pattern> options to remove noisy folders such as .git, node_modules, dist, or build output.
4. Add --hidden only when hidden files are likely relevant.
5. Use -diff when you want to compare against the previous snapshot.
6. Use -c when you want a compact clipboard-oriented summary.

Common agent examples:

trls . --format prompt
trls . --format prompt --depth 2
trls . --format prompt --ignore .git --ignore node_modules --ignore dist
trls src --format prompt --depth 3
trls . -diff --format prompt
trls . -c
trls --skill

Progress And Color UX

• interactive runs show a transient progress indicator while scanning
• image files such as .jpg and .png have their own color family
• video files such as .mp4 have their own color family
• spreadsheet and office files such as .xlsx, .csv, .docx, and .pptx have their own color family
• data-oriented files such as .parquet and .ipynb are also colorized

CLI contract for v0.5.0

The first public release guarantees:

• scan the current directory or a user-provided path
• five output formats: rich, prompt, text, markdown, and json
• rich is the default output format
• default output is also a diff against the previous run when a baseline exists
• hidden files are excluded by default and included with --hidden
• ignore rules may be repeated with --ignore
• snapshots are automatically updated after successful runs
• snapshot diffing is available via -save/--save-snapshot, -diff/--diff-last, -compare/--compare-with, and -update/--update-snapshot
• clipboard copy is available via -c/--copy
• agent skill output is available via -skill/--skill
• interactive scans show live progress feedback
• directories are listed before files and names are sorted case-insensitively
• unreadable directories are reported in the output instead of crashing the renderers

Development

On macOS or Linux:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[dev]"
pytest

On Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e ".[dev]"
pytest

Release

Build locally:

python -m build
twine check dist/*

Recommended flow:

1. Upload a test release to TestPyPI.
2. Verify pip install, trls --version, and one real CLI example.
3. Publish the tagged release to PyPI with Trusted Publishing.

.venv\Scripts\Activate.ps1 Remove-Item -Recurse -Force .\dist python -m pytest python -m build python -m twine check dist/* python -m twine upload --disable-progress-bar dist/* See RELEASING.md and .github/workflows/publish.yml for the release checklist.