Smart, safe, cross-platform CLI file organizer.
FOLDR cleans messy directories by sorting files into category folders — instantly, predictably, and safely. Preview every action before anything moves. Undo anything. Watch a folder and keep it tidy automatically.
Installation · Quick Start · All Commands · Watch Mode · Undo & History · Configuration
pip install foldrRequires Python 3.10+. Works on Windows, Linux, macOS
# Preview what would happen (nothing moves)
foldr ~/Downloads --preview
# Organize (shows preview, asks to confirm)
foldr ~/Downloads
# Undo the last operation
foldr undo
# Watch a folder — organize now and keep watching
foldr watch ~/DownloadsPaths with spaces must be quoted:
foldr "D:\My Downloads" --preview
foldr <path> # organize (preview → confirm → move)
foldr <path> --preview # dry-run: show plan, nothing moves
foldr <path> --recursive # also organize subdirectories
foldr <path> --recursive --depth 2 # limit to 2 levels deep
foldr <path> --ignore "*.log" "tmp/" # skip patterns this run
foldr <path> --no-ignore # disable all ignore rules
foldr <path> --show-ignored # list skipped files
foldr <path> --verbose # print every file moved
foldr <path> --quiet # no output (for scripts / cron)
foldr <path> --config myconfig.toml # use a custom category config# ⚠ IRREVERSIBLE — always preview first
foldr <path> --dedup keep-newest --preview
foldr <path> --dedup keep-newest # delete older copies
foldr <path> --dedup keep-largest # delete smaller copies
foldr <path> --dedup keep-oldest # delete newer copiesfoldr watch <path> # organize now + keep watching
foldr watch <path> --recursive # watch subdirectories too
foldr watch <path> --preview # watch mode, log only (no moves)
foldr watches # list active watchers
foldr unwatch <path> # stop a specific watcher
foldr unwatch # interactive pickerfoldr undo # undo the last operation
foldr undo --id a1b2c3 # undo a specific operation by ID
foldr undo --preview # show what would be restored
foldr history # list last 50 operations
foldr history --all # list all operations everfoldr config # show config file locations
foldr config --edit # open config.toml in your editor
foldr config --edit --ignore-file # open .foldrignore in your editorWatch mode has two jobs: organize what's already there, then keep watching forever.
foldr watch ~/DownloadsWhen you run this:
- FOLDR organizes all existing files in
~/Downloadsimmediately (same as runningfoldr ~/Downloads). - FOLDR then watches the folder in the background. Any file you drop, copy, or move into it gets organized automatically — within about one second.
- If you move an already-organized file back to the root, it gets re-organized again. No stale state.
The watcher runs until your machine shuts down or you stop it with foldr unwatch.
See all active watchers:
foldr watchesStop watching:
foldr unwatch ~/DownloadsWatch logs (for debugging) live at:
~/.foldr/watch_logs/<dirname>.log
Files are classified by extension and moved into category folders at the root of the target directory. Existing folders are never touched. Filename conflicts are resolved automatically by appending _(1), _(2), etc.
| Category | Folder | Common extensions |
|---|---|---|
| Documents | Documents/ |
.pdf .doc .docx .odt .md .tex |
| Images | Images/ |
.jpg .png .gif .webp .heic .raw |
| Videos | Videos/ |
.mp4 .mkv .mov .avi .webm |
| Audio | Audio/ |
.mp3 .wav .flac .aac .ogg |
| Archives | Archives/ |
.zip .rar .7z .tar .gz |
| Code | Code/ |
.py .js .ts .html .css .java .cpp |
| Scripts | Scripts/ |
.sh .bash .ps1 .bat .cmd |
| Spreadsheets | Spreadsheets/ |
.xlsx .xls .csv .ods |
| Presentations | Presentations/ |
.pptx .ppt .odp |
| Databases | Databases/ |
.db .sqlite .sqlite3 |
| Executables | Executables/ |
.exe .msi .deb .rpm .apk .dmg |
| Fonts | Fonts/ |
.ttf .otf .woff .woff2 |
| Ebooks | Ebooks/ |
.epub .mobi .azw |
| Notebooks | Notebooks/ |
.ipynb |
| Text & Data | Text_Data/ |
.txt .json .xml .yaml .toml |
Files with unrecognised extensions are left in place — never moved.
Every organize operation is saved to ~/.foldr/history/. You can undo any operation independently — no need to undo in order.
foldr history # see what's available
foldr undo # undo the most recent
foldr undo --id a1b2 # undo a specific oneIf a file was moved again after the operation you're undoing, FOLDR skips it and tells you — it never blindly overwrites later changes.
Dedup cannot be undone —
--deduppermanently deletes files. Always--previewfirst.
FOLDR auto-creates ~/.foldr/config.toml on first run. Edit it to add extensions or create your own categories:
[foldr]
merge = true # true = extend built-ins | false = replace them
[Images]
extensions = [".heic", ".avif", ".raw"] # adds to built-in Images
[RAW Photos]
folder = "RAW_Photos"
extensions = [".cr2", ".nef", ".arw", ".dng", ".orf"]
[Design]
folder = "Design"
extensions = [".fig", ".sketch", ".xd", ".psd", ".ai"]Open in editor:
foldr config --editCreate ~/.foldr/.foldrignore (global, applies to all runs):
# ~/.foldr/.foldrignore
*.tmp
*.bak
desktop.ini
~$*
Thumbs.db
Or pass patterns for one run:
foldr ~/Downloads --ignore "*.log" "tmp/" "DO_NOT_MOVE*"Disable all rules for one run:
foldr ~/Downloads --no-ignore| Platform | Config | History | Watch logs |
|---|---|---|---|
| Linux / macOS | ~/.foldr/config.toml |
~/.foldr/history/ |
~/.foldr/watch_logs/ |
| Windows | %USERPROFILE%\.foldr\config.toml |
%USERPROFILE%\.foldr\history\ |
%USERPROFILE%\.foldr\watch_logs\ |
- Preview by default — FOLDR shows you what it will do and asks before moving anything.
- Folders are never touched — only files are moved; directories stay where they are.
- Conflict-safe — if a file with the same name already exists at the destination, FOLDR renames the incoming file (
photo_(1).jpg, etc.) rather than overwriting. - Undo anything — every operation is reversible via
foldr undo. - Dedup is the only irreversible action — always use
--previewbefore--dedup.
If FOLDR saves you time or improves your workflow, consider supporting its continued development and maintenance:
Muhammad Qasim GitHub: github.com/qasimio LinkedIn: linkedin.com/in/qasimio
