littlejohn

Native terminal UI for torrent search with Real-Debrid integration, written in Rust.

Features

• Fast, native terminal interface built with ratatui
• Search multiple torrent sites in parallel (standalone, no backend required)
• Real-Debrid integration for premium downloads
• File picker for multi-file torrents
• Built-in download manager with progress tracking
• Vim-style keybindings (j/k navigation)

Installation

cargo install littlejohn

Nix

Run directly without installing:

nix run github:mat-lo/littlejohn

Or install to your profile:

nix profile install github:mat-lo/littlejohn

For development, enter a shell with all dependencies:

nix develop

Building from Source

cargo build --release

The binary will be at target/release/littlejohn.

Configuration

Create a .env file with your settings. The app checks these locations (in order):

1. .env in the current directory
2. Config directory:
   • Linux: ~/.config/littlejohn/.env
   • macOS: ~/Library/Application Support/littlejohn/.env
   • Windows: %APPDATA%\littlejohn\.env

Real-Debrid API Token (Required)

RD_API_TOKEN=your_token_here

Get your token from: https://real-debrid.com/apitoken

Download Directory

Optionally set a custom download directory:

DOWNLOAD_DIR=/path/to/downloads

If not set, files are saved to your system's default Downloads folder.

Firecrawl (Optional)

Some sites (Il Corsaro Nero, YTS) use anti-bot protection. Firecrawl helps bypass this:

FIRECRAWL_API_KEY=your_key_here

Get your key from: https://firecrawl.dev

Without this, Il Corsaro Nero won't work and YTS may be less reliable.

First-Run Setup

On first run, if no Real-Debrid token is configured, the app will show a setup wizard where you can enter your settings. You can also access settings anytime by pressing Shift+S from the search screen.

Usage

cargo run --release

Or run the built binary directly:

./target/release/littlejohn

Keybindings

Search Screen

Results Screen

File Select Screen

Downloads Screen

Supported Sites

• 1337x
• The Pirate Bay (TPB)
• BitSearch
• YTS
• Il Corsaro Nero

Dependencies

• ratatui - Terminal UI framework
• tokio - Async runtime
• reqwest - HTTP client
• scraper - HTML parsing

Architecture

src/
├── main.rs         # Application state, event loop, async messaging
├── ui.rs           # Terminal UI rendering (ratatui)
├── realdebrid.rs   # Real-Debrid API client
├── lib.rs          # Shared types and utilities
└── scrapers/       # Site-specific scrapers
    ├── mod.rs      # Scraper registry and common types
    ├── x1337.rs    # 1337x scraper
    ├── tpb.rs      # TPB scraper
    ├── bitsearch.rs
    ├── yts.rs
    └── ilcorsaronero.rs

The app uses an async message-passing architecture:

• Main loop handles keyboard events and renders UI
• Background tasks handle scraping and API calls
• Messages are sent back via tokio channels