bookgrabs

BookGrabs - Interactive LibGen Book Search & Download Tool

An interactive CLI tool for searching and downloading books from LibGen with AI-powered result selection, batch processing, and a beautiful terminal interface.

Features

• Interactive Terminal UI: Beautiful React-based terminal interface using Ink
• Smart Search: Search LibGen by author, title, or general query
• AI-Powered Selection: Uses OpenAI GPT to select the best matching results
• Batch Processing: Process multiple books from CSV files with progress tracking
• Smart Blacklisting: Automatically blacklist failed downloads
• Author/Title Standardization: Normalize author names and book titles using AI
• Multiple Search Options: Fiction, non-fiction, comics, language filters
• Retry Logic: Automatically retry failed downloads with alternative results
• Real-time Progress: Live progress indicators for downloads and batch operations

Installation

Using npx (Recommended)

npx bookgrabs

Global Installation

npm install -g bookgrabs
bookgrabs

From Source

git clone <repository-url>
cd bookgrabs
npm install
npm start

Usage

Interactive Mode (Default)

Simply run the command without arguments to launch the interactive interface:

npx bookgrabs

This will open an interactive menu where you can:

• Search for individual books
• Process CSV files in batch mode
• View real-time progress and results

Command Line Mode

You can also use traditional command-line arguments:

# Search by general query
npx bookgrabs "Harry Potter"

# Search by author and title
npx bookgrabs --author "J.K. Rowling" --title "Harry Potter"

# Search fiction only
npx bookgrabs --fiction "1984"

# Search with language filter
npx bookgrabs --language fra "Harry Potter"

# Process books from CSV file
npx bookgrabs --csv books.csv

Configuration

OpenAI API Key Setup

BookGrabs will automatically prompt you to enter your OpenAI API key on first run. If you don't have one or want to skip this step, you can:

• Use the built-in setup: Run npx bookgrabs and follow the prompts
• Configure later: Use the Settings menu to add your API key anytime
• Manual setup: Create a .env file in your working directory:

  OPEN_AI_KEY=your_openai_api_key_here
  

Get your API key from: https://platform.openai.com/api-keys

Note: AI features (intelligent result selection, title standardization, retry logic) require an OpenAI API key. Without it, BookGrabs will use basic search result selection.

CSV Batch Processing

For batch processing, create a CSV file with the following format:

author,title,year
J.K. Rowling,Harry Potter and the Philosopher's Stone,1997
George Orwell,1984,1949
Isaac Asimov,Foundation,1951

Then either:

• Use the interactive interface (Menu → Batch Processing)
• Use command line: npx bookgrabs --csv books.csv

Command Line Options

• --author, -a: Specify author name
• --title, -t: Specify book title
• --csv, -c: Process books from CSV file
• --fiction: Search fiction only
• --nonfiction: Search non-fiction only
• --comics: Search comics only
• --all-topics: Search all topics
• --results, -r: Maximum number of results (default: 25)
• --language, -l: Language filter (3-letter code, e.g., eng, fra, deu)
• --english: Search English books only (default)
• --any-language: Search all languages

Project Structure

bookGrabs/
├── bin/
│   └── bookgrabs.js      # CLI executable
├── src/
│   ├── components/       # React/Ink UI components
│   │   ├── MainMenu.tsx
│   │   ├── SearchScreen.tsx
│   │   ├── BatchScreen.tsx
│   │   └── ...
│   ├── ai.js             # OpenAI integration
│   ├── blacklist.js      # Blacklist management
│   ├── config.js         # Command line argument parsing
│   ├── csv.js            # CSV processing and batch operations
│   ├── download.js       # Book downloading functionality
│   ├── search.js         # LibGen search functionality
│   └── utils.js          # Utility functions
├── index.tsx             # Interactive React/Ink interface
├── index.js              # Traditional CLI interface
├── books/                # Downloaded books directory
├── .blacklist            # Blacklisted download hashes
└── package.json

Key Features

Interactive Interface

• Menu Navigation: Easy-to-use menu system
• Real-time Search: Live search results with progress indicators
• Batch Processing UI: Visual progress tracking for CSV processing
• Settings Management: Built-in OpenAI API key configuration and testing
• First-Run Setup: Automatic API key prompt for new users
• Error Handling: Graceful error handling with retry options

AI Integration

• Smart Selection: AI analyzes search results to find the best matches
• Title Standardization: Automatically standardizes author names and titles
• Retry Logic: AI-powered retry with alternative results on failures

Batch Processing

• CSV Import: Process hundreds of books from CSV files
• Progress Tracking: Real-time progress with success/failure counts
• Detailed Logging: Comprehensive logs for debugging and monitoring
• Resume Support: Graceful handling of interruptions

Requirements

• Node.js 18+ (ES modules support)
• OpenAI API key (optional, for AI features)

Output

• Downloaded books are saved to ~/BookGrabs/author_name/ directories in your home folder
• CSV reports are generated for batch processing in your current working directory
• Detailed logs are created for batch operations in your current working directory
• Blacklisted downloads are tracked in .blacklist file in your current working directory

Note: Books are now stored in a dedicated BookGrabs folder in your home directory, making them easy to find regardless of where you run the command.

For Existing Users

If you previously used BookGrabs, your books may be in a local books/ folder where you ran the command. You can move them to the new location:

# Move existing books to the new location
mv books/* ~/BookGrabs/

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.