trls-cli 0.2.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
• 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

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/
project/src/
project/src/trls/
project/src/trls/cli.py
~ project/README.md
+ project/src/new_file.py
- project/src/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.2.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
• every later line uses a full root-prefixed path
• +, -, and ~ diff markers are preserved
• the clipboard payload is intentionally different from the terminal render to save tokens

CLI contract for v0.2.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
• 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.

See RELEASING.md and .github/workflows/publish.yml for the release checklist.