Examples

This section provides real-world rule examples organised by common use cases.

What's New in v0.3.0:

• 🆕 Human-readable sizes: Use larger_than and smaller_than with values like "50GB", "100MB", "1TB"
• 🆕 Custom triggers: Define your own trigger names (e.g., trigger: hourly, trigger: weekend)
• 🆕 Trigger-agnostic mode: Run all rules with qbt-rules --trigger none

Content Organisation

Auto-Categorise Movies

- name: "Auto-categorize HD movies"
  enabled: true
  stop_on_match: true
  conditions:
    trigger: on_added
    all:
      - field: info.name
        operator: matches
        value: '(?i).*(1080p|2160p|4k).*\.(mkv|mp4|avi)$'
  actions:
    - type: set_category
      params:
        category: "Movies-HD"
    - type: add_tag
      params:
        tag: "movies"

Auto-Categorize TV Shows

- name: "Auto-categorize TV shows"
  enabled: true
  stop_on_match: true
  conditions:
    trigger: on_added
    all:
      - field: info.name
        operator: matches
        value: '(?i).*[Ss]\d{2}[Ee]\d{2}.*'
  actions:
    - type: set_category
      params:
        category: "TV-Shows"
    - type: add_tag
      params:
        tag: "tv"

Organize by Tracker

- name: "Categorize private tracker content"
  enabled: true
  stop_on_match: true
  conditions:
    trigger: on_added
    any:
      - field: trackers.url
        operator: contains
        value: "privatehd.to"
      - field: trackers.url
        operator: contains
        value: "passthepopcorn.me"
  actions:
    - type: set_category
      params:
        category: "Private"
    - type: add_tag
      params:
        tag: "private-tracker"

9.2 Content Filtering

Block Archive Files

- name: "Remove torrents with only archives"
  enabled: true
  stop_on_match: true
  conditions:
    trigger: on_added
    all:
      - field: files.name
        operator: matches
        value: '(?i).*\.(rar|zip|7z|tar|gz)$'
  actions:
    - type: delete_torrent
      params:
        delete_files: true

Remove Sample Files

- name: "Delete torrents with sample files"
  enabled: true
  stop_on_match: true
  conditions:
    trigger: on_added
    any:
      - field: info.name
        operator: contains
        value: "sample"
      - field: files.name
        operator: contains
        value: "sample"
  actions:
    - type: delete_torrent
      params:
        delete_files: true

Filter by Size (v0.3.0+ Human-Readable Syntax)

- name: "Remove torrents too small (human-readable)"
  enabled: true
  conditions:
    trigger: on_added
    all:
      - field: info.size
        operator: smaller_than
        value: "100MB"  # Human-readable size
      - field: info.category
        operator: "=="
        value: "Movies"
  actions:
    - type: delete_torrent
      params:
        delete_files: true

- name: "Tag large downloads"
  enabled: true
  conditions:
    trigger: on_added
    all:
      - field: info.size
        operator: larger_than
        value: "50GB"  # Supports KB, MB, GB, TB
  actions:
    - type: add_tag
      params:
        tag: "large-download"

- name: "Pause huge torrents during work hours"
  enabled: true
  conditions:
    trigger: manual
    all:
      - field: info.size
        operator: larger_than
        value: "100GB"
      - field: info.state
        operator: "=="
        value: "downloading"
  actions:
    - type: stop

9.3 Tracker Management

Tag Private Trackers

- name: "Tag all private tracker torrents"
  enabled: true
  conditions:
    trigger: manual
    all:
      - field: trackers.url
        operator: not_contains
        value: "public"
  actions:
    - type: add_tag
      params:
        tag: "private"

Force Start on Specific Tracker

- name: "Force start low-seeded torrents on private trackers"
  enabled: true
  conditions:
    trigger: manual
    all:
      - field: trackers.url
        operator: contains
        value: "privatehd.to"
      - field: info.num_complete
        operator: "<"
        value: 3
  actions:
    - type: force_start

Reannounce Stalled Trackers

- name: "Reannounce torrents with tracker errors"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: trackers.msg
        operator: not_contains
        value: "Working"
      - field: info.state
        operator: "=="
        value: "stalledUP"
  actions:
    - type: reannounce

