▀█▀ █▀▄ ▄▀▄ █ ▄ █ █ ╱╲╱╲╱╲
█ █▀▄ █▀█ ▀▄▀▄▀ █▄▄ ╲╱╲╱╲╱
A curated, terminal-native torrent & book finder. One search trawls a short
list of reputable sources — games, movies, TV, anime, books — at once; pick a
result and aria2 downloads it (magnets, direct http links, and ebooks).
Just type trawl — no Node, no npx, no install step.
Trawl is a from-scratch Python TUI inspired by torlink (the look and feel) and driven by aria2 like its sibling Riptide — zero third-party packages, stdlib only.
▀█▀ █▀▄ ▄▀▄ █ ▄ █ █ ╱╲╱╲╱╲
█ █▀▄ █▀█ ▀▄▀▄▀ █▄▄ ╲╱╲╱╲╱
A curated, terminal-native torrent & book finder.
games · movies · tv · anime · books
╭─ Search ─────────────────────────────────────────────────────╮
│ ❯ Search, or paste a magnet or link… │
╰──────────────────────────────────────────────────────────────╯
type to search ↵ browse q quit
▀█▀ █▀▄ ▄▀▄ █ ▄ █ █ ╱╲╱╲╱╲
█ █▀▄ █▀█ ▀▄▀▄▀ █▄▄ ╲╱╲╱╲╱
────────────────────────────────────────────────────────────────────
╭─ Search ────────────────────────────────────────╮
▌ All │ ❯ oppenheimer │
Games ╰─────────────────────────────────────────────────╯
Movies
TV ╭─ Results · seeders ─────────────────────── (3) ─╮
Anime │ 3 results │
Books │ Name Size S:L Src │
Downloads │ ❯ Oppenheimer (2023)… 1.83 GB 1240:88 YTS │
│ Oppenheimer 2023 2… 14.90 GB 910:41 KNB │
│ Oppenheimer.2023.P… 1.96 GB 540:30 TPB │
╰─────────────────────────────────────────────────╯
↑↓ move · enter details · d grab · o page · y copy · q quit
- Multi-source search — built-in sources plus user-configured Torznab feeds are queried concurrently; results stream in, merge, and sort by seeders (toggle to size / newest). Failed sources can be retried without losing good results.
- aria2 engine — spawns a private
aria2cover JSON-RPC; honors your~/.aria2/aria2.conf. Magnet metadata → real download handoff handled; direct http(s) links download too. - Downloads pane — live progress (animated bar), speed, ETA, peers; pause / resume / cancel / retry; pick individual files from multi-file torrents; reveal in Finder; a persistent Recently downloaded list.
- Inspect before grabbing — a details view, open the torrent's page in your
browser, or copy its selected URI/link. Duplicate results retain source variants; use
←/→in details to cycle them. - Resume — unfinished downloads resume automatically on the next launch;
sadditionally scans the download folder for stray partial*.aria2files. - Quality of life — persistent search history, completion notifications, clipboard magnet auto-detect, mouse-wheel scrolling, a settings overlay (toggle sources, set the download dir), and confirm-on-quit.
- Single file — ships as one stdlib zipapp executable on your
PATH.
- macOS (uses
open,pbcopy/pbpaste,osascript) - aria2 (Homebrew installs it for you)
- Python 3.10+
brew tap araidz/trawl https://github.com/araidz/Trawl
brew install trawlbrew pulls in aria2 and Python automatically. Update later with brew upgrade trawl.
git clone https://github.com/araidz/Trawl.git && cd Trawl
sh build.sh # -> dist/trawl (one self-contained file)
ln -sf "$PWD/dist/trawl" /opt/homebrew/bin/trawl # or anywhere on your PATHNeeds aria2 (brew install aria2). Or run without building: python3 -m trawl.
Trawl opens to a search bar. Type and press Enter to search, press Enter on an empty box to browse the latest, or paste a magnet or direct http(s) link to grab it.
Search
| Key | Action |
|---|---|
type · Enter |
search (paste a magnet or link to grab) |
↑ ↓ |
recall past searches / scroll results |
Enter |
result details |
d |
download selected |
o |
open the torrent's page in your browser |
y copy selected URI/link · v |
grab a magnet or link from the clipboard |
S |
cycle sort (seeders / size / newest) |
r |
retry failed sources, preserving successful results |
← → filter category · c |
clear results |
s |
resume partial downloads found on disk |
g settings · ? keys · q |
quit |
Downloads (Tab to switch)
| Key | Action |
|---|---|
↑ ↓ |
move / scroll |
p |
pause / resume · x cancel (asks: delete files or keep) |
r |
retry a failed download |
f |
choose which files to download (season packs) |
o |
reveal the file in Finder |
s resume · g settings · q |
quit |
| Category | Sources |
|---|---|
| Games | FitGirl |
| Movies | YTS · The Pirate Bay · 1337x |
| TV | EZTV · SolidTorrents · The Pirate Bay · 1337x |
| Anime | Nyaa · SubsPlease · AnimeTosho |
| Books | The Pirate Bay · Nyaa (literature) · Library Genesis · Anna's Archive |
| All | Knaben (meta-aggregator) · TorrentGalaxy · Torrents-CSV |
Toggle any source on or off in the settings overlay (g). If a source is down,
the search carries on without it.
In settings (g), press a and paste a Torznab endpoint URL. You may also
enter a separate API key with k; a separate key overrides an apikey already
present in the endpoint URL. User feeds are search-only: Trawl does not request
capabilities and currently provides neither browse-latest nor pagination for
them. Feed availability and contents depend on the endpoint.
Trawl sends only the remaining search text to sources, then applies these
filters locally: seeders:, size:, source:, group:, age:, and files:.
Use -term to exclude a word and quotes for an exact phrase, for example
"special edition" -cam seeders:>10 size:<4GiB group:movies. Unknown operators
are treated as literal search text.
Trawl launches its own aria2c with JSON-RPC on loopback and drives it over
HTTP. aria2 does all the downloading; Trawl is a thin native-feeling client plus
a raw-ANSI TUI. Your ~/.aria2/aria2.conf is loaded as the base config (download
dir, connection/seed settings, resume); Trawl forces only the RPC transport and
uses a private session file so it never touches your own aria2 state.
State lives in ~/Library/Application Support/Trawl/:
history.txt (searches), downloads.jsonl (completed), config.json (settings),
aria2-session.txt (private session).
Torznab endpoint keys are masked in the UI and errors, as are metadata keys.
They are stored as plaintext in config.json, so protect that file like any
other local credential store.
Your files stay on your disk; nothing routes through a central server. Trawl only talks to the sources you search and the torrent network via aria2.
- aria2 — the download engine
- torlink — look-and-feel inspiration
- Riptide — the aria2 integration this grew from
No third-party code is used; Trawl is an independent stdlib-only implementation.