Skip to content

Actions

Jump to bottom
Stephen Cox edited this page Dec 13, 2025 · 3 revisions

Actions execute when rule conditions match. Multiple actions can be specified per rule and execute sequentially.

Overview

Available Actions:

Action Description Idempotent Parameters
stop Stop/pause torrent Yes None
start Start/resume torrent Yes None
force_start Force start (bypass queue) No None
recheck Recheck torrent files No None
reannounce Force reannounce to trackers No None
delete_torrent Delete torrent from qBittorrent No keep_files
set_category Set torrent category Yes category
add_tag Add tags to torrent Yes tags
remove_tag Remove tags from torrent Yes tags
set_tags Replace all tags No tags
set_upload_limit Set upload speed limit No limit
set_download_limit Set download speed limit No limit

Idempotent Actions:

  • Yes: Skipped if already in desired state (logged as "skipped")
  • No: Always execute

stop

Description: Stop/pause torrent (qBittorrent v5.0+ terminology)

Parameters: None

Idempotent: Yes (skips if already paused/stopped)

Syntax:

actions:
  - type: stop

Use Cases:

  • Pause well-seeded torrents to free bandwidth
  • Stop torrents in error state
  • Pause torrents exceeding ratio requirements
  • Stop downloading after categorization for review

Example:

- name: "Pause well-seeded torrents"
  conditions:
    all:
      - field: info.ratio
        operator: ">="
        value: 3.0
      - field: info.num_leechs
        operator: ==
        value: 0
  actions:
    - type: stop

start

Description: Start/resume torrent (qBittorrent v5.0+ terminology)

Parameters: None

Idempotent: Yes (skips if already running)

Syntax:

actions:
  - type: start

Use Cases:

  • Resume paused torrents
  • Auto-start torrents meeting criteria
  • Re-enable stopped torrents after fixes

Example:

- name: "Resume torrents under ratio"
  conditions:
    all:
      - field: info.ratio
        operator: "<"
        value: 1.0
      - field: info.state
        operator: ==
        value: pausedUP
  actions:
    - type: start

force_start

Description: Force start torrent (bypasses queue limits)

Parameters: None

Idempotent: No (always executes)

Syntax:

actions:
  - type: force_start

Use Cases:

  • Prioritize private tracker torrents under ratio
  • Force-seed important torrents
  • Override queue limits for specific content

Example:

- name: "Force start private torrents under ratio"
  conditions:
    all:
      - field: info.ratio
        operator: "<"
        value: 1.0
      - field: trackers.url
        operator: contains
        value: ".private"
  actions:
    - type: force_start

Note: Use sparingly - bypasses qBittorrent's queue management

recheck

Description: Recheck torrent files for integrity

Parameters: None

Idempotent: No (always executes)

Syntax:

actions:
  - type: recheck

Use Cases:

  • Fix stalled downloads near completion
  • Verify files after external modification
  • Troubleshoot corrupted data

Example:

- name: "Recheck stalled downloads near completion"
  conditions:
    all:
      - field: info.state
        operator: ==
        value: stalledDL
      - field: info.progress
        operator: ">"
        value: 0.9
  actions:
    - type: recheck

reannounce

Description: Force reannounce to all trackers

Parameters: None

Idempotent: No (always executes)

Syntax:

actions:
  - type: reannounce

Use Cases:

  • Update tracker stats immediately
  • Fix tracker communication issues
  • Refresh peer list

Example:

- name: "Reannounce private torrents periodically"
  conditions:
    trigger: scheduled
    all:
      - field: trackers.url
        operator: contains
        value: ".private"
  actions:
    - type: reannounce

delete_torrent

Description: Delete torrent from qBittorrent

Parameters:

Parameter Type Required Default Description
keep_files boolean No false Keep downloaded files on disk

Idempotent: No (deletes permanently)

Syntax:

# Delete torrent and files
actions:
  - type: delete_torrent
    params:
      keep_files: false

# Delete torrent, keep files
actions:
  - type: delete_torrent
    params:
      keep_files: true

Use Cases:

  • Remove old completed torrents
  • Clean up errored torrents
  • Delete torrents with missing files
  • Space management

Examples:

# Delete old completed torrents (including files)
- name: "Delete old completed"
  conditions:
    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
# Remove errored torrents (keep files)
- name: "Remove errored torrents"
  conditions:
    any:
      - field: info.state
        operator: ==
        value: error
      - field: info.state
        operator: ==
        value: missingFiles
  actions:
    - type: delete_torrent
      params:
        keep_files: true

WARNING: Deletion is permanent! Always test with --dry-run first.

set_category

Description: Set torrent category

Parameters:

Parameter Type Required Description
category string Yes Category name (empty string "" to remove)

Idempotent: Yes (skips if already set)

Syntax:

# Set category
actions:
  - type: set_category
    params:
      category: movies-hd

# Remove category
actions:
  - type: set_category
    params:
      category: ""

Use Cases:

  • Auto-categorize by content type
  • Organize by tracker
  • Group by resolution or quality
  • Migrate between categories

Examples:

# Auto-categorize HD movies
- name: "Categorize HD movies"
  conditions:
    all:
      - field: info.name
        operator: matches
        value: '(?i).*(1080p|2160p).*'
      - field: info.category
        operator: ==
        value: ""
  actions:
    - type: set_category
      params:
        category: movies-hd
