qbt-hub

name	qbt-hub
description	Manage qBittorrent downloads via WebUI API (v5.0+). Use this skill whenever the user asks to add a torrent or magnet link, check download progress, search/filter tasks, delete tasks, set speed limits, manage tags/categories, or do anything related to qBittorrent. Trigger keywords: qBittorrent, qbt, torrent, magnet, download task, seeding, add torrent, qbt-hub.

qbt-hub

Manage qBittorrent (v5.0+) via its WebUI API using the bundled scripts/qbt.py.

Authentication

Credentials are read from env vars (set once, reused forever):

• QBT_HOST — e.g. http://qbt.example.com
• QBT_USER — WebUI username
• QBT_PASS — WebUI password

Can also be overridden per-call: --host / --user / --pass

Script Location

~/.agents/skills/qbt-hub/scripts/qbt.py

Alias for convenience:

alias qbt="python3 ~/.agents/skills/qbt-hub/scripts/qbt.py"

Commands

Add a task

# magnet link
python3 qbt.py add "magnet:?xt=urn:btih:..."

# https .torrent URL
python3 qbt.py add "https://example.com/file.torrent"

# local .torrent file
python3 qbt.py add ~/Downloads/movie.torrent

# with options
python3 qbt.py add "magnet:..." --savepath /data/movies --category Movies --tags "4K,DV" --paused --sequential

List / filter tasks

python3 qbt.py list                              # all tasks
python3 qbt.py list --filter downloading         # active downloads
python3 qbt.py list --filter completed
python3 qbt.py list --tag 4K --sort size         # filter by tag, sort by size
python3 qbt.py list --category Movies --asc

Filter choices: all downloading seeding completed paused active inactive stalled errored Sort choices: name size progress dlspeed upspeed ratio added_on

Search

python3 qbt.py search ubuntu          # fuzzy match on task name

Global status

python3 qbt.py status                 # DL/UL speed, totals, limits, turtle mode

Task details

python3 qbt.py info ubuntu            # progress, files, trackers, peers

Pause / Resume / Recheck

python3 qbt.py pause ubuntu
python3 qbt.py resume all
python3 qbt.py recheck ubuntu

Delete

python3 qbt.py delete ubuntu          # keep local files
python3 qbt.py delete ubuntu --files  # also delete local data

Speed limits

# per-task
python3 qbt.py limit ubuntu --dl 500 --ul 100   # KB/s
python3 qbt.py limit ubuntu --dl 0              # remove limit

# global
python3 qbt.py speedlimit                        # show current
python3 qbt.py speedlimit --dl 2048 --ul 512
python3 qbt.py speedlimit --dl 0                 # unlimited
python3 qbt.py speedlimit --alt                  # toggle turtle mode

Tags

python3 qbt.py tag ubuntu --tags "linux,iso"
python3 qbt.py untag ubuntu --tags "iso"
python3 qbt.py tags                              # list all tags with counts

Categories

python3 qbt.py category ubuntu --cat Linux
python3 qbt.py categories                        # list all categories

Rename / Move

python3 qbt.py rename ubuntu --name "Ubuntu 24.04 LTS"
python3 qbt.py move ubuntu --path /data/iso

Top N

python3 qbt.py top --n 10 --sort size    # largest tasks
python3 qbt.py top --n 5 --sort dl       # fastest downloads
python3 qbt.py top --n 5 --sort ratio    # highest ratio seeders

Sort choices: size dl ul ratio progress added

RSS

python3 qbt.py rss list
python3 qbt.py rss add --url "https://example.com/feed.rss"
python3 qbt.py rss remove --path "FeedName"
python3 qbt.py rss addrule --name "4K Shows" --pattern "2160p" --category TV
python3 qbt.py rss removerule --name "4K Shows"

Workflow: Search the web and add a torrent

1. Search for the torrent on sites like torrentkitty.net or thepiratebay.org using browser_use
2. Extract the magnet link from the page
3. Run python3 qbt.py add "<magnet>" --savepath /path --tags "tag1,tag2"

Common patterns

# Check what's currently downloading
python3 qbt.py list --filter downloading

# Find and delete a large task including its files
python3 qbt.py top --n 10 --sort size
python3 qbt.py delete "keyword" --files

# Tag all completed tasks
python3 qbt.py list --filter completed   # find keyword
python3 qbt.py tag "keyword" --tags "done"

# Slow down a task to save bandwidth
python3 qbt.py limit "keyword" --dl 200 --ul 50

Notes

• keyword matching is case-insensitive fuzzy match on task name
• Use all as keyword to target every task (e.g. resume all, pause all)
• delete always prompts for confirmation before executing
• rename requires an exact single match; use a more specific keyword if multiple tasks match
• qBittorrent instance: http://qbt.wsen.me (internal network, v5.0.2)