Quick Start

Installation

Option 1: Install from PyPI (recommended)

# Install the package
pip install qbt-rules

# Create config directory (if not exists)
mkdir -p ~/.config/qbt-rules

# Download example configurations
curl -o ~/.config/qbt-rules/config.yml \
  https://raw.githubusercontent.com/andronics/qbt-rules/main/config/config.example.yml
curl -o ~/.config/qbt-rules/rules.yml \
  https://raw.githubusercontent.com/andronics/qbt-rules/main/config/rules.example.yml

# Edit config with your qBittorrent credentials
nano ~/.config/qbt-rules/config.yml

Option 2: Install from source

# Clone the repository
git clone https://github.com/andronics/qbt-rules.git
cd qbt-rules

# Install in editable mode
pip install -e .

# Copy example configurations
cp config/config.example.yml config/config.yml
cp config/rules.example.yml config/rules.yml

Basic Configuration

1. Set qBittorrent Connection

   Edit config/config.yml or set environment variables:

   export QBITTORRENT_HOST="http://localhost:8080"
   export QBITTORRENT_USER="admin"
   export QBITTORRENT_PASS="your_password"

2. Enable qBittorrent Web UI

   • Open qBittorrent → Tools → Options → Web UI
   • Check "Web User Interface (Remote control)"
   • Set username and password
   • Note the port (default: 8080)

Your First Rule

Let's create a simple rule to auto-categorize HD movies.

Edit config/rules.yml:

rules:
  - name: "Auto-categorize HD movies"
    enabled: true
    stop_on_match: false
    conditions:
      all:
        - field: info.name
          operator: matches
          value: '(?i).*(1080p|2160p|4k).*'
        - field: info.category
          operator: ==
          value: ""
    actions:
      - type: set_category
        params:
          category: movies-hd
      - type: add_tag
        params:
          tags:
            - hd
            - auto-categorized

What this rule does:

1. Matches: Torrents with "1080p", "2160p", or "4k" in the name (case-insensitive)
2. AND: Currently have no category assigned
3. Actions: Sets category to "movies-hd" and adds tags

Important: Create the "movies-hd" category in qBittorrent first!

Testing Your Setup

Dry-run mode (see what would happen without making changes):

qbt-rules --dry-run

Expected output:

2024-12-10 12:00:00 | INFO     | Successfully authenticated with qBittorrent
2024-12-10 12:00:00 | INFO     | Loaded 1 rules (execute in file order)
2024-12-10 12:00:00 | INFO     | Would set_category Movie.2160p.BluRay to movies-hd (params={'category': 'movies-hd'})
2024-12-10 12:00:00 | INFO     | Would add_tag Movie.2160p.BluRay (params={'tags': ['hd', 'auto-categorized']})
2024-12-10 12:00:00 | INFO     | Rule 'Auto-categorize HD movies' matched 1 torrent(s)

Run for real (remove --dry-run):

qbt-rules

Other useful commands:

# Validate rules syntax
qbt-rules --validate

# List all enabled rules
qbt-rules --list-rules

# Debug with trace logging
qbt-rules --dry-run --trace

# Override log level
qbt-rules --dry-run --log-level DEBUG

Congratulations! You've created your first automation rule. Continue reading for comprehensive documentation.