filemindr 1.0.0

Declarative local file pipelines in Python

Filemindr --- Rule-Driven Local File Automation (v2)

Declarative local file automation using profiles.

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

You define rule pipelines in YAML (extensions, regex, age, priority), group them into profiles, and run them safely via a clean CLI.

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

• predictable behavior\
• safety by default\
• excellent CLI DX

---

✨ Features (v2)

Core

• Profiles-based configuration (~/.filemindr)
• Declarative YAML rules
• Rule engine with priority (highest wins)
• Match by:
  • file extensions
  • regex on filename
  • file age (older_than_days)
• Actions:
  • move_to
  • copy_to
• Global and per-rule conflict policies:
  • rename
  • skip
  • overwrite
  • trash
• Dry-run mode
• Final summary report
• Structured logging (INFO, DEBUG)
• Cross-platform (Windows, macOS, Linux)

---

📦 Installation

pipx install filemindr

or

pip install filemindr

Dev:

uv sync

---

🧠 Profiles (core concept)

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 (home, work, media, etc)
• 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: images
    priority: 40
    match:
      extensions: ["jpg", "png", "webp"]
    action:
      move_to: ~/Downloads/images

Preview:

filemindr run -p home --dry-run

Run:

filemindr run -p home

Verbose:

filemindr run -p home --log-level DEBUG

---

📂 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

filemindr explain -p home ~/Downloads

---

✅ Validate

filemindr validate -p home

---

🩺 Doctor

filemindr doctor

---

⚔ Conflict Policy

Supported:

• rename
• skip
• overwrite
• trash

---

🧪 Development

uv run pytest

---

🛠 Status

Stable v2.

---

📄 License

MIT