# Categorize by tracker
- name: "Categorize private tracker content"
  conditions:
    all:
      - field: trackers.url
        operator: contains
        value: ".private"
  actions:
    - type: set_category
      params:
        category: private

Important: Category must exist in qBittorrent (create manually first)

add_tag

Description: Add one or more tags to torrent

Parameters:

Parameter Type Required Description
tags list[string] Yes Tag names to add

Idempotent: Yes (skips if all tags already present)

Syntax:

actions:
  - type: add_tag
    params:
      tags:
        - hd
        - private
        - auto-tagged

Use Cases:

  • Tag by content attributes
  • Mark torrents by tracker
  • Flag for manual review
  • Track automation actions

Examples:

# Tag HD content
- name: "Tag HD content"
  conditions:
    all:
      - field: info.name
        operator: matches
        value: '(?i).*(1080p|2160p|4k).*'
  actions:
    - type: add_tag
      params:
        tags:
          - hd
# Tag completed large downloads (v0.3.0+ syntax)
- name: "Tag large completed downloads"
  conditions:
    trigger: on_completed
    all:
      - field: info.size
        operator: larger_than
        value: "10GB"
  actions:
    - type: add_tag
      params:
        tags:
          - completed-large
          - needs-seeding

remove_tag

Description: Remove one or more tags from torrent

Parameters:

Parameter Type Required Description
tags list[string] Yes Tag names to remove

Idempotent: Yes (skips if tags not present)

Syntax:

actions:
  - type: remove_tag
    params:
      tags:
        - temporary
        - review-needed

Use Cases:

  • Clean up temporary tags
  • Remove outdated markers
  • Clear automation flags

Example:

# Remove temporary tag after processing
- name: "Clean up temp tags"
  conditions:
    all:
      - field: info.tags
        operator: contains
        value: "temp"
      - field: info.completion_on
        operator: older_than
        value: 1 days
  actions:
    - type: remove_tag
      params:
        tags:
          - temp

set_tags

Description: Replace all tags with new set (removes existing first)

Parameters:

Parameter Type Required Description
tags list[string] Yes Complete tag list

Idempotent: No (always executes)

Syntax:

actions:
  - type: set_tags
    params:
      tags:
        - hd
        - verified

Use Cases:

  • Reset tagging completely
  • Enforce specific tag set
  • Clear all tags and apply new ones

Example:

# Reset tags for completed torrents
- name: "Reset tags on completion"
  conditions:
    trigger: on_completed
  actions:
    - type: set_tags
      params:
        tags:
          - completed
          - seeding

set_upload_limit

Description: Set per-torrent upload speed limit

Parameters:

Parameter Type Required Description
limit integer Yes Upload limit in bytes/s (-1 for unlimited)

Idempotent: No (always executes)

Syntax:

# Limit to 100 KB/s
actions:
  - type: set_upload_limit
    params:
      limit: 102400

# Remove limit (unlimited)
actions:
  - type: set_upload_limit
    params:
      limit: -1

Use Cases:

  • Throttle well-seeded torrents
  • Prioritize bandwidth for new uploads
  • Limit old torrents to free bandwidth
  • Manage bandwidth allocation

Examples:

# Throttle old torrents
- name: "Limit upload for old torrents"
  conditions:
    all:
      - field: info.ratio
        operator: ">="
        value: 5.0
      - field: info.seeding_time
        operator: ">"
        value: 2592000  # 30 days
  actions:
    - type: set_upload_limit
      params:
        limit: 102400  # 100 KB/s

Common Speed Conversions:

Speed Bytes/Second
50 KB/s 51200
100 KB/s 102400
500 KB/s 512000
1 MB/s 1048576
5 MB/s 5242880
10 MB/s 10485760

set_download_limit

Description: Set per-torrent download speed limit

Parameters:

Parameter Type Required Description
limit integer Yes Download limit in bytes/s (-1 for unlimited)

Idempotent: No (always executes)

Syntax:

# Limit to 1 MB/s
actions:
  - type: set_download_limit
    params:
      limit: 1048576

# Remove limit (unlimited)
actions:
  - type: set_download_limit
    params:
      limit: -1

Use Cases:

  • Throttle large downloads
  • Prevent bandwidth saturation
  • Prioritize specific torrents
  • Time-based speed management

Example:

# Limit large downloads (v0.3.0+ syntax)
- name: "Throttle large downloads"
  conditions:
    trigger: on_added
    all:
      - field: info.size
        operator: larger_than
        value: "20GB"
  actions:
    - type: set_download_limit
      params:
        limit: 2097152  # 2 MB/s

qbt-rules v0.3.0 | Python-based rules engine for qBittorrent automation

GitHub • PyPI • Issues • Discussions • Contributing • License

Requirements: Python 3.8+ • qBittorrent 5.0+

Made with ❤️ by the qbt-rules community | Licensed under MIT

🎯 qbt-rules

v0.3.0 | GitHub

📚 Getting Started

📖 Core Concepts

🔧 Configuration

🆘 Help & Support

🤝 Contributing

🆕 What's New (v0.3.0)

  • ✅ Unified CLI (qbt-rules)
  • ✅ Custom triggers
  • ✅ Trigger-agnostic mode
  • ✅ Size operators (50GB)

🔗 Quick Links

Clone this wiki locally