torrentcli-pro 2.0.10

Hardcore terminal torrent client with cyberpunk aesthetics, optimized for rare torrents

TorrentCLI Pro

Enterprise-grade BitTorrent client for terminal environments with intelligent optimization and aria2c integration.

---

Table of Contents

• Overview
• Features
• Architecture
• Installation
• Quick Start
• Interactive REPL
• Configuration
• Download Profiles
• CLI Reference
• API & Integration
• Security Considerations
• Troubleshooting
• Development
• Contributing
• License

---

Overview

TorrentCLI Pro is a production-ready command-line BitTorrent client that wraps aria2c with intelligent download optimization, health analysis, and a rich terminal interface. Designed for server environments, automation pipelines, and power users who prefer terminal workflows.

Why TorrentCLI Pro?

Challenge	Solution
Low-seeder torrents fail silently	Health analysis with automatic profile escalation
Manual tracker management	Auto-fetches 100+ working trackers from trusted sources
No visibility into download issues	Real-time diagnostics showing peer/tracker status
Complex aria2c configuration	Profile system with sensible defaults
GUI clients unsuitable for servers	Full CLI/REPL with scriptable JSON output

---

Features

Core Capabilities

• Intelligent Health Analysis - Queries DHT and trackers before download to assess torrent viability
• Automatic Profile Selection - Chooses optimal configuration based on seeder count and network conditions
• Dynamic Tracker Injection - Fetches and injects 50-100 working trackers from curated sources
• Interactive REPL - Full-featured shell with readline support, auto-completion, and command history
• Auto-Start Daemon - REPL automatically manages aria2c lifecycle (start/stop)

Download Management

• Multiple Source Types - Magnet URIs, .torrent files, .metalink files, HTTP URLs, bare info hashes
• Selective File Download - Interactive picker for multi-file torrents
• Resume Support - Session persistence with automatic resume on restart
• Batch Processing - Queue multiple downloads with configurable concurrency

Monitoring & Observability

• Real-time Progress - Speed graphs, ETA, peer statistics
• Tracker Diagnostics - Response times, success rates, peer counts per tracker
• JSON Output Mode - Machine-readable output for integration with monitoring systems
• SQLite History - Queryable download history with performance metrics

Performance

Metric	Value
Memory footprint	< 50 MiB (Python + aria2c)
CPU usage (idle)	< 5%
Cold start time	< 500ms
Supported concurrent downloads	Configurable (default: 5)

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        TorrentCLI Pro                           │
├─────────────────────────────────────────────────────────────────┤
│  CLI Layer (Click)                                              │
│  ├── download, list, pause, resume, cancel                      │
│  ├── config, history, stats                                     │
│  └── repl (interactive shell)                                   │
├─────────────────────────────────────────────────────────────────┤
│  Core Services                                                  │
│  ├── DownloadEngine      - Orchestrates download lifecycle      │
│  ├── HealthAnalyzer      - Assesses torrent viability           │
│  ├── TrackerManager      - Fetches/injects external trackers    │
│  └── ProfileManager      - Manages download configurations      │
├─────────────────────────────────────────────────────────────────┤
│  REPL Backend                                                   │
│  ├── CommandParser       - Parses user input                    │
│  ├── REPLBackend         - aria2c JSON-RPC interface            │
│  └── Auto-start/stop     - Manages aria2c daemon lifecycle      │
├─────────────────────────────────────────────────────────────────┤
│  Data Layer                                                     │
│  ├── SQLite              - Download history, tracker stats      │
│  └── TOML Config         - User preferences, profiles           │
├─────────────────────────────────────────────────────────────────┤
│  External                                                       │
│  └── aria2c              - BitTorrent protocol implementation   │
└─────────────────────────────────────────────────────────────────┘

---

Installation

Prerequisites

Requirement	Version	Installation
Python	3.9+	python.org
aria2c	1.36.0+	See below

Install aria2c

# macOS
brew install aria2

# Ubuntu/Debian
sudo apt install aria2

# RHEL/CentOS/Fedora
sudo dnf install aria2

