littlejohn 0.4.0

Terminal UI for littlejohn torrent search with Real-Debrid integration
Documentation

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

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

Key Action
Enter Search / Process magnet link
s Select sources
S Open settings
d View downloads
Esc Quit

Results Screen

Key Action
j / Down Move down
k / Up Move up
Enter Select torrent
n Next page
p Previous page
s Select sources
d View downloads
/ Back to search
q Quit

File Select Screen

Key Action
j / Down Move down
k / Up Move up
Space Toggle file selection
a Toggle all files
Enter Confirm selection
Esc Cancel

Downloads Screen

Key Action
j / Down Move down
k / Up Move up
s Start selected download
S Start all downloads
c Cancel selected
C Cancel all
x Clear completed
Esc Back

Supported Sites

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

Dependencies

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