9.4 Cleanup & Maintenance

Remove Old Completed Torrents

- name: "Delete old completed torrents"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: info.state
        operator: in
        value: ["uploading", "pausedUP", "stalledUP"]
      - field: info.completion_on
        operator: older_than
        value: 2592000  # 30 days
      - field: info.ratio
        operator: ">="
        value: 1.0
  actions:
    - type: delete_torrent
      params:
        delete_files: false

Remove Stalled Downloads

- name: "Delete stalled downloads after 7 days"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: info.state
        operator: "=="
        value: "stalledDL"
      - field: info.added_on
        operator: older_than
        value: 604800  # 7 days
  actions:
    - type: delete_torrent
      params:
        delete_files: true

Clean Up Errored Torrents

- name: "Remove errored torrents"
  enabled: true
  conditions:
    trigger: scheduled
    any:
      - field: info.state
        operator: "=="
        value: "error"
      - field: info.state
        operator: "=="
        value: "missingFiles"
  actions:
    - type: delete_torrent
      params:
        delete_files: false

9.5 Seeding Management

Pause Well-Seeded Torrents

- name: "Pause torrents with high ratio and seeders"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: info.ratio
        operator: ">="
        value: 2.0
      - field: info.num_complete
        operator: ">"
        value: 10
      - field: info.state
        operator: "=="
        value: "uploading"
  actions:
    - type: stop

Start Underseded Torrents

- name: "Force start torrents with low seeders"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: info.num_complete
        operator: "<="
        value: 2
      - field: info.state
        operator: in
        value: ["pausedUP", "stalledUP"]
  actions:
    - type: force_start

Throttle Old Torrents

- name: "Limit upload speed for old torrents"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: info.completion_on
        operator: older_than
        value: 1209600  # 14 days
      - field: info.ratio
        operator: ">="
        value: 1.5
  actions:
    - type: set_upload_limit
      params:
        limit: 524288  # 512 KB/s

9.6 Error Handling & Recovery

Recheck Missing Files

- name: "Recheck torrents with missing files"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: info.state
        operator: "=="
        value: "missingFiles"
  actions:
    - type: recheck

Remove Errored Torrents After Retry

- name: "Delete permanently errored torrents"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: info.state
        operator: "=="
        value: "error"
      - field: info.added_on
        operator: older_than
        value: 259200  # 3 days
  actions:
    - type: delete_torrent
      params:
        delete_files: false

Auto-Resume Paused Downloads

- name: "Resume paused downloads with activity"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: info.state
        operator: "=="
        value: "pausedDL"
      - field: info.availability
        operator: ">"
        value: 0.5
  actions:
    - type: start

9.7 Advanced Multi-Criteria Rules

Complex Download Management

- name: "Manage large, slow downloads (v0.3.0 syntax)"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: info.size
        operator: larger_than
        value: "10GB"  # Human-readable size (v0.3.0+)
      - field: info.state
        operator: "=="
        value: "downloading"
      - field: info.dlspeed
        operator: "<"
        value: 102400  # < 100 KB/s (bytes)
      - field: info.added_on
        operator: newer_than
        value: 86400  # < 1 day old (seconds)
    none:
      - field: info.category
        operator: "=="
        value: "Priority"
  actions:
    - type: set_download_limit
      params:
        limit: 1048576  # 1 MB/s max (bytes/sec)
    - type: add_tag
      params:
        tag: "throttled"

Conditional Seeding Strategy

- name: "Smart seeding based on ratio and time"
  enabled: true
  conditions:
    trigger: on_completed
    any:
      # High ratio achieved
      - field: info.ratio
        operator: ">="
        value: 3.0
      # OR seeded for 30 days with ratio >= 1.0
      - all:
          - field: info.completion_on
            operator: older_than
            value: 2592000  # 30 days
          - field: info.ratio
            operator: ">="
            value: 1.0
  actions:
    - type: stop
    - type: add_tag
      params:
        tag: "seeding-complete"

Private Tracker Automation

