torrent-finder-cli 0.2.0

Search torrents across multiple sources from your terminal and hand them to your client — subtitles, episode picking, batch download, and search-by-creator.

Torrent Search CLI

An interactive command-line application for searching and downloading torrents directly from your terminal. Built with Python and rich.

Install it from PyPI (pipx install torrent-finder-cli) or grab a standalone, no-Python binary from Releases — see Installation.

Features

• Multi-Category Search: Torrents across different providers (Movies & Series, Games, Software, Anime, Manga), each with its own tailored search backends. The Movies & Series provider handles both films and TV shows — the episode-aware streaming flow kicks in automatically when a torrent contains multiple video files. Software is a group on the provider screen: pick it and choose a source — Desktop (Windows/macOS/Linux programs via The Pirate Bay's Applications categories plus SolidTorrents), Mobile (Android apps — APK/MOD/OBB; Android-only and says so when you search), or RuTracker (logs into rutracker.org and searches it directly — great for software, audio, and rare content; needs an account set under the credentials menu, and stays dormant until one is configured). On the CLI these stay individually addressable: -t software, -t mobile, -t rutracker. Games is likewise a group: pick it and choose General (PC, consoles, ROMs & repacks from public trackers — The Pirate Bay's game categories plus SolidTorrents), Online-Fix (scrapes online-fix.me for co-op/online game cracks), or FitGirl (searches the official fitgirl-repacks.site — the one trustworthy source for FitGirl repacks, since fake "FitGirl" uploads on public trackers are a known malware vector; no account needed, the magnet resolves from the post when you pick a result). On the CLI they're -t game, -t online-fix, and -t fitgirl. Online-Fix needs no account — both search and download are anonymous (the file host is referer-gated, not login-gated); picking a result downloads the .torrent into your download folder and opens it in your system torrent client, showing the archive password (online-fix.me) to unpack the game with. Manga is also a group: General (Nyaa Literature + Apibay Comics) or Madokami (the private manga.madokami.al library — needs an account under the credentials menu; hits are direct downloads, no torrent client involved: picking a series folder opens a volume picker and the chosen archives are saved straight to your download folder). On the CLI: -t manga and -t madokami.
• Multi-Engine Fan-Out: Each provider queries several sources in parallel (e.g. Apibay + SolidTorrents + YTS + Nyaa live-action for Movies & Series, Nyaa for Anime, Nyaa Literature + Apibay Comics for Manga) and merges results, deduplicating by info hash and sorting by seeders.
• Search by Creator: Search by the people and companies behind the content instead of by title. After choosing a provider, a "choose how to search" screen offers normal keyword search plus by-creator options — Anime and Movies & Series by director or studio, Manga by writer or serialization magazine, Games by developer or publisher (kept separate — a company can be both). You type a name, disambiguate between matches, then multi-select which of that creator's titles to include (a paged checklist, 100 per page with n/p); the app runs a normal torrent search for each picked title and merges the results — so picking still uses all the usual download/stream/episode options. It works keyless out of the box (AniList for anime/manga staff, Jikan for manga magazines, Wikidata for movies/games), and an optional TMDB key (Movies & Series) or Twitch/IGDB credentials (Games) added under 🔑 Credentials transparently upgrade those two to richer, better-ranked data. Online-Fix is included in the Games developer/publisher results. From the CLI: --by <role> --name "<creator>" alongside -t, e.g. torrent -t anime --by director --name "Hayao Miyazaki".
• Search Several at Once (multi-title): At the keyword prompt, press Ctrl+N to add another title, then Enter to search them all together — results fan out across the provider's engines and merge into one list. A From column shows which searched title each result came from, so interleaved results are easy to tell apart.
• Multi-Select & Batch Download: In the results table, press Space to tick more than one torrent (a select all, c clear), then Enter. A batch menu lets you open all in your torrent client, download all with aria2c (one parallel process — no client needed), or copy all magnet links at once. Works for any results — several releases of one title, or picks spanning a multi-title / by-creator search. A single pick still opens the full per-torrent download menu.
• Arrow-Key Driven UI: Fully interactive, flicker-free terminal interface.
  • Utilizes an alternate screen buffer so your scrollback history remains flawlessly clean.
  • Dynamic Viewport Windowing: Capable of rendering massive 500+ item checklists (like huge anime seasons) by automatically windowing the active selection while pinning crucial action buttons tightly to the top and bottom of your screen to prevent terminal overflow.
  • Marquee Scrolling: Automatically scrolls long torrent names and checklist items that exceed the physical terminal width when hovered over.
  • Contextual Footers: Displays dynamic helper text explaining the trade-offs, speeds, and seeding behaviors of different download options as you highlight them.
