Every developer’s Downloads folder eventually becomes a chaotic digital landfill. Screenshots, random PDF receipts, compressed archives, test datasets, and CLI binaries pile up until finding anything becomes a chore.
Like most engineers, I initially relied on ad-hoc Bash one-liners. But quick scripts have major flaws:
- They fail silently or overwrite files when file names collide.
- One wrong flag or typo can accidentally move or delete critical files.
- There is no rollback mechanism if you change your mind.
To solve this once and for all, I built CleanDrop — a lightweight, zero-dependency Node.js CLI utility designed to organize cluttered folders safely, predictably, and reversibly.
Key Design Principles
When designing CleanDrop, developer safety and ergonomics were the top priorities:
1. Dry-Run by Default Mentality (--dry-run)
Moving hundreds of files without knowing where they will land is terrifying. CleanDrop allows you to simulate the entire sorting process first:
npx cleandrop --dry-run
It prints an exact audit table of source paths, target categories, and planned file actions without touching disk storage.
2. Built-in Undo Support (Atomic Transaction Log)
Accidents happen. CleanDrop logs batch actions to a local history journal. If you run a sort and realize you wanted to keep certain files in place, you can reverse the operation with a single command:
npx cleandrop --undo
3. Non-Destructive Conflict Resolution
CleanDrop never silently overwrites an existing file. If invoice.pdf already exists in Documents/, the tool renames the incoming file safely (e.g., invoice (1).pdf), ensuring zero data loss.
4. Zero Heavy Dependencies
The entire CLI is powered by native Node.js filesystem APIs (fs/promises, path). It starts instantly and doesn't require bloated npm dependency trees.
How it Categorizes Files
CleanDrop inspects file extensions and maps them into clean, logical target folders:
| Category | Extensions Handled |
|---|---|
| Documents |
.pdf, .docx, .txt, .xlsx, .pptx, .csv, .md
|
| Images |
.png, .jpg, .jpeg, .gif, .svg, .webp
|
| Archives |
.zip, .tar.gz, .rar, .7z, .tar
|
| Code & Data |
.js, .ts, .py, .json, .sql, .html
|
| Media |
.mp4, .mov, .mp3, .wav, .mkv
|
System files, hidden dotfiles (.DS_Store, .git), and already organized subdirectories are safely ignored.
Quick Start in 5 Seconds
You don't even need to install it globally. Run it directly with npx:
# 1. Preview changes first
npx cleandrop --dry-run
# 2. Run the organization
npx cleandrop
Source Code & Contributing
CleanDrop is 100% open-source under the MIT license.
🔗 GitHub Repository: github.com/mahdyarmonfared/cleandrop
I would love to get your thoughts:
- What safety features do you look for in automated file management tools?
- What file types or custom rule options would you like to see next?
If you find it useful, feel free to drop a star ⭐ on GitHub or open an issue with your suggestions!
Top comments (0)