- name: "Private tracker: force seed low-seeded content"
  enabled: true
  conditions:
    trigger: on_completed
    all:
      - field: trackers.url
        operator: contains
        value: "passthepopcorn.me"
      - field: info.num_complete
        operator: "<="
        value: 5
  actions:
    - type: force_start
    - type: set_category
      params:
        category: "Private-Important"
    - type: add_tag
      params:
        tag: "must-seed"
    - type: set_upload_limit
      params:
        limit: -1  # Unlimited

Nested Conditions (Advanced Logic)

New Feature: Nest all, any, and none groups for complex boolean logic.

# Complex cleanup rule with nested conditions
- name: "Smart cleanup: old or well-seeded torrents"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: info.state
        operator: in
        value: [uploading, stalledUP, pausedUP]
      - any:  # Nested: Either high ratio OR old with decent ratio
          - field: info.ratio
            operator: ">="
            value: 5.0
          - all:  # Nested level 2
              - field: info.completion_on
                operator: older_than
                value: "90 days"
              - field: info.ratio
                operator: ">="
                value: 1.5
  actions:
    - type: add_tag
      params:
        tags: ["cleanup-candidate"]
# Matches: seeding AND (ratio >= 5.0 OR (completed > 90 days AND ratio >= 1.5))

# Tiered priority based on multiple factors
- name: "Priority seeding: underseed OR private tracker"
  enabled: true
  conditions:
    trigger: on_completed
    any:  # Top-level OR
      - all:  # Nested: Private tracker with low seeders
          - field: trackers.url
            operator: contains
            value: ".private"
          - field: info.num_complete
            operator: "<="
            value: 3
      - all:  # Nested: Public but very low seeders
          - field: trackers.url
            operator: not_contains
            value: ".private"
          - field: info.num_complete
            operator: "=="
            value: 1
  actions:
    - type: force_start
    - type: set_upload_limit
      params:
        limit: -1  # Unlimited
    - type: add_tag
      params:
        tags: ["priority-seed"]
# Matches: (private AND <= 3 seeders) OR (public AND only 1 seeder)

# Exclude multiple categories with nested NONE
- name: "Apply limits except to important categories"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: info.ratio
        operator: ">="
        value: 2.0
      - none:  # Nested: NOT in any important category
          - field: info.category
            operator: in
            value: [keep, seedbox, private-important]
          - field: info.tags
            operator: contains
            value: "must-seed"
  actions:
    - type: set_upload_limit
      params:
        limit: 524288  # 512 KB/s
# Matches: ratio >= 2.0 AND NOT (important category OR must-seed tag)

Scheduled Maintenance Examples

Note: Scheduling is controlled by cron, not by rules. Use qbt-rules --trigger scheduled in your crontab.

# Daily cleanup at 3 AM
0 3 * * * qbt-rules --trigger scheduled

# Weekly recheck on Sundays at 4 AM
0 4 * * 0 qbt-rules --trigger scheduled

# Daily cleanup rule
- name: "Daily cleanup: remove completed torrents"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: info.state
        operator: in
        value: ["pausedUP", "stalledUP"]
      - field: info.ratio
        operator: ">="
        value: 2.0
      - field: info.completion_on
        operator: older_than
        value: 604800  # 7 days
  actions:
    - type: delete_torrent
      params:
        delete_files: false

# Weekly integrity check
- name: "Weekly integrity check"
  enabled: true
  conditions:
    trigger: scheduled
    all:
      - field: info.state
        operator: in
        value: ["uploading", "stalledUP"]
  actions:
    - type: recheck

9.9 Webhook Integration Example

# Auto-categorize on add
- name: "Webhook: Categorize new downloads"
  enabled: true
  conditions:
    trigger: on_added
    any:
      - field: info.name
        operator: matches
        value: '(?i).*\.(mkv|mp4|avi)$'
      - field: files.name
        operator: matches
        value: '(?i).*\.(mkv|mp4|avi)$'
  actions:
    - type: set_category
      params:
        category: "Videos"
    - type: add_tag
      params:
        tag: "auto-categorized"

# Post-completion actions
- name: "Webhook: Tag completed downloads"
  enabled: true
  conditions:
    trigger: on_completed
    all:
      - field: info.ratio
        operator: "<"
        value: 1.0
  actions:
    - type: add_tag
      params:
        tag: "needs-seeding"
    - type: force_start