Metadata-Version: 2.4
Name: trls-cli
Version: 0.3.0
Summary: A modern tree-style CLI for humans and AI prompts.
Author: Yonglin and Yuanben
License: MIT
License-File: LICENSE
Keywords: cli,filesystem,llm,prompt,tree
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: rich>=13.9.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: pytest>=8.3.4; extra == 'dev'
Requires-Dist: twine>=6.1.0; extra == 'dev'
Description-Content-Type: text/markdown

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

```bash
pip install trls-cli
```

## Quick start

Show the current directory:

```bash
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:

```bash
trls . --format prompt
```

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

```bash
trls . -c
```

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:

```bash
trls . -save
```

Compare against the previous run for the same path:

```bash
trls . -diff
```

Compare against an explicit snapshot file:

```bash
trls . -compare snapshot.json --format prompt
```

Show a specific directory:

```bash
trls path/to/project
```

Limit traversal depth:

```bash
trls . --depth 2
```

Include hidden files:

```bash
trls . --hidden
```

Ignore noisy paths:

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

Export machine-readable output:

```bash
trls . --format json
```

## Example output

Prompt output:

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

Text output:

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

Markdown output:

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

Prompt diff output:

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

Clipboard copy output with `-c`:

```text
project/
paths: project/src/, project/src/trls/, project/src/trls/cli.py, project/README.md
modified: project/README.md
added: project/src/new_file.py
removed: project/src/old_file.py
```

## Python API

`trls` can also be used as a small Python library:

```python
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.3.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 compress paths into small labeled blocks such as `paths:`, `modified:`, `added:`, and `removed:`
- full root-prefixed paths are preserved to keep context for LLMs
- the clipboard payload is intentionally different from the terminal render to save tokens
- WSL-aware clipboard fallbacks are attempted before reporting an error

## 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.3.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`
- 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:

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

On Windows PowerShell:

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

## Release

Build locally:

```bash
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.
