Metadata-Version: 2.4
Name: trls-cli
Version: 0.2.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
- `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
```

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/
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:

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

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