Introduction

What is qbt-rules?

qbt-rules is a Python-based rules engine that automates torrent management through the qBittorrent Web API v5.0+. It allows you to define declarative rules in YAML format that automatically organize, manage, and maintain your torrents based on custom conditions—no manual intervention required once configured.

Why Use This?

Save Time & Effort:

• Automatically categorize torrents based on content patterns (movies, TV shows, resolution)
• Clean up old or completed torrents to save disk space
• Tag and organize torrents from specific trackers
• Enforce ratio requirements for private trackers
• Block unwanted content immediately upon arrival
• Manage bandwidth limits dynamically based on conditions
• Handle hundreds of torrents without manual work

Flexible & Powerful:

• Declarative YAML configuration (no coding required)
• Rich condition operators (equality, comparison, regex, time-based)
• Access to 8 different qBittorrent API endpoint categories
• Multiple trigger types (manual, scheduled, webhooks)
• Dry-run mode for safe testing
• Idempotent actions prevent unnecessary operations

Key Features

✅ Declarative YAML Configuration - Define rules in easy-to-read YAML files

✅ Multiple Trigger Types - Manual CLI, scheduled cron, or real-time webhooks

✅ Rich Condition Operators - Equality, comparison, regex, time-based, list operations

✅ Dot Notation Field Access - Access 8 API categories: info, trackers, files, peers, properties, webseeds, transfer, app

✅ File-Order Execution - Rules execute top-to-bottom for predictable behavior

✅ Idempotent Actions - Smart skipping prevents redundant operations

✅ Dry-Run Mode - Test rules safely without making changes

✅ Comprehensive Logging - Detailed logs with optional trace mode

✅ User-Friendly Errors - Clear error messages with fix suggestions

✅ Docker Ready - Includes Docker configuration for easy deployment

✅ qBittorrent v5.0+ Support - Uses latest API endpoints

✅ Custom Triggers (v0.3.0+) - Define your own trigger names for flexible scheduling

✅ Trigger-Agnostic Mode (v0.3.0+) - Run all rules regardless of trigger filters

✅ Human-Readable Sizes (v0.3.0+) - Use intuitive syntax like "50GB" or "100MB"

✅ Nested Conditions - Complex boolean logic with nested all/any/none groups

Requirements

• Python: 3.8 or higher
• qBittorrent: 5.0 or higher with Web UI enabled
• Installation: pip install qbt-rules
• System: Linux, macOS, Windows (or Docker)