Metadata-Version: 2.5
Name: plexo-cli
Version: 0.1.2
Summary: Multi-network bandwidth bonding download engine & CLI
Author-email: Jagjot Singh <gotogether@gmail.com>
License-Expression: MIT
Keywords: bandwidth-aggregation,download-accelerator,multi-interface,network-bonding,proxy,torrent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: rich>=13.7.0
Requires-Dist: urllib3>=2.0.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# ⚡ Plexo CLI (`plexo-cli`)

[![PyPI version](https://img.shields.io/pypi/v/plexo-cli.svg?color=blue)](https://pypi.org/project/plexo-cli/)
[![Python versions](https://img.shields.io/pypi/pyversions/plexo-cli.svg)](https://pypi.org/project/plexo-cli/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-36%20passed-success.svg)](tests/)

> **Universal, lightweight, terminal-first multi-network bandwidth bonding and torrent engine.**  
> Combines Wi-Fi, Ethernet, and Mobile 5G tethering into one unified high-speed pipe directly from your command line.

---

## 🚀 Key Features

* **🌐 Multi-Socket Bandwidth Bonding:** Binds parallel download workers to distinct physical network interfaces using source-IP socket routing (`urllib3.PoolManager(source_address=(NIC_IP, 0))`).
* **🧲 BitTorrent Multi-Homing Swarm:** Slices BitTorrent peer swarms across multiple network adapters simultaneously with SHA-1 piece verification.
* **🎬 Watch While Downloading (`--sequential`):** Prioritizes file headers (moov container) and opening frames so media players like **VLC** can stream video immediately from byte 0.
* **🪞 Multi-Source Mirror Bonding (`-m / --mirror`):** Pulls chunks simultaneously across distinct server mirrors (e.g. Mirror A on Wi-Fi, Mirror B on 5G) to bypass server-side IP throttling.
* **🛡️ Per-Adapter Data Quotas (`-q / --quota`):** Protects mobile hotspot data caps (e.g. `-q usb=1.5GB`). When the cap is reached, that connection rests while unlimited Wi-Fi finishes the rest.
* **📂 Selective Torrent Downloads (`--list`, `--select`):** Inspect contents of multi-file season packs and download only the specific episodes you need.
* **📋 Background Clipboard Watcher (`plexo watch`):** IDM-style daemon that monitors the system clipboard and auto-captures `.mp4`, `.mkv`, `.zip`, `.iso`, or `magnet:` links.
* **⚡ Zero-Touch Local Acceleration Proxy (`plexo proxy`):** Runs a local forward proxy (`127.0.0.1:8899`) to bond traffic for `pip`, `curl`, `git`, and `huggingface-cli`.
* **💾 Smart Checkpointing & Instant Resume (`.plexo`):** Non-destructive NTFS/ext4 sparse file pre-allocation with zero-overhead resume on interrupted downloads.

---

## 📦 Installation

### From PyPI
```bash
pip install plexo-cli
```

### From Source (Editable Mode)
```bash
git clone https://github.com/anmolkapil/plexo.git
cd plexo/packages/plexo-cli
pip install -e .
```

---

## 🛠️ CLI Command Reference

### 1. Discover Active Interfaces: `plexo adapters`
Scans and validates all active physical, Ethernet, and wireless interfaces, verifying outward internet reachability via canary probes:
```bash
plexo adapters
```

*Example Output:*
```text
+-------------------+---------------+----------+---------+--------+
| Adapter Name      | IP Address    | Type     | State   | Canary |
+-------------------+---------------+----------+---------+--------+
| Wi-Fi (Hostel)    | 192.168.1.104 | Wi-Fi    | UP      | ONLINE |
| Phone 5G USB      | 192.168.43.55 | Ethernet | UP      | ONLINE |
+-------------------+---------------+----------+---------+--------+
```

---

### 2. Bonded HTTP Downloads: `plexo download`

#### Basic Parallel Download
```bash
plexo download "https://example.com/largefile.zip" -o "largefile.zip"
```

#### Watch While Downloading (`--sequential`)
Download chunks in strict chronological order so you can open and watch the video in VLC within 30 seconds:
```bash
plexo download "https://example.com/movie.mp4" --sequential -o "movie.mp4"
```

#### Multi-Source Mirror Bonding (`-m / --mirror`)
Distribute chunk downloads across multiple server mirrors and multiple adapters:
```bash
plexo download "https://mirror1.com/ubuntu.iso" -m "https://mirror2.com/ubuntu.iso" -o "ubuntu.iso"
```

#### Protect Mobile Data Caps (`-q / --quota`)
Specify a maximum data quota for any adapter by name or IP:
```bash
# Cap Phone USB tethering to 1.5 GB, let Wi-Fi pull the rest:
plexo download "<url>" -q "usb=1.5GB"

# Cap a specific network IP to 500 MB:
plexo download "<url>" -q "192.168.43.55=500MB"
```

#### Authenticated / Protected Filelockers (`--cookie`, `--referer`, `-H`)
```bash
plexo download "<protected-url>" \
  --cookie "session_token=abcdef123456" \
  --referer "https://filelocker.com/view" \
  -H "Authorization: Bearer my_token"
```

---

### 3. BitTorrent Swarm Multi-Homing: `plexo torrent`

#### Magnet Links & `.torrent` Files
```bash
# Magnet URI:
plexo torrent "magnet:?xt=urn:btih:EXAMPLE_HASH&dn=Debian" -o "D:\Downloads"

# Local .torrent file:
plexo torrent "debian.torrent" -o "D:\Downloads"
```

#### Inspect Torrent Files (`--list`)
```bash
plexo torrent "magnet:?xt=urn:btih:..." --list
```

#### Download Selected Files (`--select`)
Download only specific files or episodes from large torrents:
```bash
# Download only Episode 1 (index 1):
plexo torrent "magnet:?xt=urn:btih:..." --select 1

# Download multiple episodes:
plexo torrent "magnet:?xt=urn:btih:..." --select 1,2,5
```

#### Sequential Torrent Playback (`--sequential`)
```bash
plexo torrent "magnet:?xt=urn:btih:..." --sequential -o "D:\Movies"
```

---

### 4. Background Clipboard Watcher: `plexo watch`
Listens in the background for copied download links (`.mp4`, `.mkv`, `.zip`, `.iso`, `magnet:`, etc.):

```bash
# Interactive mode (prompts [Y/n] when a downloadable URL is copied):
plexo watch

# Headless / Auto-download mode:
plexo watch -a -o "D:\Downloads"

# Auto-download with sequential streaming:
plexo watch -a --sequential -o "D:\Movies"
```

---

### 5. Local Acceleration Proxy: `plexo proxy`
Accelerate development tools across bonded network connections:

```bash
# Start proxy on default port 8899:
plexo proxy --port 8899
```

In another terminal, direct tools to use the proxy:
```bash
# Accelerate pip:
pip install torch torchvision --proxy http://127.0.0.1:8899

# Accelerate curl / Hugging Face CLI:
export HTTPS_PROXY="http://127.0.0.1:8899"
curl -O https://example.com/dataset.tar.gz
```

---

### 6. Probe Server Capabilities: `plexo info`
Inspect remote server headers, file size, MIME type, and byte-range support:
```bash
plexo info "https://example.com/file.zip"
```

---

## 🧪 Verification & Testing

The package includes a comprehensive automated test suite testing live sockets, mock mirrors, sparse file allocation, torrent bencoding, QoS quota enforcement, and clipboard regex extractors:

```bash
pytest packages/plexo-cli -v
```
```text
tests/test_adapter.py     PASSED (3/3)
tests/test_sparse.py      PASSED (3/3)
tests/test_torrent.py     PASSED (4/4)
tests/test_engine.py      PASSED (5/5)
tests/test_watcher.py     PASSED (12/12)
tests/test_mirror.py      PASSED (9/9)
============================= 36 passed in 10.10s =============================
```

---

## 📄 License
MIT © Anmol Kapil & Jagjot Singh
