Noureddine RAMDI / Organize: YAML-driven file management automation with Python CLI

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
970 Words
github-stars python cli file-automation yaml scripting cross-platform

tfeldmann/organize

File management automation can be surprisingly tedious. Tools like macOS Hazel or Windows File Juggler offer GUI-driven workflows, but they come with licensing costs or platform lock-in. Organize takes a different path: it’s an open-source, cross-platform CLI tool that lets you automate file organization using declarative YAML rules. You write what you want done in a config file, and Organize executes it. This approach treats your filesystem like infrastructure-as-code, making file automation reproducible, versionable, and scriptable.

What organize is and how it works

Organize is a Python-based CLI tool that automates file management according to user-defined rules written in YAML. Each rule specifies locations to scan, filters to select files, and actions to perform on matching files. Filters range from simple extensions and name patterns to more advanced criteria like EXIF metadata and file content extraction (e.g., from PDFs or DOCX files). Actions include moving, copying, renaming, deleting files, or even running inline Python or shell scripts.

The core concept is a declarative rule engine: you describe what you want, not how to traverse directories or write imperative scripts. This separation improves clarity and maintainability. Organize supports safe simulation mode, so you can preview actions without affecting your files.

Under the hood, the tool is implemented in Python (requiring Python 3.9+). It progressively scans specified directories (including subfolders if enabled), applies filters sequentially, then executes actions in order. The YAML config file is the single source of truth for your file management logic.

This design positions Organize as a free alternative to proprietary file automation tools, with the added advantage of deep extensibility via scripting and content-based filtering.

Technical strengths and design tradeoffs

The standout feature of Organize is the YAML-driven declarative rule engine. By using YAML, it achieves human-readable, version-controllable configuration that can express complex pipelines without custom code. Users benefit from:

  • Flexible filtering: Beyond extensions and regex name patterns, filters can inspect EXIF metadata (useful for photos), detect duplicates, or extract content from PDFs and DOCX files to match on text inside documents.

  • Rich actions: Organize supports all the basics (move, copy, rename, delete), plus custom shell or Python script execution per file. This makes the tool highly adaptable to edge cases.

  • Safe simulation mode: You can run organize sim to see what would happen without modifying files, which improves safety and confidence.

  • Template engine: Actions can use placeholders and template variables, enabling dynamic paths or filenames based on file metadata or content.

The tradeoff is some complexity in learning the YAML config syntax and the expressive filters/actions. Users comfortable with scripting might find the declarative approach restrictive until they leverage inline scripting. Also, being Python-based means it requires a Python runtime and dependencies, which could be a hurdle in some environments.

Under the hood, the codebase balances performance improvements in version 3 with extensibility. While not explicitly benchmarked here, the emphasis on performance suggests attention to efficient file scanning and filtering.

Compared to GUI tools, Organize lacks a visual interface, which may slow adoption for non-technical users. However, the CLI plus YAML config makes it ideal for programmers and sysadmins who prefer code-based automation.

Quick start with organize

Getting started with Organize is straightforward if you have Python 3.9+ installed. Installation is done via pip:

pip install -U organize-tool

After installation, verify by running:

organize --help

To create your first rule, run:

organize new

Then edit the configuration with:

organize edit

Here’s a minimal example of a YAML rule to find all PDFs in your Downloads folder and echo a message for each:

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

Save the config file and run:

organize run

You should see a list of all PDFs found. To move PDFs to a specific folder, edit the actions:

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

Run a simulation to preview:

organize sim

This safe mode shows what files would be moved without changing anything.

This example barely scratches the surface. Organize supports renaming, copying, deleting, duplicate detection, regex matching, placeholders, and executing custom scripts.

Verdict

Organize is a solid, code-centric tool for automating complex file management workflows on any platform with Python. It shines for users who prefer declarative configuration and want powerful filters and actions beyond simple pattern matching. The safe simulation mode is a practical feature that encourages experimentation without risk.

The main limitations are the learning curve of the YAML syntax and reliance on Python 3.9+, which may not fit all environments. Also, power users who want full flexibility will need to write inline scripts, which requires some Python or shell knowledge.

Overall, Organize fills a niche for developers, sysadmins, and power users looking for a free, extensible, scriptable alternative to GUI file automation tools. If you manage files regularly and want reproducible automation with transparent configs, it’s worth trying.

→ GitHub Repo: tfeldmann/organize ⭐ 3,041 · Python