folderly — Simple File Organizer (CLI)

folderly is a small, dependency-free Node.js CLI that scans a directory (non-recursively) and sorts regular files into category folders based on file extension (documents, images, videos, code, etc.). It is designed to be fast and predictable and publishes as an npm binary folderly.

Features

• Classifies files by extension into named folders (documents, images, music, videos, code, archives, etc.)
• Category Filtering: Only organize the file types you care about using flags (e.g., --code --images).
• Built-in help manual (--help) with dynamically generated valid categories.
• Strict error handling (safely fails on typos or missing directories).
• Uses safe filesystem operations (Node's fs/promises and C equivalents)
• Small, standalone entrypoint available in both Node.js and C.
• Case-insensitive extension matching.

Installation

Install globally with npm:

npm install -g folderly

Or run directly with npx:

npx folderly

Usage

Run in the directory you want to organize (defaults to current directory):

folderly
# or specify a path
folderly path/to/dir

Filtering by Category

You can organize only specific types of files by passing their category names as flags. Any files that don't match the provided categories will be ignored.

folderly --code --images
# or combine with a target path
folderly path/to/dir --documents

Example Output

folderly test_foldercopy2/test_folder --code

Folderly - Simple File Organizer
Organizing files in: test_foldercopy2/test_folder
Filtering for categories: code

Moved: typescript.ts -> code/

Done! 1 moved, 0 failed

To see the full list of valid category flags, run the built-in manual:

folderly --help

Example Output

folderly — Simple File Organizer (CLI)

Usage:
  folderly [options] [target_directory]

Arguments:
  target_directory    The directory to organize (defaults to current directory ".")

Options:
  --help, -h          Show this help message
  --<category>        Only organize files of this category (e.g., --code, --music)

Valid Categories:
  3d, archives, backups, certificates, code
  configs, data, design, documents, fonts
  images, logs, music, others, presentations
  programs, spreadsheets, videos

Lets Try:

Example Output

Folderly - Simple File Organizer
Organizing files in: test_folder

Moved: photo.jpg -> images/
Moved: sample.txt -> documents/
Moved: audio.wav -> music/
Moved: movie.mp4 -> videos/
Moved: unknown.xyz -> others/

Done! 5 moved, 0 failed

Notes & Behavior

• Only regular files are moved; subdirectories are left untouched.
• Files with unknown extensions are moved to the others folder.
• If an unrecognized flag is passed (e.g. --documana), the program will abort immediately to prevent partial execution.
• The command uses fs.rename() so moves are fast but can fail across different mount points/filesystems.
• No recursive scanning (only the specified directory level).

NB: Special handling for .ts files

• .ts files are ambiguous (video container vs TypeScript source). To avoid misclassification, folderly implements a size-based rule:
  • If a .ts file is larger than 1024 KB (1,048,576 bytes) it will be moved to the videos folder.
  • If a .ts file is smaller than or equal to 1024 KB it will be moved to the code folder.
  • If the program cannot stat the file to determine size it will fall back to the normal extension-based mapping.

This behavior is intentional and documented so users understand why some .ts files may end up in videos instead of code.

Contributing

Contributions are welcome. Preferred workflow:

1. Fork the repo
2. Create a feature branch: git checkout -b feature/your-change
3. Make changes and add tests if appropriate
4. Commit and push your branch
5. Open a Pull Request

License

MIT. See the LICENSE file for details.

Links

• npm Package
• GitHub Repository
• Issues