subsplease-dl 0.3.0

CLI downloader for SubsPlease.org anime releases with tmux session management

subsplease-dl

A pip-installable CLI downloader for SubsPlease.org with tmux session management — inspired by animepahe-dl-tmux.

pip install subsplease-dl

Requirements

• Python 3.9+
• A torrent client: aria2c (recommended), webtorrent-cli, or transmission-cli
• tmux for background download sessions (optional but recommended)

Install aria2 (recommended torrent client):

# Ubuntu/Debian
sudo apt install aria2

# macOS
brew install aria2

# Or use webtorrent-cli
npm install -g webtorrent-cli

Quick Start

# See what's airing right now
subsplease-dl latest

# Search for an anime (currently-airing shows)
subsplease-dl search "One Piece"

# View the weekly schedule
subsplease-dl schedule
subsplease-dl schedule --day Sunday

# Download the latest episode of a show (auto-detects quality)
subsplease-dl download --show "One Piece"

# Download a specific episode (use page slug from search/schedule)
subsplease-dl download --page one-piece --episode 1161

# Download in a detached tmux session (survives terminal close)
subsplease-dl download --show "One Piece" --tmux

# Just print the magnet link
subsplease-dl download --show "One Piece" --magnet-only

All Commands

search <query>

Search for currently-airing anime by name.

subsplease-dl search "mushoku tensei"

schedule

Show the full weekly airing schedule with page slugs.

subsplease-dl schedule
subsplease-dl schedule --day Monday

latest

Show recent episode releases with magnet links.

subsplease-dl latest
subsplease-dl latest --limit 30 --quality 720

episodes --page <slug>

List all available episodes for a show.

subsplease-dl episodes --page one-piece
subsplease-dl episodes --page one-piece --batches  # show batch releases

download

Download an episode. Supports --tmux for background downloads.

# By show name (latest episode)
subsplease-dl download --show "One Piece" --quality 1080

# By page slug + episode number
subsplease-dl download --page one-piece --episode 1161

# Print magnet link only (no download)
subsplease-dl download --page one-piece --episode 1161 --magnet-only

# Background download in tmux
subsplease-dl download --page one-piece --episode 1161 --tmux

# Custom output directory
subsplease-dl download --show "One Piece" --output ~/Downloads/anime

magnet --page <slug> --episode <ep>

Print or open a specific episode's magnet link.

subsplease-dl magnet --page one-piece --episode 1161
subsplease-dl magnet --page one-piece --episode 1161 --open  # open with system handler

watch <show>

Poll for new episodes and auto-download them.

# Run in foreground (Ctrl+C to stop)
subsplease-dl watch "One Piece" --quality 1080

# Run as persistent background tmux session
subsplease-dl watch "One Piece" --quality 1080 --tmux --interval 300

sessions

Manage active tmux download sessions.

subsplease-dl sessions list
subsplease-dl sessions attach spdl-one-piece-ep1161
subsplease-dl sessions kill spdl-one-piece-ep1161

Options Reference

Flag	Default	Description
-q / --quality	1080	Quality: 1080, 720, 480
-o / --output	./	Output directory
--client	auto	Torrent client binary
--tmux	off	Run in detached tmux session
--magnet-only	off	Print magnet link and exit
--interval	300	Watch poll interval in seconds
-l / --limit	20	Max results to show

Torrent Client Detection Order

1. aria2c
2. webtorrent
3. transmission-cli
4. qbittorrent-nox

Override with --client <binary>.

How It Works

• Latest / Watch: Uses subsplease.org/api/?f=latest — fast, no scraping required.
• Search / Schedule: Uses subsplease.org/api/?f=schedule — the full list of airing shows, fuzzy-matched client-side.
• Episodes: Scrapes the show's HTML page to extract its SID, then calls subsplease.org/api/?f=show&sid=<id>.
• Tmux sessions are named spdl-<show-slug>-ep<n> for easy identification.

Development

git clone ...
cd subsplease-dl
pip install -e ".[dev]"

License

MIT