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:

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!