• Advanced Filtering:
  • Toggle built-in presets (preferred resolutions, known uploaders/repackers, trusted release groups) using an interactive checklist.
  • Toggle individual search engines on and off per provider from the same menu.
  • Add custom include/exclude keywords to quickly find the exact release you want.
  • Shared keybinds with the episode picker: a select all • i invert • c clear presets • w save • v / Shift+V visual anchor + range toggle • Space toggle current.
  • Persistent across runs: engine toggles, active filter presets, search history, usage stats, the quiet-mode flag, the chosen download folder, and the dismissed-warning state all live in filter_state.json in your user data folder (see Where your data lives), so configuration sticks after you close the program. Mutations are held in an in-memory cache and flushed on exit or after destructive actions (clear history, reset stats, filter-menu Confirm) — no per-event disk hit.
• Search History: Press H on the provider screen (or Tab then H at the search prompt) to browse past searches. Filter by provider (P), date range (D, today/week/month), and sort order (S). Each entry shows the provider, relative timestamp, and the filter presets that were active at search time. Pick an entry to re-run the query; clear history with a confirmation modal.
• Usage Stats: Press S on the provider screen (or Tab then S at the search prompt) to open a scrollable stats page showing session count, total runtime, searches, top queries, torrents picked, method picks vs. completions (with success rate), avg seeders of picks, and preset usage counters. Reset all stats from the same screen, guarded by a confirmation modal.
• Confirmation Modals: Destructive actions (clear history, reset stats) share a unified red Y/N panel so you can't nuke state with a stray keypress.
• Dynamic Contextual Tips: Random hints (💡 Tip: ...) are displayed in the provider selector and post-download menus. A searchable tips browser is also available from the provider screen (T), the search prompt (Tab then T), and the post-download menu.
• Quiet Mode: Toggle 🔇 Quiet mode from the Download Method menu to suppress the native progress UIs of aria2c, webtorrent-cli, and peerflix (full-screen progress bars, peer lists, speed graphs) and replace them with a single minimal spinner. The toggle redraws in place with no flicker and persists across runs (stored as hide_stream_output in filter_state.json). Episode info, VLC hotkey hints, and Ctrl+C all still work.
• Flexible Downloading & Streaming:
  • System Client: Automatically send generated magnet links to your default system torrent client (like qBittorrent, Transmission, etc.).
  • Direct Terminal Download: Use aria2c, webtorrent-cli, or peerflix integration to download files directly within the terminal, with native progress UIs.
  • File Browser / Episode Picker (Anime, Movies & Series, Manga): Open 📂 Browse torrent files… from the download menu to list every file in the torrent (videos, subs, artwork, .nfo, samples — or individual volumes/chapters for Manga) and pick any subset. Opening it fetches the torrent's file list over DHT via aria2c, which can take 30–60s (or stall on low-peer torrents) — press Esc during the load to cancel and return to the menu. Features vim-style visual range selection (v anchor, Shift+V range-toggle) and rapid hotkeys (a, i, c, w). Selection persists across re-entries — reopening the picker shows your existing checkboxes already ticked, so you can refine without rebuilding from scratch. Confirming with nothing checked clears the selection; Esc cancels and keeps the prior picks intact. Only aria2c honors strict file selection on download — webtorrent and peerflix ignore --select and pull the whole torrent (the menu warns you when a selection is active). Streams auto-skip non-video picks and warn about it, so you can still e.g. download the .srt + .nfo alongside the video without breaking playback. If a stream selection contains zero video files, the stream errors out instead of silently substituting another file.
  • Torrent Info (from origin): In the Torrent & files section of the download menu, ℹ Torrent info fetches details straight from the source page — category, uploader, date, description, and the full file list. Supported sources: Nyaa (scraped), The Pirate Bay (Apibay JSON API) and YTS (API); other engines show "not available". It also reports whether subtitles are embedded in the video: a filename/metadata heuristic (e.g. an anime "English-translated" category or a [Subbed] tag), upgraded to a definitive answer via ffprobe when ffmpeg is installed and a copy of the video has already been downloaded — useful to tell a soft-subbed MKV apart from a raw release with no separate .srt.
  • Stream to VLC: Stream media directly to VLC Media Player using webtorrent-cli (default) or peerflix (fallback). Both stream and download menus list webtorrent before peerflix to match this preference. Press the v hotkey at any time during a streaming session to reopen VLC without losing your torrent download/buffering progress. The CLI checks active processes (tasklist on Windows, pgrep -x on Mac/Linux) and silently ignores the hotkey if VLC is already running, preventing accidental duplicate windows. When an episode is selected, streams that specific file.
  • Subtitles for streams (auto + manual): A 📝 Source: <mode> row in the Download Method menu controls how VLC gets subtitles for the next stream:
    • auto-detect from torrent (default) — scans the torrent for .srt/.ass/.ssa/.vtt/.sub files paired with each video (matched by basename, language tag like .en.srt, or a sibling Subs/ folder with episode-numbered files like 01.ass). Matches are pre-downloaded via aria2c and attached to VLC via --sub-file before playback starts. English subs are prioritized as the primary track when available.
    • external file — pick a .srt/.ass from a list of recent files in your chosen download folder (defaults to downloads/), or type a custom path. The same file is attached to every episode in the session.
    • off — stream with no subtitles.
    • After downloading subs via 📝 Search & download subtitles (the existing subliminal flow), the saved file is auto-promoted to external mode so your next stream just picks it up.
  • Auto Episode Navigation: When streaming a torrent with ≥ 2 video files without pre-selecting anything, the CLI fetches metadata via aria2c, queues every video file in episode order (using filename patterns like S01E01, - 01, [01], Episode 01, or E01 when present; alphabetical fallback otherwise), and enables n (next) / b (previous) hotkeys so you can jump between episodes mid-session. Single-file movies still stream as-is — no forced picker, no extra wait.
  • Subtitle Download: Search and download the best matching subtitles directly from the terminal using subliminal. Enter one or more languages separated by commas (e.g. eng, por or pt-BR) — accepts ISO codes (eng/en) and regional variants (pt-BR, pt-PT). Every available language is downloaded, the first in your order becomes the primary VLC track (the rest attach as switchable tracks), and any language it couldn't find is reported. If a matching video has already been downloaded, it hash-matches the real file for frame-accurate sync; otherwise it matches on the release name. Configuring OpenSubtitles.com credentials greatly improves results (see Subtitle providers below). For Anime searches, a dedicated Jimaku lookup (jimaku.cc) runs first when a JIMAKU_API_KEY is set, since the western-TV providers behind subliminal don't index anime fansubs well.
  • Configurable Download Folder: A 📁 Save to: row in the Download Method menu — or the 📁 Download folder row on the Select Provider screen, which shows the current path — sets a persistent default download directory used by aria2c, webtorrent, peerflix downloads, the subtitle downloader, and Online-Fix / Madokami file saves. Picker offers Default (downloads/), ~/Downloads, or a custom path (created on-the-fly if missing). Streams and magnet-to-client handoff are unaffected — they use their own paths.
  • Clipboard Integration: Easily copy magnet links directly to your OS clipboard (Windows/macOS/Linux).
  • Seamless Error Recovery: If a terminal download fails, lacks dependencies, or is manually forcefully aborted by you (Ctrl+C), the CLI intercepts the exit and safely drops you back into the download method selector without losing your active search context.
