Getting Started

Folder Sorter is an open-source CLI program written in Python that helps developers, photographers, and general PC users maintain clean folder systems. It acts as an automated sorting butler, scanning files, grouping them by rules, and cleanly placing them into destination categories.

How to launch:

After completing the one-command installation, run the utility without arguments to enter the **Interactive Menu Mode**:

folder-sorter

Interactive mode guides you through selecting target directories, configuring recursive subdirectory traversal, and performing dry runs without having to remember any command-line options.

Commands & Subcommands

Use subcommands directly from PowerShell or Command Prompt for direct execution or to integrate Folder Sorter into automated background shell scripts.

sort [DIRECTORY]

Organizes target directory (defaults to current directory). Options:

  • -m, --mode [by-type|by-date]: Sorting mode. Default is by-type.
  • -d, --dry-run: Show moves in log without writing changes.
  • -r, --recursive: Traverses subdirectories recursively.
  • -v, --verbose: Display verbose file move operations.

undo

Reverse the last folder sorting run. Re-scans sqlite database moves and puts everything back exactly where it was found.

doctor

Run write diagnostics checks, SQLite database health checks, and Python package dependency validation.

config

Manage configuration variables. Subcommands: show, add [category] [extension], remove [category] [extension], add-category [category].

Custom Configuration

Folder Sorter uses default extension mappings to group files, but you can dynamically customize mappings using CLI commands, the interactive settings menu, or by editing the JSON configuration file directly.

Configurations are saved globally under your home directory:~/.folder-sorter/config.json

View active mapping rules:

folder-sorter config show

Create a new custom category:

folder-sorter config add-category Music

Add a new extension mapping:

folder-sorter config add Music .mp3

Undo System

Mistakes happen. If you sorted the wrong directory, Folder Sorter has an integrated database safety net. When files are moved, a record containing the old path, new path, and transaction timestamp is logged into a local SQLite database under `~/.folder-sorter/history.json` or `history.db`.

Idempotent SafetyTo run a dry run of the undo operation, run `folder-sorter undo --dry-run`. This shows you what files would move without actually changing the filesystem, confirming it's safe to run the actual restoration.

Doctor Diagnostics

If Folder Sorter fails or throws permission errors, run the diagnostic doctor:

folder-sorter doctor

The doctor command performs a validation checklist on Python runtime version, folder read/write permissions, database consistency, and additional libraries (Pillow for image resolution sorting).

Tech Stack & Details

Here is an explanation of the core technologies under the hood of Folder Sorter, keeping it transparent, lightweight, and local.

What is Used (and Why)

  • 1. Python: The entire tool is written in Python, allowing robust cross-platform file manipulation out-of-the-box.
  • 2. Typer: Standardized terminal command library that automatically maps function arguments into flags (like --recursive or --dry-run).
  • 3. Rich: Builds beautiful, colored panels, progress bars, tables, and loading spinners directly inside command lines.
  • 4. Pillow: Image processing framework used to examine image dimensions (resolution pixels) to group them into 4K, 1080p, or 720p folders.
  • 5. JSON Storage: Utilizes flat text JSON configurations (`config.json` and `history.json`) for speed, portability, and zero-dependency reads/writes.

What is NOT Used (and Why)

  • 1. No heavy SQL databases: Flat JSON structures require zero local installations or server setup, keeping Folder Sorter's memory and CPU footprint minimal.
  • 2. No web browsers: Runs entirely inside native terminal sessions (PowerShell, CMD, Bash) for instantaneous startup speeds.
  • 3. No remote cloud servers: Operates 100% locally on your computer. None of your directories, file sizes, or personal content are ever uploaded or sent over the network.

Release Changelog

Track the release history and feature updates of Folder Sorter CLI.

v1.0.3 - Vercel Hosting Migration

Released: June 2026
  • Migrated installation scripts and website hosting to Vercel
  • Created a premium Next.js landing page & docs center
  • Added new config command to dynamically register custom categories
  • Fixed Windows 11 platform diagnostics reporting bug
  • Suppressed shell-completion stderr messages during Windows setup

v1.0.2 - Windows Release Pipeline

Released: June 2026
  • First release pipeline targeting Windows x64 binaries
  • Added lightweight, dependency-free install.ps1 script
  • Enabled auto-updates check against the latest GitHub Releases
  • Integrated doctor diagnostics system

v1.0.1 - CLI Refactor

Released: May 2026
  • Refactored Typer CLI inputs and arguments
  • Polished Rich table layouts, spinners, and help texts
  • Implemented transaction log undo capabilities

Contribution Guidelines

Folder Sorter is an open-source project and we welcome contributions from everyone. Whether you are fixing a bug, adding mapping configurations for new file extensions, or rewriting parts of the documentation, we appreciate your help.

Quick Contribution Steps

  1. Fork and Clone: Fork the repository on GitHub and clone it to your local machine.
  2. Install Dependencies: Run pip install -e . and install developer requirements from requirements-dev.txt.
  3. Create a Branch: Work on a separate feature branch instead of making changes directly to the main branch.
  4. Run Tests: Verify your changes by running the test suite with the pytest command.
  5. Open a Pull Request: Push your branch to GitHub and open a pull request. Make sure to describe the modifications in detail.

Community Issue Labels & Boards

We use labels and project boards to make work visible and structured for contributors:

  • bug: Confirmed issues where the tool behaves incorrectly.
  • enhancement: Requests for new features or user interface improvements.
  • good first issue: Welcoming, isolated bugs suitable for new developers.
  • Project Board: We track active items in four stages: Todo, In Progress, Testing, and Done.

Code of Conduct

To ensure that the Folder Sorter community is welcoming, respectful, and safe for everyone, we ask all contributors to follow our Code of Conduct pledge:

Our PledgeWe pledge to make participation in our community a harassment-free experience for everyone, regardless of age, background, visibility or level of experience.
Our StandardsContributors are expected to use welcoming and inclusive language, remain respectful of differing viewpoints, accept constructive criticism, and show empathy toward other community members. Trolling, insults, and harassment will not be tolerated.

Frequently Asked Questions

Will Folder Sorter overwrite my existing files?

No. If a file with the same name already exists in the destination category folder, Folder Sorter automatically renames the incoming file (e.g. `document_1.pdf`) to avoid data collisions.

Does the tool require an active internet connection?

Only during checking for updates. All sorting, undo transactions, and custom configuration modifications are executed locally on your hard drive.

Troubleshooting

PATH Variables

If PowerShell displays `folder-sorter: command not found` after a successful install, close and reopen your PowerShell window. The new PATH updates will only be loaded by terminal prompts on system initialization.

Antivirus False Positives

PyInstaller wraps the Python executable inside a single binary which might trigger false flags on default Windows Defender scans. If this occurs, allowlist the directory `%LOCALAPPDATA%\FolderSorter\` in your security center.