I built a minimal file organizer CLI and underestimated filesystem case

I built a small CLI tool that organizes files in the current directory based on their extensions.

The idea came from staring at my messy “Downloads” folder and thinking: what if I could fix this with a single command?

The tool is intentionally minimal and opinionated:

- It groups files into predefined categories (Images, Documents, Archives, Code, etc.)

- It never deletes or overwrites anything

- It stops execution if a filename collision is detected

- It only operates inside the current working directory

- It works out of the box, but also includes optional flags like --only, --exclude, and --preview

One interesting lesson was around hidden/system files.

In early versions, any unrecognized extension was moved into an “Others” folder. That worked — until I enabled hidden files and realized system files were being moved too.

That forced me to rethink what “safe by default” really means. Now the tool only moves explicitly whitelisted extensions.

Another issue I underestimated was filename collisions. Currently, if a file already exists in the target folder, execution stops and shows an error.

I’m now thinking about:

- Whether to implement safer/atomic move strategies

- How to handle large numbers of files more robustly

- Whether user-defined extension mappings are worth the added complexity

It’s built with plain Node.js (no TypeScript), using minimal dependencies (Chalk and Ora).

I’d really appreciate feedback, especially around:

- Filesystem edge cases I might not be considering

- Safer move strategies

- The trade-off between minimalism and flexibility in CLI tools

Repo: https://github.com/ChristianRincon/auto-organize