# Arch Linux
sudo pacman -S aria2

# Windows (Chocolatey)
choco install aria2

Install TorrentCLI Pro

# From PyPI (recommended)
pip install torrentcli-pro

# From source
git clone https://github.com/torrentcli/torrentcli-pro.git
cd torrentcli-pro
pip install -e .

# With Poetry (development)
poetry install

Verify Installation

torrentcli --version
# TorrentCLI Pro, version 1.0.0

aria2c --version
# aria2 version 1.37.0

---

Quick Start

1. Start Interactive REPL (Recommended)

The easiest way to use TorrentCLI Pro - one command handles everything:

torrentcli repl

This automatically:

• Starts aria2c daemon if not running
• Connects to existing aria2c if available
• Provides an interactive shell for managing downloads
• Stops aria2c on exit (if it started it)

2. Add a Download

In the REPL, add a torrent using any supported source:

# Magnet URI
torrentcli> add magnet:?xt=urn:btih:dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c&dn=Big+Buck+Bunny

# Info hash (auto-converts to magnet)
torrentcli> add dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c

# .torrent file
torrentcli> add /path/to/file.torrent

# HTTP URL
torrentcli> add https://example.com/file.torrent

3. Monitor Progress

torrentcli> list
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓
┃ GID            ┃ Name             ┃ Progress ┃ Speed    ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩
│ a1b2c3d4e5f6   │ Big Buck Bunny   │ 42.3%    │ 5.2 MB/s │
└────────────────┴──────────────────┴──────────┴──────────┘

torrentcli> details a1b2c3d4e5f6

Example Test Magnet

Use this legal, freely-distributable torrent for testing (Big Buck Bunny - open source animated short):

magnet:?xt=urn:btih:dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c&dn=Big+Buck+Bunny&tr=udp%3A%2F%2Ftracker.opentrackr.org%3A1337%2Fannounce

---

Interactive REPL

The REPL provides a full-featured interactive environment for managing downloads.

Starting the REPL

# Basic usage (auto-starts aria2c)
torrentcli repl

# With RPC authentication
torrentcli repl --rpc-secret=YOUR_SECRET

# Using environment variable
export ARIA2_RPC_SECRET=YOUR_SECRET
torrentcli repl

Command Reference

Command	Aliases	Description	Example
add <source>	a, dl	Add download (magnet/URL/hash/file)	add magnet:?xt=...
pause <GID>	p	Pause a download	pause a1b2c3
resume <GID>	r	Resume paused download	resume a1b2c3
remove <GID>	rm, del	Remove a download	remove a1b2c3
list	ls, l	List all downloads	list
details <GID>	d, info	Show download details	details a1b2c3
filter <criteria>	f	Filter by status or name	filter active
set <GID> <k>=<v>	option	Set per-download option	set a1b2c3 max-download-limit=1M
set global <k>=<v>		Set global option	set global max-overall-download-limit=5M
retry		Reconnect to aria2c	retry
help	?, h	Show help	help
quit	q, exit	Exit REPL	quit

Supported Source Types

Type	Format	Example
Magnet URI	magnet:?xt=urn:btih:...	add magnet:?xt=urn:btih:abc123...
Info Hash (hex)	40 hexadecimal characters	add abc123def456789012345678901234567890abcd
Info Hash (base32)	32 base32 characters	add ABCDEFGHIJKLMNOPQRSTUVWXYZ234567
Torrent File	.torrent path	add /downloads/file.torrent
Metalink File	.metalink or .meta4 path	add /downloads/file.metalink
HTTP/HTTPS URL	URL to torrent/file	add https://example.com/file.iso

Filtering Downloads

# Filter by status
torrentcli> filter active
torrentcli> filter waiting
torrentcli> filter stopped

# Filter by name (case-insensitive substring match)
torrentcli> filter ubuntu

# Clear filter
torrentcli> filter

---

Configuration

Configuration File Location

~/.config/torrentcli/config.toml

Initialize Configuration

torrentcli config init

Configuration Reference

