torrra

Torrra is a Python-based CLI tool designed for finding and downloading torrents directly from the terminal.

Key capabilities include:

• Indexer Integration: Works with services like Jackett and Prowlarr.
• Torrent Management: Fetches and downloads magnet links using Libtorrent.
• Terminal UI: Features a responsive download manager built with Textual, supporting keyboard shortcuts to pause/resume downloads and theme toggling (dark/light).
• Search Modes: Supports both direct command-line searches and an interactive full-screen UI.
• Performance: Includes opt-in caching for faster repeated searches.

Torrra uses external torrent indexer proxies to aggregate search results from various trackers. Currently, it supports the following indexer proxies:

• Jackett: A proxy server that translates queries into tracker-specific HTTP requests and parses HTML responses.
• Prowlarr: An indexer manager and proxy for Usenet and Torrent trackers.

Future support is planned for custom indexers and anime-specific indexers like Nyaa.

The config.toml file is automatically created in your operating system's standard user configuration directory.

• Linux/macOS: ~/.config/torrra/config.toml
• Windows: %APPDATA%\torrra\config.toml

torrra uses the platformdirs Python library to resolve these paths automatically.

To contribute to torrra or run it directly from source, clone the repository and use uv (recommended) or pip to set up the environment.

git clone https://github.com/stabldev/torrra
cd torrra
uv sync # or `pip install -e .`
uv run torrra

You can bypass the initial welcome screen and perform searches immediately using the search command. This is useful for quick lookups without entering the TUI first.

Use the --no-cache flag if you want to ensure the search results are fresh and not retrieved from the local cache.

torrra search "arch linux iso"
# or with no cache
torrra search "ubuntu iso" --no-cache

To use Torrra, you must first initialize it with a torrent indexer. You can use either Jackett or Prowlarr by providing the instance URL and your API key via the CLI.

Using Jackett

Run the following command with your Jackett instance URL and API key:

torrra jackett --url http://localhost:9117 --api-key <your_jackett_api_key>

Using Prowlarr

Run the following command with your Prowlarr instance URL and API key:

torrra prowlarr --url http://localhost:9696 --api-key <your_prowlarr_api_key>

Note: For Prowlarr, ensure that the "Prefer Magnet URL" option is enabled in your Prowlarr settings to ensure optimal compatibility.

Themes can be changed by editing the theme key in the [general] section of config.toml or via the CLI.

Available themes:

• catppuccin-latte
• catppuccin-mocha
• dracula
• flexoki
• gruvbox
• monokai
• nord
• solarized-light
• textual-ansi
• textual-dark (default)
• textual-light
• tokyo-night

Via CLI:

torrra config set general.theme gruvbox

You can install Torrra using pipx or uv. Other installation methods include AUR, standalone binaries, Homebrew, or Docker.

pipx install torrra
# or
uv tool install torrra

macOS users can install the precompiled binary version of torrra using Homebrew, which avoids the need for Python or additional setup.

brew tap Maniacsan/homebrew-torrra
brew install torrra

The official Docker image is stabldev/torrra. You can run it for quick tasks or mount volumes for persistent configuration and downloads.

Quick Usage

Run an indexer (e.g., jackett) without persistent configuration:

docker run --rm -it stabldev/torrra:latest jackett --url <url> --api-key <api_key>

Persistent Configuration and Downloads

To persist your config.toml and download files, mount your local directories into the container. Note that if you mount a download directory, your config.toml's download_path must point to the path inside the container (e.g., /downloads).

docker run --rm -it \
  -v ~/.config/torrra:/root/.config/torrra \
  -v /path/to/your/downloads:/root/Downloads \
  stabldev/torrra:latest jackett --url <url> --api-key <api_key>

Once the application is running, use these keyboard shortcuts to interact with the Text-User Interface (TUI):

Navigation

• ↑ / k: Navigate up through search results
• ↓ / j: Navigate down through search results
• ctrl+u: Page up
• ctrl+d: Page down
• G: Scroll to the bottom
• gg: Scroll to the top (press g twice)
• Tab: Move focus to the next interactive widget

Actions

• Enter / l: Initiate download for selected torrent
• ctrl+t: Open theme switcher
• p: Pause active download
• r: Resume paused download
• q: Quit Torrra

You can run torrra directly using a Nix flake without installing it, or add it to your NixOS configuration if you have flakes enabled.

# Run directly without installing
nix run github:stabldev/torrra

# In flake.nix inputs:
torrra.url = "github:stabldev/torrra";

# In your NixOS configuration:
environment.systemPackages = [ inputs.torrra.packages.${pkgs.system}.default ];