torrra 1.1.2

A Python tool that lets you find and download torrents without leaving your CLI.

torrra

A Python tool that lets you find and download torrents without leaving your CLI.

Overview

torrra provides a streamlined command-line interface for your torrent needs. It allows you to search for and download torrents, and manage active downloads without leaving your terminal, offering a fast and efficient solution for command-line users.

Table of Contents

• Features
• Installation
  • Cross-Platform
  • Arch Linux
  • Standalone Binaries
  • Docker
  • Local Development
• Usage
  • CLI Commands & Flags
  • TUI Controls
• Configuration
  • Managing Your Configuration
  • Config Options
• Indexer Support
• Roadmap
• Contributing
• License

Features

• Integrate with services like Jackett and Prowlarr.
• Fetch and download magnet links directly, powered by Libtorrent.
• A responsive download manager built with Textual.
• Pause and resume torrent downloads using keyboard shortcuts.
• Operates as both a CLI tool and a full-screen terminal UI.
• Toggle between dark and light themes.

Installation

torrra offers several installation methods to suit your environment.

Cross-Platform (recommended)

Using pipx ensures torrra is installed in an isolated environment, preventing conflicts with your system's Python packages.

pipx install torrra

This method supports Linux, macOS, and Windows. libtorrent is installed automatically via pip.

Arch Linux

1. From AUR (builds from source):

yay -S torrra

2. From AUR Binary Package (faster installation):

yay -S torrra-bin

torrra-bin includes a precompiled standalone binary for x86_64 Linux, requiring no Python dependencies.

Standalone Binaries (No Python Required)

Download pre-built executables directly from GitHub Releases:

OS	File
Linux	torrra-vX.Y.Z-linux-x86_64
Windows	torrra-vX.Y.Z-windows.exe
macOS	torrra-vX.Y.Z-macos-x86_64

On Linux/macOS, ensure the binary is executable: chmod +x torrra-vX.Y.Z-*-x86_64.

Docker

torrra is also available as a Docker image, allowing you to run it in an isolated environment without installing Python dependencies directly on your host system.

The official image is hosted on Docker Hub: stabldev/torrra.

Quick Usage

docker run --rm -it stabldev/torrra:latest --jackett

Replace --jackett with your preferred provider flag. You can also pass URL and API key directly: --jackett http://localhost:9117 your_api_key. You must mount any required config or download directories if needed.

With Config and Downloads Folder Mounted

docker run --rm -it \
  -v ~/.config/torrra:/root/.config/torrra \
  -v ~/Downloads:/downloads \
  stabldev/torrra:latest --jackett

Ensure your config.toml inside ~/.config/torrra is set up correctly.

Image Tags

• stabldev/torrra:latest - always points to the latest release
• stabldev/torrra:<version> - for a specific release (e.g., x.y.z)

Local Development

To set up torrra for development:

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

Usage

To start torrra, you must specify a provider. For example, to use Jackett:

torrra --jackett

Uses Jackett with credentials from your saved configuration.

Or pass your own URL and API_KEY directly. For example, to use Prowlarr:

torrra --prowlarr http://localhost:9696 your_api_key

Omitting a provider flag will result in an error.

CLI Commands & Flags

Top-level commands

Command	Description
torrra	Launches the interactive TUI
torrra config	Manages configuration settings
torrra --help	Displays help for the top-level CLI commands

Provider flags (used with torrra)

Flag	Description
-h, --help	Displays help for the main application
-v, --version	Shows the current torrra version
-j, --jackett	Uses Jackett as the torrent indexer. Optionally accepts URL and API_KEY.
-p, --prowlarr	Uses Prowlarr as the torrent indexer. Optionally accepts URL and API_KEY.

TUI Controls

Key	Action
↑↓	Navigate through results
Tab	Focus the next widget
Enter	Start download for selection
p	Pause the current download
r	Resume a paused download
q	Quit torrra

Configuration

torrra's behavior can be customized via a config.toml file located in your OS-specific user config directory:

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

The actual path is automatically resolved using platformdirs.

Example config.toml:

[general]
download_path = "/home/username/Downloads"   # Default folder for saving torrents
remember_last_path = true                    # Reuse the last used path as default

Managing Your Configuration

Use the built-in torrra config command to manage settings:

torrra config -g general.download_path             # Get a specific config value
torrra config -s general.remember_last_path False  # Set a key-value pair
torrra config -l                                   # List all config settings

Config Options

Flag	Description
-g, --get KEY	Retrieves a config value (e.g., general.download_path)
-s, --set KEY VALUE	Sets a key-value pair
-l, --list	Lists all configuration settings
-h, --help	Displays help for the config command

Indexer Support

Currently supported:

• Jackett (via --jackett or -j)
• Prowlarr (via --prowlarr or -p)

Planned:

• Support for custom indexers

Roadmap

Ongoing development focuses on enhancing torrra's capabilities:

• Jackett integration
• Prowlarr support
• Torrent download UI with pause/resume
• Config file support
• Standalone binary & AUR packaging
• Magnet info preview (seeders/leechers before download)
• Advanced filtering/sorting
• Nyaa & anime-specific indexers
• Keyboard shortcuts overlay / help screen

Contributing

torrra is an open-source project, and contributions are highly valued.

• If you find an issue, please open an issue with detailed steps to reproduce.
• We welcome new features or indexer integrations. Fork the repository and submit a Pull Request.
• General feedback and feature requests are always appreciated.

License

MIT License. Copyright (c) stabldev