• Network Exposure Warning: At startup a red panel queries ip-api.com and shows your public IP, ISP, ASN, location, plus flags for proxy / hosting / mobile. Gives you a clear go/no-go decision before joining a public swarm.
• Install-Aware Update Check: On startup the app checks for a newer version (at most once a day, fail-silent) and shows a notice tailored to how you installed it — a pip/pipx install compares against PyPI, a git clone against origin, a standalone binary against the latest Release. Press Tab → ⬆ Install update to update in place (pipx upgrade/pip -U, git pull, or open the Releases page).
• Pagination & Navigation: Navigate through large sets of search results cleanly, with the ability to safely go back to your previous search results after viewing download options.

Prerequisites

• Python 3.10+ — for the PyPI/pip install or running from source. Not needed for the standalone binary.
• (Optional but recommended) Node.js & npm for installing webtorrent-cli or peerflix.
• (Optional) VLC Media Player — required for streaming.
• (Optional) aria2 — required for the file browser / episode picker, the in-torrent subtitle auto-detect path, auto episode navigation on the peerflix backend, and single-process multi-file downloads. Install with winget install aria2.aria2 (Windows), brew install aria2 (macOS), or apt install aria2 / dnf install aria2 (Linux).

Installation

With Python (3.10+) — from PyPI