# General Settings
[general]
default_profile = "auto"           # auto|default|rare|fast|seeder|privacy|batch
download_dir = "~/Downloads"       # Default download directory
tracker_update_interval = 43200    # Tracker list refresh interval (seconds)

# User Interface
[ui]
theme = "cyberpunk"                # cyberpunk|matrix|solar|nord|gruvbox|midnight

# Notifications
[notifications]
level = "important"                # all|important|none

# aria2c Global Options
[aria2c]
max_overall_download_limit = "0"   # Global download speed limit (0 = unlimited)
max_overall_upload_limit = "0"     # Global upload speed limit
max_concurrent_downloads = 5       # Maximum parallel downloads

# Custom Profile Example
[profiles.my_custom]
inherit = "rare"                   # Inherit from built-in profile
aria2c_options.bt_max_peers = 300  # Override specific options
aria2c_options.seed_time = 120     # Seed for 2 hours

Environment Variables

Variable	Description	Example
TORRENTCLI_PROFILE	Default profile	rare
TORRENTCLI_DOWNLOAD_DIR	Download directory	/data/torrents
TORRENTCLI_THEME	UI theme	matrix
TORRENTCLI_QUIET	Suppress output	1
ARIA2_RPC_SECRET	aria2c RPC secret	mysecret

---

Download Profiles

Profiles are pre-configured optimization strategies for different scenarios.

Profile	Description	Max Peers	Trackers	Use Case
auto	Analyzes health, selects optimal	Dynamic	Dynamic	Recommended default
default	Balanced settings	55	Best 20	Popular torrents (10+ seeders)
rare	Aggressive peer discovery	200	All 100+	Low-seeder torrents (0-10 seeders)
fast	High-bandwidth optimization	100	Best 20	High-speed connections (100+ Mbps)
seeder	Long-term seeding	100	Best 20	Contribute back (24h or 2.0 ratio)
privacy	Minimal exposure	50	Best 20, no DHT	VPN/privacy-focused usage
batch	Concurrent downloads	30	Best 20	Multiple simultaneous downloads

Profile Selection

# CLI
torrentcli download "magnet:..." --profile rare

# REPL (uses default profile from config)
torrentcli> add magnet:?xt=...

# Environment
export TORRENTCLI_PROFILE=rare
torrentcli download "magnet:..."

---

CLI Reference

Download Commands

# Download with automatic profile selection
torrentcli download "magnet:?xt=..."

# Specify profile
torrentcli download "magnet:?xt=..." --profile rare

# Custom download directory
torrentcli download "magnet:?xt=..." --dir /data/torrents

# Speed limiting
torrentcli download "magnet:?xt=..." --max-speed 5M

# Seeding options
torrentcli download "magnet:?xt=..." --seed-time 60      # Seed for 60 minutes
torrentcli download "magnet:?xt=..." --seed-ratio 2.0    # Seed until 2.0 ratio
torrentcli download "magnet:?xt=..." --no-seed           # Exit after download

# Interactive file selection (multi-file torrents)
torrentcli download "magnet:?xt=..." --select

# Completion hook
torrentcli download "magnet:?xt=..." --on-complete "notify-send 'Done'"

# Output modes
torrentcli download "magnet:?xt=..." --quiet             # Errors only
torrentcli download "magnet:?xt=..." --json              # JSON output

Management Commands

# List downloads
torrentcli list
torrentcli list --status active

# Download history
torrentcli history --limit 20

# Aggregate statistics
torrentcli stats

# Tracker performance
torrentcli tracker-stats --limit 20

Configuration Commands

# Show current configuration
torrentcli config show

# Initialize configuration
torrentcli config init

# Edit in $EDITOR
torrentcli config edit

# List available profiles
torrentcli list-profiles

# Update tracker lists
torrentcli update-trackers

Command Aliases

Full Command	Alias
torrentcli download	torrentcli dl
torrentcli list	torrentcli ls

---

API & Integration

JSON Output Mode

For integration with scripts and monitoring systems:

torrentcli download "magnet:..." --json > download_stats.json

Exit Codes

Code	Meaning
0	Success
1	General error
130	Interrupted (Ctrl+C)

