Triggers

Triggers determine when and how rules execute.

Unified CLI (v0.3.0+)

Since v0.3.0, all trigger functionality is unified into a single qbt-rules command. The trigger type is specified via the --trigger flag instead of separate scripts.

Key Changes:

• ✅ Single command: qbt-rules (replaces manual.py, scheduled.py, etc.)
• ✅ Trigger selection: --trigger manual|scheduled|on_added|on_completed|custom
• ✅ Default trigger: manual (when --trigger is omitted)
• ✅ Custom triggers: Define your own trigger names (e.g., --trigger hourly)
• ✅ Trigger-agnostic mode: --trigger none to run all rules regardless of trigger filters

Overview

Trigger	Use Case	Execution Method	Torrent Scope	Best For
manual	Testing, one-off operations	qbt-rules (default)	All torrents	Development, troubleshooting
scheduled	Periodic maintenance	qbt-rules --trigger scheduled	All torrents	Cleanup, ratio enforcement
on_added	React to new torrents	qbt-rules --trigger on_added --hash HASH	Single torrent	Content filtering, auto-categorization
on_completed	React to finished downloads	qbt-rules --trigger on_completed --hash HASH	Single torrent	Post-download actions, seeding rules
custom	User-defined triggers	qbt-rules --trigger <name>	All or single	Custom workflows

Manual Trigger

Description: Direct execution from command line. Ideal for testing rules, debugging issues, and performing one-off operations.

Command: qbt-rules (trigger defaults to manual)

Usage:

# Run all rules against all torrents (manual trigger is default)
qbt-rules

# Explicitly specify manual trigger
qbt-rules --trigger manual

# Dry-run mode (show what would happen, make no changes)
qbt-rules --dry-run

# Custom config directory
qbt-rules --config-dir /path/to/config

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

# Enable trace mode (detailed logging with module/function/line)
qbt-rules --trace

# Validate rules syntax without execution
qbt-rules --validate

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

# Show version
qbt-rules --version

# Combine flags
qbt-rules --dry-run --log-level DEBUG --trace

When to Use:

• Testing new rules before scheduling them
• Debugging issues with verbose logging
• Manual cleanup operations (e.g., after bulk adding torrents)
• Validating configuration changes
• Learning how rules work with --dry-run

Example Output:

2024-12-10 12:00:00 | INFO     | Successfully authenticated with qBittorrent at http://localhost:8080
2024-12-10 12:00:00 | INFO     | ============================================================
2024-12-10 12:00:00 | INFO     | Starting qBittorrent automation engine
2024-12-10 12:00:00 | INFO     | Trigger: manual
2024-12-10 12:00:00 | INFO     | Dry run mode: True
2024-12-10 12:00:00 | INFO     | ============================================================
2024-12-10 12:00:00 | INFO     | Fetched 253 torrent(s)
2024-12-10 12:00:00 | INFO     | Loaded 5 rules (execute in file order)
2024-12-10 12:00:00 | INFO     | Processing rule: Auto-categorize HD movies
2024-12-10 12:00:00 | INFO     | Would set_category Movie.2160p.BluRay to movies-hd
2024-12-10 12:00:00 | INFO     | Rule 'Auto-categorize HD movies' matched 1 torrent(s)
2024-12-10 12:00:00 | INFO     | ============================================================
2024-12-10 12:00:00 | INFO     | Execution complete - Summary:
2024-12-10 12:00:00 | INFO     |   Total torrents: 253
2024-12-10 12:00:00 | INFO     |   Processed: 0
2024-12-10 12:00:00 | INFO     |   Rules matched: 1
2024-12-10 12:00:00 | INFO     |   Actions executed: 2
2024-12-10 12:00:00 | INFO     |   Actions skipped (idempotent): 0
2024-12-10 12:00:00 | INFO     | ============================================================

Scheduled Trigger

Description: Automated execution via cron for periodic maintenance tasks.

Command: qbt-rules --trigger scheduled

Setup:

# Edit crontab
crontab -e

# Run every 15 minutes
*/15 * * * * qbt-rules --trigger scheduled >> /var/log/qbt-rules.log 2>&1

# Run every hour
0 * * * * qbt-rules --trigger scheduled

# Run daily at 3 AM
0 3 * * * qbt-rules --trigger scheduled

# Run every 6 hours
0 */6 * * * qbt-rules --trigger scheduled

Docker Setup:

Add to docker-compose.yml:

services:
  qbt-rules-scheduler:
    image: python:3.11-slim
    volumes:
      - ./config:/config
    environment:
      - QBITTORRENT_HOST=http://qbittorrent:8080
      - QBITTORRENT_USER=admin
      - QBITTORRENT_PASS=password
    command: |
      sh -c 'pip install qbt-rules && \
        while true; do
          qbt-rules --trigger scheduled
          sleep 900
        done'

Or use system cron with Docker exec:

