🧯 qbit-ops

A tiny qBittorrent CLI and TUI for people who don't want to nuke their seedbox by accident.

Inspect torrents and trackers, diagnose problems, and preview bulk changes before they reach qBittorrent.

🚀 Get started

Requires Python 3.12+ and a qBittorrent instance with the Web UI enabled.

pipx install "git+https://github.com/LECOQQ/qbit-ops.git@v0.3.0"  # x-release-please-version

With the optional TUI:

pipx install "git+https://github.com/LECOQQ/qbit-ops.git@v0.3.0#egg=qbit-ops[tui]"  # x-release-please-version

Create ~/.config/qbit-ops/.env:

QBIT_HOST=http://localhost:8080
QBIT_USER=admin
QBIT_PASSWORD=change-me

Then:

qbit-ops status
qbit-ops doctor
qbit-ops tui

🔍 Inspect your instance

qbit-ops torrents list --category sonarr --state stalled
qbit-ops trackers status
qbit-ops explain torrent --hash abc123
qbit-ops status --watch

Read commands support machine-friendly output where it makes sense:

qbit-ops torrents list --format json
qbit-ops status --format jsonl

🛠️ Make changes safely

Mutations are dry-run by default:

qbit-ops torrents pause --category sonarr

Review the plan, then apply it explicitly:

qbit-ops torrents pause --category sonarr --no-dry-run

🛡️ Safety by default

• 🧪 Dry-run first. Nothing changes unless --no-dry-run is explicit.
• 🎯 Hash-based targeting. Mutations never guess from a fuzzy torrent name.
• 🧊 Frozen plans. The previewed selection is the selection that gets applied.
• 🚫 No silent “all”. Bulk actions require a hash, --all, or an explicit filter.
• 🔒 Secret-safe output. Tracker passkeys and announce URLs stay redacted in normal output.
• ✅ Honest results. qbit-ops reports what was submitted or observed, not what it cannot prove.

🖥️ TUI

The optional Textual interface provides a branded overview, torrent browsing, filters, details, explanations, and previewed low-risk bulk actions.

qbit-ops tui

Overview	Torrents

Search	Preview before Apply

Press ? inside the TUI to see the available controls.

🧩 Compatibility

Container integration is tested against these exact qBittorrent releases:

qBittorrent	Web API
4.6.7	2.9.3
5.0.0	2.11.2
5.1.4	2.11.4
5.2.3	2.15.1

This is evidence for those exact versions, not a claim for the whole 4.6–5.2 range. Run qbit-ops doctor to compare your instance with the packaged evidence.

🧰 Commands

qbit-ops --help
qbit-ops torrents --help
qbit-ops trackers --help

A compact command overview is available in docs/COMMANDS.md.

🧑‍💻 Development

git clone https://github.com/LECOQQ/qbit-ops.git
cd qbit-ops
make install
make check-fast
make check

See CONTRIBUTING.md.

📄 License

MIT - see LICENSE.