organize: rule-based file management automation from the command line

What organize solves, and who ends up writing YAML

The README opens with a fairly blunt description of the problem: your desktop is a mess, downloads and documents are unsorted, and doing it by hand is tedious. organize is the answer to that, and it positions itself as "a command line, open-source alternative to apps like Hazel (macOS) or File Juggler (Windows)." The people who get value from it are the ones who already think in rules: sort pictures into folder structures using EXIF data, rename PDF invoices based on file content, delete incomplete downloads, clear unused files off the desktop, or free disk space by removing duplicates. The README lists exactly these as common uses, along with "automating various business processes."

The audience is narrower than the tagline suggests. This is not a tool you point at a folder and forget. You write a config.yaml, you run a command, and you inspect the result. If you want a background service that watches a directory and reacts within a second of a file appearing, organize is not that, and the documentation does not present it as one. If you are comfortable editing a text file and re-running a command, the trade is a good one: the sorting logic becomes a reviewable artifact instead of a habit.

Rules, filters, actions: the shape of a config

A rule is a named block with three moving parts. locations says where to look, subfolders says whether to descend, filters decide which files survive, and actions say what happens to them. The README's first example is about as small as this gets: find PDFs in ~/Downloads, including subfolders, and echo a line for each one. Nothing is touched until an action that writes is added.

The filter vocabulary visible in the README covers extension, name (with a contains list and a case_sensitive flag), created, and empty. Actions include echo, move, copy, delete, confirm, and the README also mentions running shell or Python code inline as either filters or actions. Templates use placeholder variables: the advanced example builds a destination from {extension.upper()} and {created.strftime('%Y-%m')}, and passes on_conflict: rename_new so a name collision gets a counter appended instead of overwriting. That template engine is Jinja2 according to the dependency list in pyproject.toml, which is why the expression syntax looks familiar.

Two details are worth flagging. First, locations can point at more than a local path: the advanced example includes an ftps:// URL and mentions ZIP, so the same rule can span a local folder and a remote one. Second, max_depth limits recursion, which matters when you point a rule at a home directory and do not want it walking everything.

Install organize-tool with pip and run your first rule

The README states that only Python 3.9 or newer is needed, and that installation goes through pip. The package name on PyPI is organize-tool, not organize, which is the first thing that trips people up. The same command updates an existing install.

pip install -U organize-tool

After that, organize --help should print the command list. The README gives organize new followed by organize edit as the way to create and open the configuration. If the editor does not open, organize show --reveal opens the configuration folder in your file manager so you can edit config.yaml directly.

rules:
  - name: "Find PDFs"
    locations:
      - ~/Downloads
    subfolders: true
    filters:
      - extension: pdf
    actions:
      - echo: "Found PDF!"

With that saved, organize run lists every PDF under your downloads folder and its subfolders, printing Found PDF! for each. If the output says Nothing to do, you have no PDFs there. To make it do something, add a move action and simulate first.

actions:
  - echo: "Found PDF!"
  - move: ~/Documents/PDFs/

organize sim

The README says organize sim shows what would happen without touching your files. That is the loop: edit, simulate, read the plan, then run.

Where organize stops being the right tool

The biggest limitation is the one the README does not discuss, because it is architectural. organize is a command you invoke. There is no documented daemon, no filesystem watcher, no scheduled trigger. If your workflow depends on a file being sorted the moment it is saved, you need something else to call organize, and the README does not document how to wire that up. That is a real gap for anyone coming from Hazel, which watches folders continuously.

Second, the safety story is simulation, not rollback. The README says "Everything can be simulated before touching your files," and organize sim is the mechanism. What the README does not document is an undo. Once organize run has moved or deleted files, there is no described way to reverse it. The delete action is worth treating with the same caution as rm, and the send2trash dependency in pyproject.toml suggests deletions may route through the system trash on supported platforms, but the README does not spell out the semantics, so verify before relying on it.

Third, the confirm action blocks on user input, which makes a rule containing it unsuitable for unattended execution. Fourth, rules are only as good as their filters. A name filter with contains: [Invoice, Order, Purchase] will match anything whose filename holds those substrings, and the README's example is deliberately loose. Point a broad rule at a directory you have not simulated against and you will move files you did not mean to move.

organize compared with Hazel and File Juggler

The README names both alternatives directly. Hazel runs on macOS, File Juggler on Windows, and both are graphical applications that watch folders and apply rules as files arrive. organize is the opposite on every axis that matters: command line instead of GUI, cross-platform instead of single-OS, and invoked instead of resident. The README lists macOS, Windows and Linux as supported, and pyproject.toml carries an OS Independent classifier plus a macOS-only dependency (macos-tags) that is installed conditionally on darwin.

The practical difference is what you can review. A Hazel rule lives in a preferences pane; an organize rule lives in a YAML file you can put in git, diff between versions, and copy to another machine. For a single desktop user who wants files sorted automatically with no further thought, Hazel or File Juggler will feel lighter. For someone managing the same folder structure across several machines, or who wants the logic under version control, organize's text-first design is the reason to pick it. There is also a Dockerfile in the repository, which the alternatives do not offer, so containerised or scheduled execution is at least a supported path.

Maintenance, licensing and the cost of staying current

The repository is not archived, and the last push was on 2026-09-21, three days before this writing. The most recent tagged release is v3.3.0 from 2024-11-25, preceded by v3.2.5 in July 2024 and v3.2.4 two days before that. So the release cadence is slow and the commit activity is recent: expect fixes to land on main before they reach a version tag. The README also carries a migration note for v2 to v3, which tells you the project does make breaking changes between major versions, and that upgrading is not always a one-line edit.

The licence is MIT, declared in LICENSE.txt and referenced from pyproject.toml. In practical terms that permits commercial use and modification with attribution and no warranty. That is not legal advice; read LICENSE.txt yourself if the distinction matters to your organisation.

Upgrade cost is mostly dependency-shaped. pyproject.toml pins exifread to exactly 2.3.2 and constrains pdfminer-six, pydantic, jinja2, rich and others to ranges. Installing via pip into a shared environment can therefore collide with other tools, and a virtualenv or the provided Dockerfile is the safer route. Python 3.9 is the floor, so environments still on 3.8 cannot run it at all.

Editorial conclusion

Adopt organize if you keep a stable set of folders and want the sorting logic written down in a file you can review, version and re-run, and if you are willing to spend an afternoon learning the rule schema. Do not adopt it if you want a graphical watcher that reacts the moment a file lands, or if you need per-file confirmation that survives the process, because organize is a batch command you invoke yourself and its confirm action blocks on stdin. Before trusting it with anything you care about, run organize sim against your real config and check the planned list line by line, then confirm that your move actions use on_conflict, since the README does not document rollback for a run that has already executed.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tfeldmann/organize on GitHub