# Install qbt-rules in container first, then run via cron
*/15 * * * * docker exec qbt-rules-scheduler qbt-rules --trigger scheduled

Best Practices:

• Interval: 15-60 minutes for most use cases
• Monitoring: Direct output to log file for troubleshooting
• Testing: Run manually first to verify behavior
• Dry-run: Test with cron using --dry-run initially

When to Use:

• Removing old/completed torrents automatically
• Enforcing ratio requirements periodically
• Bandwidth limit adjustments based on time/conditions
• Periodic reannounce operations
• Tagging torrents based on age or status

Example Rules for Scheduled:

rules:
  - name: "Remove old completed torrents"
    enabled: true
    conditions:
      trigger: [scheduled, manual]  # Run on schedule, allow manual testing
      all:
        - field: info.completion_on
          operator: older_than
          value: 30 days
        - field: info.ratio
          operator: ">="
          value: 1.0
    actions:
      - type: delete_torrent
        params:
          keep_files: false

On Added Trigger (Webhook)

Description: Triggered immediately when qBittorrent adds a new torrent. Executes for a single torrent identified by hash.

Command: qbt-rules --trigger on_added --hash HASH

qBittorrent Configuration:

1. Open qBittorrent → Tools → Options → Downloads
2. Scroll to "Run external program on torrent added"
3. Check the box to enable
4. Set command:

Bare Metal:

qbt-rules --trigger on_added --hash "%I"

Docker:

docker exec qbt-rules-container qbt-rules --trigger on_added --hash "%I"

Or if qbt-rules runs inside qBittorrent container:

qbt-rules --trigger on_added --hash "%I"

Important: %I is qBittorrent's placeholder for torrent info hash (required)

Usage in Rules:

To make a rule execute only on the on_added trigger:

conditions:
  trigger: on_added
  any:
    - field: info.name
      operator: contains
      value: "unwanted"

Best Practices:

• Keep processing lightweight - Only single torrent, but triggered frequently
• Avoid expensive API calls - Don't use files.* or trackers.* unless necessary
• Use for immediate actions - Categorization, tagging, filtering
• Fast decisions - Block unwanted content before download starts

When to Use:

• Content filtering - Block/stop unwanted torrents immediately
• Auto-categorization - Assign category based on name/tracker
• Initial tagging - Tag by tracker, content type, or name pattern
• Download priority - Set force_start for important torrents

Example Rules for On Added:

# Block unwanted file types immediately
- name: "Block archive files on add"
  enabled: true
  stop_on_match: true
  conditions:
    trigger: on_added
    any:
      - field: files.name
        operator: matches
        value: '(?i)\.(rar|zip|7z)$'
  actions:
    - type: stop
    - type: add_tag
      params:
        tags:
          - blocked-archive

# Auto-categorize by name pattern
- name: "Auto-categorize new movies"
  enabled: true
  conditions:
    trigger: on_added
    all:
      - field: info.name
        operator: matches
        value: '(?i).*(1080p|2160p).*'
  actions:
    - type: set_category
      params:
        category: movies-hd

Troubleshooting:

• Not triggering? Check qBittorrent logs for errors
• Wrong path? Ensure qbt-rules is in PATH or use absolute path
• Permission denied? Ensure qBittorrent process can execute qbt-rules
• Test manually: qbt-rules --trigger on_added --hash <torrent_hash>

On Completed Trigger (Webhook)

Description: Triggered when a torrent finishes downloading. Executes for a single torrent identified by hash.

Command: qbt-rules --trigger on_completed --hash HASH

qBittorrent Configuration:

1. Open qBittorrent → Tools → Options → Downloads
2. Scroll to "Run external program on torrent completion"
3. Check the box to enable
4. Set command:

Bare Metal:

qbt-rules --trigger on_completed --hash "%I"

Docker:

docker exec qbt-rules-container qbt-rules --trigger on_completed --hash "%I"

Or if qbt-rules runs inside qBittorrent container:

qbt-rules --trigger on_completed --hash "%I"

Important: %I is qBittorrent's placeholder for torrent info hash (required)

Usage in Rules:

conditions:
  trigger: on_completed
  all:
    - field: info.size
      operator: ">"
      value: 1073741824  # > 1GB

Best Practices:

• Post-download processing - Trigger notifications, move files, update tags
• Seeding strategy - Apply upload limits, set ratio goals
• Category migration - Move from "downloading" to "completed" categories
• Tracking - Tag completed torrents for organization

When to Use:

• Notifications - Trigger external notification systems
• Seeding rules - Apply limits or force_start for ratio requirements
• Category changes - Move to "completed" or "seeding" categories
• Upload limiting - Throttle completed torrents to prioritize active downloads
• Tagging - Mark as completed for tracking

Example Rules for On Completed:

# Tag large completed downloads
- name: "Tag large completed downloads"
  enabled: true
  conditions:
    trigger: on_completed
    all:
      - field: info.size
        operator: ">"
        value: 10737418240  # > 10GB
  actions:
    - type: add_tag
      params:
        tags:
          - completed-large
          - needs-seeding

# Move to seeding category
- name: "Move completed to seeding"
  enabled: true
  conditions:
    trigger: on_completed
  actions:
    - type: set_category
      params:
        category: seeding

# Limit upload speed for private tracker torrents
- name: "Limit upload on completion for private"
  enabled: true
  conditions:
    trigger: on_completed
    all:
      - field: trackers.url
        operator: contains
        value: ".private"
  actions:
    - type: set_upload_limit
      params:
        limit: 1048576  # 1 MB/s

Troubleshooting:

• Not triggering? Check qBittorrent logs
• Fires multiple times? qBittorrent may trigger on re-check or resume
• Test manually: qbt-rules --trigger on_completed --hash <torrent_hash>

Custom Triggers

New in v0.3.0: Define your own custom trigger names for specialized workflows.

Usage:

# Use any trigger name you want
qbt-rules --trigger hourly
qbt-rules --trigger daily-cleanup
qbt-rules --trigger weekend
qbt-rules --trigger low-bandwidth

In Rules:

rules:
  - name: "Weekend high-bandwidth downloads"
    enabled: true
    conditions:
      trigger: weekend  # Only runs when: qbt-rules --trigger weekend
      all:
        - field: info.size
          operator: larger_than
          value: "50GB"
    actions:
      - type: force_start

  - name: "Hourly cleanup"
    enabled: true
    conditions:
      trigger: [hourly, manual]  # Runs on custom hourly OR manual
      all:
        - field: info.ratio
          operator: ">="
          value: 2.0
    actions:
      - type: delete_torrent
        params:
          keep_files: true

Common Use Cases:

• Time-based rules: hourly, daily, weekly
• Bandwidth-based: low-bandwidth, high-bandwidth
• Maintenance windows: maintenance, cleanup
• Testing: test, staging, production

Cron Examples:

# Run hourly cleanup every hour
0 * * * * qbt-rules --trigger hourly

# Run weekend rules on Saturday/Sunday
0 0 * * 6,0 qbt-rules --trigger weekend

# Run low-bandwidth rules during work hours
0 9-17 * * 1-5 qbt-rules --trigger low-bandwidth

Trigger-Agnostic Mode

New in v0.3.0: Run all rules regardless of trigger filters using --trigger none.

Usage:

# Run ALL rules, ignoring trigger filters
qbt-rules --trigger none

# Also works with dry-run
qbt-rules --trigger none --dry-run

When to Use:

• Emergency operations: Need to apply all rules immediately
• Migration: Moving from old trigger system to new
• Testing: Verify all rules work together
• Recovery: Re-apply all rules after configuration changes

Example:

Given these rules:

rules:
  - name: "Scheduled cleanup"
    conditions:
      trigger: scheduled  # Normally only runs on scheduled
      # ...

  - name: "On-added filter"
    conditions:
      trigger: on_added  # Normally only runs on_added
      # ...

  - name: "Universal rule"
    conditions:
      # No trigger filter - always runs
      # ...

Behavior:

# Normal: Only runs "Universal rule"
qbt-rules --trigger manual

# Trigger-agnostic: Runs ALL 3 rules
qbt-rules --trigger none

Trigger Filtering in Rules

You can filter rules to execute only on specific trigger types using the trigger field in conditions.

Single Trigger:

conditions:
  trigger: on_added
  # This rule ONLY runs when on_added.py is executed

Multiple Triggers:

conditions:
  trigger: [scheduled, manual]
  # This rule runs when scheduled.py OR manual.py is executed
  # Does NOT run for on_added or on_completed

All Triggers (Default):

conditions:
  # No trigger field = runs on ALL trigger types
  all:
    - field: info.ratio
      operator: ">"
      value: 2.0

Available Trigger Values:

• manual - Manual CLI execution (default)
• scheduled - Cron/scheduled execution
• on_added - Torrent added webhook
• on_completed - Torrent completed webhook
• <custom> - Any custom trigger name you define
• none - Trigger-agnostic mode (runs all rules)

Use Cases:

# Cleanup rules: Only run on schedule (not on every webhook)
- name: "Remove old torrents"
  conditions:
    trigger: [scheduled, manual]
    # ...

# Real-time filtering: Only on torrent added
- name: "Block unwanted content"
  conditions:
    trigger: on_added
    # ...

# Seeding rules: Only on completion
- name: "Set upload limits on completion"
  conditions:
    trigger: on_completed
    # ...

# Universal rules: No trigger filter (runs always)
- name: "Tag private tracker torrents"
  conditions:
    # Runs on ALL triggers
    all:
      - field: trackers.url
        operator: contains
        value: ".private"