Install from PyPI; pipx keeps it isolated in its own environment:

pipx install torrent-finder-cli      # recommended
# or
pip install torrent-finder-cli

Then run it from anywhere:

torrent-finder

Without Python — standalone binary

Download a ready-to-run build for your OS from the Releases page: torrent-finder-windows.exe, torrent-finder-macos, or torrent-finder-linux. On Windows, double-click it (if SmartScreen warns, More info → Run anyway — it's just unsigned). On macOS/Linux, make it executable (chmod +x <file>) and run it from a terminal; on macOS the first run may need System Settings → Privacy & Security → Open anyway.

From source (for development)

git clone https://github.com/PietroFilippo/torrent-finder-cli.git
cd torrent-finder-cli
pip install -e .

Run it with torrent-finder, python -m torrent_finder, or torrent.bat (Windows). An editable install keeps pointing at your clone, so git pull updates it.

Optional direct download / streaming tools

Install these only if you want terminal-managed downloads or Stream to VLC:

npm install -g webtorrent-cli peerflix

aria2c is separate from Python/npm and is required for file browsing, strict multi-file selection, in-torrent subtitle extraction, and some auto episode metadata flows.

# Windows
winget install aria2.aria2

# macOS
brew install aria2

# Debian/Ubuntu
sudo apt install aria2

Credentials (optional)

Several features improve with — or, for RuTracker and Madokami, require — an account. Credentials are read at runtime from environment variables (preferred) or a subtitle_credentials.json in your user data folder (see Where your data lives) — never commit real values.

The easiest way to set them is in-program: on the Select Provider screen, choose 🔑 Credentials. For each provider you can view, enter/update, or clear its login. Entering opens a single-screen form — edit every field in place (Up/Down or Tab to move, Enter to advance, Esc to cancel) and Save when done. Saved values are verified against the provider (where possible) and written to subtitle_credentials.json; the view screen masks the password / API key with a toggle to reveal them. Environment variables, if set, override the file (the menu flags this), and Clear only empties the file — unset the matching environment variables to remove a credential that's set there.

• OpenSubtitles.com (movies & series): a free account dramatically improves results and unlocks hash-accurate matching against a downloaded file.
• Addic7ed (TV series): a free account raises rate limits and quality for episodic content. Runs anonymously (limited) when no credentials are set.
• Jimaku (anime): a free API key (jimaku.cc → account settings) enables a dedicated anime subtitle lookup that runs before subliminal for Anime searches. Without the key, Anime falls back to subliminal automatically.
• RuTracker (the RuTracker provider): a free rutracker.org account is required — the provider logs in to search and returns nothing without one.
• Madokami (the Madokami provider, under Manga): an account on manga.madokami.al is required — the whole site sits behind HTTP Basic auth, so the provider returns nothing without one. Like RuTracker, this credential gates the whole provider.
• Online-Fix (the Online-Fix provider): optional. Both search and .torrent download work anonymously (online-fix.me's file host is referer-gated, not login-gated). A login is supported (the site's DataLife Engine authtoken flow) for completeness but isn't required.
• TMDB (Movies & Series "by director / studio"): optional. That search already works keyless via Wikidata; a free TMDB v3 API key (account → Settings → API) upgrades it to richer, better-ranked results.
• IGDB (Games "by developer / publisher"): optional. That search already works keyless via Wikidata; free Twitch/IGDB credentials (register an app at dev.twitch.tv → Client ID + Client Secret) upgrade it.

subliminal queries a curated set of providers — opensubtitlescom, addic7ed, podnapisi, tvsubtitles — chosen for broad coverage and reliability. The rest of subliminal's defaults (defunct legacy APIs, VIP-only variants, and single-language scrapers) are skipped.

Set them as environment variables:

# Windows (persists for new terminals)
[Environment]::SetEnvironmentVariable("OPENSUBTITLES_USERNAME", "your_user", "User")
[Environment]::SetEnvironmentVariable("OPENSUBTITLES_PASSWORD", "your_pass", "User")
[Environment]::SetEnvironmentVariable("ADDIC7ED_USERNAME", "your_user", "User")
[Environment]::SetEnvironmentVariable("ADDIC7ED_PASSWORD", "your_pass", "User")
[Environment]::SetEnvironmentVariable("JIMAKU_API_KEY", "your_key", "User")
[Environment]::SetEnvironmentVariable("RUTRACKER_USERNAME", "your_user", "User")
[Environment]::SetEnvironmentVariable("RUTRACKER_PASSWORD", "your_pass", "User")
[Environment]::SetEnvironmentVariable("ONLINE_FIX_USERNAME", "your_user", "User")
[Environment]::SetEnvironmentVariable("ONLINE_FIX_PASSWORD", "your_pass", "User")
[Environment]::SetEnvironmentVariable("MADOKAMI_USERNAME", "your_user", "User")
[Environment]::SetEnvironmentVariable("MADOKAMI_PASSWORD", "your_pass", "User")
[Environment]::SetEnvironmentVariable("TMDB_API_KEY", "your_key", "User")
[Environment]::SetEnvironmentVariable("IGDB_CLIENT_ID", "your_id", "User")
[Environment]::SetEnvironmentVariable("IGDB_CLIENT_SECRET", "your_secret", "User")

# macOS / Linux (add to your shell profile)
export OPENSUBTITLES_USERNAME="your_user"
export OPENSUBTITLES_PASSWORD="your_pass"
export ADDIC7ED_USERNAME="your_user"
export ADDIC7ED_PASSWORD="your_pass"
export JIMAKU_API_KEY="your_key"
export RUTRACKER_USERNAME="your_user"
export RUTRACKER_PASSWORD="your_pass"
export ONLINE_FIX_USERNAME="your_user"
export ONLINE_FIX_PASSWORD="your_pass"
export MADOKAMI_USERNAME="your_user"
export MADOKAMI_PASSWORD="your_pass"
export TMDB_API_KEY="your_key"
export IGDB_CLIENT_ID="your_id"
export IGDB_CLIENT_SECRET="your_secret"

Or create subtitle_credentials.json in your user data folder (see Where your data lives):

{
  "opensubtitles_username": "your_user",
  "opensubtitles_password": "your_pass",
  "addic7ed_username": "your_user",
  "addic7ed_password": "your_pass",
  "jimaku_api_key": "your_key",
  "rutracker_username": "your_user",
  "rutracker_password": "your_pass",
  "online_fix_username": "your_user",
  "online_fix_password": "your_pass",
  "madokami_username": "your_user",
  "madokami_password": "your_pass",
  "tmdb_api_key": "your_key",
  "igdb_client_id": "your_id",
  "igdb_client_secret": "your_secret"
}

Environment variables take precedence over the file. All keys are optional — anything unset just falls back to the anonymous provider set.

Where your data lives

Your settings, credentials, search history, usage stats, and the default downloads folder are stored in a per-user data directory — not next to the code, so it survives upgrades and works the same for pip, pipx, and binary installs:

• Windows: %LOCALAPPDATA%\torrent-finder-cli\
• macOS: ~/Library/Application Support/torrent-finder-cli/
• Linux: $XDG_DATA_HOME/torrent-finder-cli/ (or ~/.local/share/torrent-finder-cli/)

It holds filter_state.json (settings, history, stats), subtitle_credentials.json, and downloads/. If you used an older version that kept these next to the code, they are migrated here automatically on first run (the originals are left untouched).

Updating

The app checks for a newer version on startup (at most once a day, fail-silent) and shows a notice when one is available. Update from inside the program with Tab → ⬆ Install update, which does the right thing for your install type:

• pip / pipx — runs pipx upgrade torrent-finder-cli (or pip install -U); restart the app afterward.
• standalone binary — opens the Releases page so you can download the new file.
• source clone — runs git pull.

Or update manually any time with pipx upgrade torrent-finder-cli.

Usage

Interactive Mode

The easiest way to use the CLI is to run it interactively. The arrow-key driven UI will guide you through selecting a category, searching, filtering, and downloading.

# After a pip/pipx install — the command is on your PATH
torrent-finder

# From a source clone
python -m torrent_finder
torrent.bat            # Windows

The command is torrent-finder. The examples below shorten it to torrent for brevity — substitute torrent-finder (or, from a source clone, torrent.bat).

Command Line Arguments

# Direct search (defaults to Movies)
torrent -q "The Matrix"

# Specify the search type (movie, game, online-fix, fitgirl, software, mobile, rutracker, anime, manga, madokami). `movie` covers both films and series.
torrent -q "Elden Ring" -t game

# Search Online-Fix (co-op / online game cracks from online-fix.me; no account needed)
torrent -q "Elden Ring" -t online-fix

# Search FitGirl repacks on the official fitgirl-repacks.site (no account needed)
torrent -q "Cyberpunk" -t fitgirl

# Search desktop software (The Pirate Bay Applications + SolidTorrents)
torrent -q "Photoshop" -t software

# Search Android apps (The Pirate Bay Android category; Android-only)
torrent -q "Spotify" -t mobile

# Search RuTracker (requires a configured rutracker.org login)
torrent -q "Photoshop" -t rutracker

# Search manga (Nyaa Literature English + Apibay Comics; Raw Nyaa available as a toggle)
torrent -q "Berserk" -t manga

# Search Madokami's manga library (requires a manga.madokami.al login; direct downloads)
torrent -q "Berserk" -t madokami

# Apply custom filters (include "1080p", exclude "cam")
torrent -q "Dune" -t movie -f "1080p" -x "cam"

# Search by creator: --by <role> --name "<creator>" with -t. Roles per provider:
#   anime/movie -> director, studio   manga -> writer, magazine   game -> developer, publisher
torrent -t anime --by director --name "Hayao Miyazaki"
torrent -t movie --by studio   --name "A24"
torrent -t game  --by developer --name "FromSoftware"
# Drops you into the disambiguation + title picker; keyless by default,
# richer with a TMDB key (movies) or IGDB creds (games).

# Skip the network exposure warning at startup
torrent -y

# Print the version and exit
torrent --version

You can also suppress the warning with the environment variable TORRENT_SKIP_WARNING=1, or permanently dismiss it from inside the panel itself (see below).

From a source clone with no pip install, replace torrent with python -m torrent_finder in the examples above.

Network Exposure Warning

On launch you'll see a red panel listing your public IP, ISP, ASN and location, with a verdict line:

• ✓ Proxy/VPN flagged — detected by the IP database.
• ✓ Hosting/datacenter IP — likely a VPN exit (not a residential ISP).
• ✓ VPN provider name detected — keyword fallback (Mullvad, Proton, Nord, …).
• ⚠ Mobile carrier IP — your carrier and peers will see this IP.
• ⚠ Residential ISP IP — your real IP is visible to every peer and tracker.

Controls inside the panel:

• Enter — acknowledge and continue.
• D — don't show again (saved to filter_state.json).
• Esc — abort the program.

Even after dismissing, you can re-open the warning at any time from the Select Provider screen: scroll to the 🔒 Network exposure info item and press Enter.

Navigating the UI

• Lists & Menus: Use Up and Down arrows to navigate.
• Select: Press Enter to confirm a choice or open a torrent.
• Toggle: In multi-select menus (like Filters), press Enter or Space on an item to toggle its checkbox.
• Search prompt (multi-title): Ctrl+N commits the current title and starts another line; Enter searches them all at once. Tab opens quick actions, Ctrl+F jumps to filters, and Up/Down recall past searches.
• Results table (multi-select / batch): Space ticks a torrent, a selects all results, c clears. With one or more ticked, Enter opens the batch menu (open all in client • download all with aria2c • copy all magnets); with nothing ticked, Enter opens that single torrent's download menu.
• Range Selection (Episode Picker):
  • v: Drop a visual anchor on the current item.
  • Shift + V: Instantly mass-toggle all items between the anchor and your cursor.
  • a (Select All) • i (Invert Selection) • c (Clear) • w (Save & Continue).
• Configure filters from the provider screen: Press F while a provider is highlighted to jump straight into its engines + filter presets menu, then return to the provider list.
• Filter menu keybinds: a select all, i invert, c clear presets, w save & confirm, v drop anchor, Shift+V range toggle between anchor and cursor, Space toggle current. The "Clear filters" button clears preset toggles only — your engine selections are preserved.
• History / stats / tips / filters: On the provider screen press H (history), S (stats), T (tips), or F (filters). At the search prompt, press Tab for the same quick-actions menu (then F/H/S/T or arrows) — your in-progress query is preserved. The prompt itself has no single-letter shortcuts, so queries can start with any letter.
• Tips browser: Use / to search across categories, tip text, and tags; C to cycle categories; X to clear the search/filter; and Esc to go back.
• Cancel / Back: Press Esc to safely cancel an action, close a menu, or go back to the previous screen.

Project Architecture

All code lives under the torrent_finder/ package, installed as a console script (torrent-finder = torrent_finder.main:main). The structure is modular and provider-based — the module paths below are relative to torrent_finder/:

• main.py: The main entry point and CLI argument parser.
• __main__.py: Enables python -m torrent_finder and serves as the PyInstaller binary entry point.
• torrent.bat (repo root): Windows launcher that runs python -m torrent_finder.
• providers/: Different search categories (Movies & Series, General games, Online-Fix, FitGirl, Desktop, Mobile, RuTracker, Anime, General manga, Madokami). The display menu nests some of these under groups — Games (General + Online-Fix + FitGirl), Software (Desktop + Mobile + RuTracker), and Manga (General + Madokami) — via ProviderGroup, a display-only wrapper that changes menu shape without touching slugs. Each provider declares an immutable slug (used for persistence keys + CLI -t lookup), a display name (free to change), capability flags (supports_subtitles, supports_episode_picker — gate UI rows), its search engines, default filters, and toggleable presets. Nyaa-backed providers also set nyaa_category (the Nyaa c filter — e.g. 1_2 anime, 4_1 live-action, 3_1 manga). Providers may also declare a creator_facets list to enable search-by-creator (director/studio/writer/magazine/developer/publisher).
• resolvers/: The "search by creator" metadata layer that turns a person/company name into a list of works. types.py (CreatorFacet / Entity / Work), anilist.py (anime director & studio + manga writer, keyless GraphQL), jikan.py (manga serialization magazines, keyless), wikidata.py (keyless SPARQL fallback for movie/series director & studio and game developer & publisher), tmdb.py (Movies & Series, needs TMDB_API_KEY), igdb.py (Games, needs Twitch creds), and movies.py / games.py which dispatch to TMDB/IGDB when a key is configured and Wikidata otherwise. Each facet exposes search_entities(name) → candidates and list_works(entity, page) → (works, has_more); creator_search.fan_out() then runs the normal provider search over each picked title and merges. main._available_facets can gate facets behind a credential when there's no keyless fallback.
• ui/: Interactive terminal prompts and rendering using rich. prompts.py (menus + confirm_prompt modal + subtitle_source_prompt + download_dir_prompt + the per-provider "choose how to search" source screen), creator.py (the search-by-creator flow: name → disambiguation → paged title picker with n/p + background prefetch → fan-out), selector.py (reusable arrow-key selector with windowing / marquee), table.py (paginated result table), history.py (search history browser), stats.py (usage stats page), streaming.py (themed Panel header + terminal-control primitives for the streaming flow), tips.py (categorized tip catalog), and tips_page.py (searchable tips browser).
• filters.py: Logic processing for including or excluding keywords.
• creator_search.py: fan_out() for search-by-creator — runs the provider's normal search() over each picked title concurrently and merges (dedupe by info hash, sort by seeders), tagging each result with the title it came from.
• credentials.py: Reads optional API credentials from environment variables (preferred) or the gitignored subtitle_credentials.json; powers the 🔑 Credentials menu (subtitle logins, RuTracker/Online-Fix/Madokami, and the TMDB/IGDB creator-search upgrades).
• torrent_session.py: Post-torrent-pick state owner. Holds the picked magnet + user file selection + sub choice, and lazily resolves files_meta / targets / stream_indexes / download_indexes / sub_paths. Stream adapters consume the session directly; download adapters take (magnet, indexes) projections and stay session-unaware.
• downloader.py: Subprocess orchestration — aria2c / webtorrent-cli / peerflix execution, VLC launch + sub injection, quiet-mode plumbing, in-torrent sub batch fetch, and v / n / b hotkey handling. Stream adapters take a TorrentSession; download adapters keep an explicit (magnet, indexes) signature for reuse outside the menu loop.
• subtitles.py: Logic for searching and downloading subtitles using subliminal. Saves into the effective download folder via constants.get_download_dir().
• security.py: Network exposure warning, public-IP/VPN detection via ip-api.com.
• state.py: Persists engine toggles, active presets, misc settings (dismissed-warning flag, quiet-mode flag, download_dir), and search history to filter_state.json. Backed by an in-memory cache: mutations mark dirty, disk write happens at atexit and at three destructive sites (save_state, clear_history, reset_stats). Includes a one-shot migration that rewrites legacy display-name keys (e.g. "Movies & Series") to provider slugs.
• stats.py: Usage counter recorders and read helpers; stores under the stats subtree, keyed by provider slug. Same in-memory cache flow as state.py.
• torrent_meta.py: Fetches a torrent's file list from a magnet via aria2c. Helpers for episode-number extraction, video/subtitle classification, multi-episode detection (any torrent with ≥ 2 video files), sub-to-video matching (match_subtitles_for), and --select-file range formatting.
• updates.py: Install-aware update check (git clone / pip-pipx / binary). Rate-limited; compares against origin (git) or PyPI (__version__), and powers the in-app Install update action via check_for_update() / run_update().
• constants.py: Configuration constants, trackers, UI themes, the per-user data directory resolver (user_data_dir() / data_path(), with first-run migration of legacy files), and get_download_dir() (returns the user's chosen download_dir setting or falls back to DOWNLOADS_DIR).

Security Notes

This tool does not make torrenting safe. Some things it cannot guarantee:

• Your real IP is visible to every peer and tracker in the swarm unless you are behind a VPN.
• Trackers in constants.py are plain UDP — there is no "tracker-over-HTTPS" that hides your IP, since trackers exist to exchange peer IPs.
• Seed counts, file names, and uploader tags are not safety signals. The "Trusted Uploaders" preset is a convenience filter based on community reputation, not a guarantee of clean content.
• The startup ip-api.com call travels over plain HTTP (free tier limitation). If that matters to you, use -y or TORRENT_SKIP_WARNING=1.

Use a VPN, verify content before running installers, and treat everything in a public swarm as untrusted.

License

Released under the MIT License.