Scripting Examples

# Batch download from file
while read -r magnet; do
  torrentcli dl "$magnet" --quiet
done < magnets.txt

# Download with notification
torrentcli dl "magnet:..." --on-complete "curl -X POST https://webhook.example.com/done"

# Health check before download
torrentcli info "magnet:..." --json | jq '.seeders'

---

Security Considerations

Network Security

• RPC Authentication: Use --rpc-secret for aria2c RPC authentication
• Local Binding: aria2c RPC binds to localhost by default
• No External Exposure: REPL does not expose network services

File System

• Download Directory: Validate and sanitize download paths
• Session Files: Stored in ~/.local/share/torrentcli/sessions/
• Configuration: Stored in ~/.config/torrentcli/

Best Practices

# Always use RPC secret in shared environments
export ARIA2_RPC_SECRET=$(openssl rand -hex 16)
torrentcli repl --rpc-secret=$ARIA2_RPC_SECRET

# Restrict download directory permissions
chmod 700 ~/Downloads/torrents

---

Troubleshooting

Common Issues

aria2c not found

# Check if installed
which aria2c

# Install (see Installation section)
brew install aria2        # macOS
sudo apt install aria2    # Ubuntu/Debian

No seeders found

# Use rare profile for aggressive peer discovery
torrentcli dl "magnet:..." --profile rare

# Manually refresh tracker lists
torrentcli update-trackers

# Check if content still exists (very old torrents may be dead)

Slow download despite seeders

# Check for ISP throttling (try VPN)
# Use fast profile for high-bandwidth connections
torrentcli dl "magnet:..." --profile fast

# Verify aria2c version (1.36.0+ recommended)
aria2c --version

REPL connection failed

# Check if another aria2c is running
pgrep aria2c

# Kill existing instance if needed
pkill aria2c

# Restart REPL
torrentcli repl

Debug Mode

# Enable verbose logging
export TORRENTCLI_DEBUG=1
torrentcli download "magnet:..."

---

Development

Setup Development Environment

# Clone repository
git clone https://github.com/torrentcli/torrentcli-pro.git
cd torrentcli-pro

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
poetry install

# Activate virtual environment
poetry shell

Running Tests

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=torrentcli --cov-report=html

# Run specific test file
poetry run pytest tests/test_repl.py -v

# Run specific test
poetry run pytest tests/test_repl.py::TestCommandParser -v

Code Quality

# Linting
poetry run ruff check .

# Type checking
poetry run mypy src/

# Formatting
poetry run black src/ tests/

Project Structure

torrentcli-pro/
├── src/torrentcli/
│   ├── __init__.py          # Package metadata
│   ├── cli.py                # Click CLI commands
│   ├── repl.py               # Interactive REPL
│   ├── engine.py             # Download orchestration
│   ├── config.py             # Configuration management
│   ├── aria2c/               # aria2c wrapper
│   ├── db/                   # SQLite database layer
│   ├── trackers/             # Tracker management
│   ├── tui/                  # Terminal UI components
│   └── utils/                # Utilities
├── tests/                    # Test suite
├── pyproject.toml            # Project configuration
└── README.md

---

Contributing

We welcome contributions! Please see our Contributing Guidelines.

Reporting Issues

• Use GitHub Issues
• Include: Python version, aria2c version, OS, error message, steps to reproduce

Pull Requests

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make changes with tests
4. Ensure all tests pass (poetry run pytest)
5. Submit pull request

---

License

MIT License - see LICENSE for details.

---

Acknowledgments

• aria2c - High-performance download utility
• Click - CLI framework
• Rich - Terminal formatting
• ngosang/trackerslist - Public tracker lists
• XIU2/TrackersListCollection - Additional tracker sources

---

Legal Notice

TorrentCLI Pro is designed for downloading legal content such as Linux distributions, open-source software, Creative Commons media, and other freely-distributable materials. Users are solely responsible for ensuring compliance with applicable copyright laws and terms of service in their jurisdiction.

---

TorrentCLI Pro - Enterprise-grade BitTorrent for the terminal