nexxeln / torrential

torrential 
 Search and download torrents from your terminal, or ask your coding agent to. 
## Install
 [code] 
This puts one file at `~/.local/bin/torrential`. It runs on macOS 14 or later on Apple silicon, and on 64-bit Linux on Intel or AMD.
### Build from source
On other machines, build it with Rust and Nix, with flakes turned on:
 [code] 
## Use it
Run `torrential` with no arguments to open the terminal UI. Search, pick the files you want, and watch the download fill in as its pieces arrive.
Or run the commands yourself:
 [code] 
An ID is the start of the torrent's infohash, and any unique prefix of 4 or more characters works. `get` also takes a magnet link, a full infohash, or a `.torrent` file or URL.
On a terminal, `get` shows progress until the download is done. Downloads run in a background engine, so they keep going after you press Ctrl-C or close the terminal.
Every command takes `--json` for scripts, and `torrential schema` describes the commands, their flags, and their errors.
## Ranked for your machine
torrential reads your screen, CPU, and language, and ranks releases to fit them: 1080p on a laptop, arm64 builds on Apple silicon, and your language first. `torrential setup` shows what it found. If you watch on another screen, say so once:
 [code] 
In the terminal UI, press `S` to change it.
## With your agent
Install the skill that teaches agents to use torrential:
 [code] 
It installs the skill for Claude Code, and for Codex, Gemini CLI, Cursor, and other agents that read `~/.agents/skills`. Then ask for what you want in plain words. Here is what a fresh Claude Code session ran for this request:
 [code] 
It chose the public-domain original over the 55 GiB remux, picked one 1.8 GiB MP4 out of five files, and checked back with `wait` instead of `sleep`. The download does not depend on the agent, so a later session can check on it with `torrential status`.
Agent sandboxes block the connections BitTorrent needs. torrential checks for a sandbox before it starts, and the skill tells the agent what to do about it.
## Settings
torrential reads `~/.config/torrential/config.yaml`. Downloads go to a `torrential` folder in your Downloads folder unless you set another:
 [code] 
torrential looks for a new version once a day, says when one is out, and `torrential update` installs it. Set `updates: auto` to install new versions in the background, or `updates: off` to stop looking.
## It never seeds
torrential never uploads a piece, and a download stops as soon as it finishes. Among equally good matches it puts lawful sources such as archive.org and official Linux torrents first, and you should download only what you have the right to.
## License
MIT. See LICENSE.