tidy

A CLI that organizes a messy folder — safely. Every run previews what it will do before touching a single file, and every real run can be undone.

Install

pip install -e .

(Not on PyPI yet — clone and install locally, or pip install tidy-cli once published.)

Usage

# First time only — creates ~/.tidy/config.toml
tidy init

# Preview only (default) — nothing moves
tidy sort ~/Downloads --by type

# Actually move the files
tidy sort ~/Downloads --by type --apply

# Sort into YYYY/MM folders by last-modified date
tidy sort ~/Downloads --by date --apply

# Sort by filename keyword
tidy sort ~/Downloads --by content --pattern invoice --pattern screenshot --apply

# Find and quarantine duplicate files (by content, not filename)
tidy dedupe ~/Downloads --apply

# Made a mistake? Undo the last run.
tidy undo

# See recent runs
tidy undo --list

Design choices

• Dry-run is the default. You have to explicitly pass --apply to move anything. This is deliberate — a tool that reorganizes your files should never surprise you.
• Nothing is ever permanently deleted. Duplicates go to a .tidy-trash folder inside the target directory, not the void.
• Every real run is logged to ~/.tidy/history/, which is what powers tidy undo.
• Path traversal is blocked at the source. Every planned destination is resolved and checked against the target root before it's used — see tidy/utils.py::resolve_within_root.

Development

pip install -e . pytest ruff
pytest
ruff check src tests

License

MIT "# Tidy" "# Tidy"