filemindr 1.1.0

Declarative local file pipelines in Python

Filemindr

Declarative local file automation using profiles.

Filemindr lets you describe what should happen to your files, not how.

You define rule pipelines in YAML, group them into profiles, and run them safely through a clean CLI.

Built as a learning and portfolio project with strong focus on:

• predictable behavior
• safety by default
• excellent CLI DX

---

Features

• Profile-based configuration in ~/.filemindr
• Declarative YAML rules
• Rule engine with priority, where the highest match wins
• Match by:
  • file extension
  • filename regex
  • file age with older_than_days
• Actions:
  • move_to
  • copy_to
  • rename_template
• Global and per-rule conflict policies:
  • rename
  • skip
  • overwrite
  • trash
• Dry-run mode
• Explain mode
• Watch mode
• Final summary report
• Structured logging with INFO and DEBUG
• Cross-platform support for Windows, macOS, and Linux

---

Installation

pipx install filemindr

or

pip install filemindr

Development setup:

uv sync --extra dev

---

Profiles

Instead of a single global YAML, Filemindr uses profiles.

Each profile lives in:

~/.filemindr/rules/<profile>/rules.yaml

And all profiles are registered in:

~/.filemindr/profiles.yaml

This allows:

• multiple setups such as home, work, or media
• explicit selection via CLI
• zero ambiguity about which config is running

---

Quick Start

Create your first profile:

filemindr profile init home

This creates:

~/.filemindr/
├── profiles.yaml
└── rules/
    └── home/
        └── rules.yaml

Open and edit the rules:

filemindr profile open home

Example rules.yaml:

source: ~/Downloads
default_target: ~/Downloads/others
conflict_policy: rename

rules:
  - name: invoices
    priority: 100
    match:
      extensions: ["pdf"]
      regex: "(?i)invoice|nota|nf"
    action:
      move_to: ~/Downloads/finance/invoices

  - name: dated-pdfs
    priority: 70
    match:
      extensions: ["pdf"]
    action:
      move_to: ~/Downloads/archive/{yyyy}/{mm}
      rename_template: "{stem}_{yyyy}-{mm}{suffix}"

  - name: images
    priority: 40
    match:
      extensions: ["jpg", "png", "webp"]
    action:
      move_to: ~/Downloads/images

Important notes:

• Rule priority matters. If two rules match the same file, the higher priority wins.
• rename_template only defines the final file name, not folders.
• move_to and copy_to can use templates in the destination path.

Supported template fields:

• {name}
• {stem}
• {suffix}
• {ext}
• {parent}
• {yyyy}
• {mm}
• {dd}

Preview:

filemindr run -p home --dry-run

Verbose preview:

filemindr run -p home --dry-run --log-level DEBUG

Run:

filemindr run -p home

---

Profile Commands

Create:

filemindr profile init home

List:

filemindr profile list

Show path:

filemindr profile show home

Open in editor:

filemindr profile open home

Remove completely:

filemindr profile remove home

---

Watch Mode

Continuous:

filemindr watch -p home

Single batch:

filemindr watch -p home --once

---

Explain Mode

Explain a directory:

filemindr explain -p home ~/Downloads

Explain a single file with spaces in the path:

filemindr explain -p home "C:\Users\you\Downloads\Day Trade-2025.pdf"

---

Validate

filemindr validate -p home

---

Doctor

filemindr doctor

---

Conflict Policy

Supported values:

• rename
• skip
• overwrite
• trash

---

Development

Install development dependencies:

uv sync --extra dev

Run tests:

uv run pytest -q

---

Status

Current release line: 1.1.x

---

License

MIT