In‐Depth Configuration

config.yml Reference

The config.yml file contains connection settings, logging configuration, and engine options.

Section	Parameter	Type	Default	Description
qbittorrent	host	string	http://localhost:8080	qBittorrent Web UI URL
	user	string	admin	Username for authentication
	pass	string	(required)	Password (supports env vars)
logging	level	string	INFO	Log level: DEBUG, INFO, WARNING, ERROR
	file	string	logs/qbittorrent.log	Log file path (relative to CONFIG_DIR)
	trace_mode	boolean	false	Include module/function/line in logs
engine	dry_run	boolean	false	Test mode without executing actions

Example config.yml:

# qBittorrent connection settings
qbittorrent:
  host: ${QBITTORRENT_HOST:-http://localhost:8080}
  user: ${QBITTORRENT_USER:-admin}
  pass: ${QBITTORRENT_PASS}

# Logging configuration
logging:
  level: ${LOG_LEVEL:-INFO}
  file: ${LOG_FILE:-logs/qbittorrent.log}
  trace_mode: ${TRACE_MODE:-false}

# Engine settings
engine:
  dry_run: ${DRY_RUN:-false}

Environment Variable Expansion

Config files support environment variable expansion using the syntax:

parameter: ${VARIABLE_NAME:-default_value}

Behavior:

• If VARIABLE_NAME is set → uses its value
• If VARIABLE_NAME is not set → uses default_value
• If VARIABLE_NAME is not set and no default → empty string

Precedence:

1. Environment variable (highest priority)
2. Config file default value
3. Empty string

Examples:

# Use environment variable, fallback to localhost
host: ${QBITTORRENT_HOST:-http://localhost:8080}

# Required environment variable (no default)
pass: ${QBITTORRENT_PASS}

# Boolean from environment
dry_run: ${DRY_RUN:-false}

rules.yml Reference

The rules.yml file defines automation rules. Rules execute in file order (top to bottom).

Rule Structure:

rules:
  - name: "Descriptive rule name"
    enabled: true
    stop_on_match: false
    conditions:
      trigger: manual  # Optional: filter by trigger type
      all: []   # All conditions must match (AND)
      any: []   # Any condition must match (OR)
      none: []  # No conditions can match (NOT)
    actions:
      - type: action_name
        params: {}

Field Reference:

Field	Type	Required	Default	Description
name	string	Yes	-	Human-readable rule name for logs
enabled	boolean	Yes	-	Set to false to disable rule
stop_on_match	boolean	Yes	false	If true, matched torrents skip remaining rules
conditions	object	Yes	-	Conditions object (see below)
actions	list	Yes	-	List of actions to execute

Conditions Object:

Field	Type	Required	Description
trigger	string or list	No	Filter rule by trigger type(s)
all	list	No	All conditions must be true (AND)
any	list	No	At least one condition must be true (OR)
none	list	No	No conditions can be true (NOT)

Condition Item:

- field: info.name
  operator: contains
  value: "1080p"

Field	Type	Required	Description
field	string	Yes	Dot notation field path (e.g., info.name, trackers.url)
operator	string	Yes	Comparison operator (see Operators section)
value	any	Yes	Value to compare against

Action Item:

- type: set_category
  params:
    category: movies

Field	Type	Required	Description
type	string	Yes	Action name (see Actions section)
params	object	No	Action-specific parameters

Key Concepts

File Order Execution

Rules execute top to bottom in the order they appear in rules.yml. This provides predictable, easy-to-understand behavior.

Best Practice:

• Top: Blocking/filtering rules with stop_on_match: true
• Middle: Categorization and tagging rules
• Bottom: Cleanup and maintenance rules

Example:

rules:
  # 1. Block unwanted content first (stops further processing)
  - name: "Block archives"
    stop_on_match: true
    # ...

  # 2. Then categorize
  - name: "Categorize movies"
    # ...

  # 3. Finally cleanup
  - name: "Remove old completed"
    # ...

stop_on_match Behavior

When stop_on_match: true and a torrent matches the rule:

• The rule's actions execute on that torrent
• That torrent skips all remaining rules in the current execution
• Other torrents continue processing normally

Use Cases:

• Content filtering (block unwanted, skip other rules)
• Mutually exclusive categorization
• Early exit for special cases

Example:

rules:
  - name: "Block unwanted"
    stop_on_match: true  # Matched torrents stop here
    conditions:
      any:
        - field: info.name
          operator: contains
          value: "unwanted"
    actions:
      - type: stop

  - name: "Categorize all"  # Blocked torrents never reach this rule
    # ...

Empty Condition Groups

Empty condition groups are ignored (treated as always true):

conditions:
  all:  # Empty - ignored
  any:
    - field: info.ratio
      operator: ">"
      value: 2.0
  # Effectively: any conditions must match

If all groups are empty, the rule matches all torrents:

conditions: {}  # Matches everything