qbittorrent-remote-client 0.2.0

A Python-based command-line tool for remotely managing qBittorrent instances via the Web API

qBittorrent Remote Client

A Python-based command-line tool for remotely managing qBittorrent instances via the Web API.

Project Status

🚀 Active Development - This project is actively maintained with comprehensive CI/CD pipeline

• ✅ Tests: 43/43 passing (100% pass rate) with 75% code coverage
• ✅ CI/CD: Multi-Python testing (3.9-3.12) with automated quality checks
• ✅ Security: Automated vulnerability scanning with Bandit
• ✅ Code Quality: Black formatting, isort imports, mypy type checking
• ✅ Branch Protection: Main branch protected with required status checks
• ✅ Documentation: Comprehensive README with usage examples

Features

• 🖥️ Comprehensive Status Dashboard - Real-time monitoring with rich formatted display
• 📋 List and Filter Torrents - View torrents with detailed information and filtering
• ➕ Add Torrents - From magnet links, URLs, or torrent files with category support
• 🏷️ Category Management - List categories and organize torrents automatically
• ⏸️ Control Torrents - Pause, resume, and delete operations
• 🗑️ Bulk Operations - Delete torrents by status (error, missingFiles, etc.)
• 📊 Transfer Statistics - Global transfer info and session statistics
• 🔄 Auto-refresh Mode - Real-time monitoring with configurable refresh intervals
• 🎯 Interactive Mode - Interactive shell for quick operations
• ⚡ Automation Ready - CLI flags for scripting and automation

Status Dashboard

Get a comprehensive overview of your qBittorrent instance:

# One-time status check
qbt-client status

# Auto-refresh every 5 seconds for monitoring
qbt-client status --refresh 5

The dashboard shows:

• 🖥️ Server information (version, connection, protocol)
• 📊 Transfer statistics (speeds, session/all-time totals)
• 📚 Torrent overview (counts, sizes, active transfers)
• 📈 Status breakdown with color-coded percentages
• 🚀 Most active torrents with progress and speeds

Installation

From PyPI (Recommended)

pip install qbittorrent-remote-client

After installation, you can use the qbt-client command directly from anywhere:

qbt-client --help

From Source

From Source

1. Clone and install from source:

   git clone https://github.com/ryanlong1004/qbittorrent-remote-client.git
   cd qbittorrent-remote-client
   pip install .
   

2. For development:

   git clone https://github.com/ryanlong1004/qbittorrent-remote-client.git
   cd qbittorrent-remote-client
   pip install -e .
   

Setup

After installation, you need to configure the connection to your qBittorrent instance:

1. Enable Web UI in qBittorrent:

   • Go to Tools → Preferences → Web UI
   • Check "Web User Interface"
   • Set username/password
   • Note the port (default: 8080)

2. Create configuration file:

   # Download example config
   curl -O https://raw.githubusercontent.com/ryanlong1004/qbittorrent-remote-client/main/config.example.json
   cp config.example.json config.json
   # Edit config.json with your qBittorrent details
   

   Or create config.json manually with your qBittorrent details:

   {
     "host": "localhost",
     "port": 8080,
     "username": "admin",
     "password": "your_password",
     "use_https": false
   }
   

Development Setup

# Clone and setup development environment
git clone https://github.com/ryanlong1004/qbittorrent-remote-client.git
cd qbittorrent-remote-client

# Set up development environment
make dev-setup

# Run tests
make test

# Run tests with coverage
make test-cov

# Run all CI checks locally
make ci

Developer Workflow

To avoid CI/CD formatting failures, always run these commands before committing:

# Format code automatically
make format

# Check formatting (what CI/CD runs)
make format-check

# Run all quality checks locally (same as CI/CD)
make ci

# Or run pre-commit hooks manually
make pre-commit

Pro Tip: Pre-commit hooks are installed automatically and will format code before each commit!

Testing

This project includes a comprehensive test suite with:

• Unit Tests - Complete coverage of API and CLI functionality
• Integration Tests - End-to-end testing scenarios
• Code Quality - Automated linting, formatting, and security checks
• CI/CD Pipeline - GitHub Actions workflow for continuous testing

# Run all tests
pytest

# Run with coverage report
pytest --cov

# Run specific test file
pytest tests/test_qbt_api.py

# Run tests matching pattern
pytest -k "test_status"

Usage

# List all torrents
qbt-client list

# List available categories
qbt-client categories

# Add torrent from magnet link
qbt-client add "magnet:?xt=urn:btih:..."

# Add torrent to specific category
qbt-client add "magnet:?xt=urn:btih:..." --category Films

# Add torrent from file with category and custom path
qbt-client add /path/to/file.torrent --category Music --path /custom/path

# Pause torrents
qbt-client pause <hash1> <hash2>

# Resume torrents
qbt-client resume <hash1> <hash2>

# Delete torrents
qbt-client delete <hash1> --delete-files

# Delete all torrents with specific status (with preview)
qbt-client delete-by-status error --dry-run

# Delete all torrents with specific status
qbt-client delete-by-status missingFiles --delete-files

# Get statistics
qbt-client stats

# Show comprehensive status dashboard
qbt-client status

# Auto-refresh status every 5 seconds
qbt-client status --refresh 5

# Interactive mode
qbt-client interactive

Alternative: Using Python Module

If you prefer to run as a Python module:

# List all torrents
python -m qbittorrent_remote_client.qbt_client list

# Or if using development environment with source
qbt-client list