bookdl

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 15 Open GitHub ↗

CLI tool for searching and downloading books from Anna's Archive

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# bookdl

A command-line tool for searching and downloading books from multiple sources: Anna's Archive, Z-Library, and Liber3.

## Features

- **Multi-Source Search**: Search across Anna's Archive, Z-Library, and Liber3 simultaneously or individually
- **Interactive Search**: Search for books with an interactive TUI selector
- **Resumable Downloads**: Pause and resume downloads with chunk-based progress tracking
- **Multiple Access Methods**: Supports API access and web scraping with Cloudflare bypass
- **Download Management**: Track, pause, resume, and restart downloads
- **Format Filtering**: Filter search results by format (EPUB, PDF, etc.)
- **Pagination**: Load more results if you don't find what you're looking for

## Installation

**📖 For detailed installation instructions, see [INSTALL.md](INSTALL.md)**

### Quick Install (Recommended)

**macOS:**
```bash
curl -fsSL https://raw.githubusercontent.com/billmal071/bookdl/main/scripts/install-mac.sh | bash
```

**Linux:**
```bash
curl -fsSL https://raw.githubusercontent.com/billmal071/bookdl/main/scripts/install-linux.sh | bash
```

**Windows (PowerShell):**
```powershell
iwr -useb https://raw.githubusercontent.com/billmal071/bookdl/main/scripts/install-windows.ps1 | iex
```

### Download Binary

Download the latest release for your platform from the [Releases page](https://github.com/billmal071/bookdl/releases/latest):

- **macOS (Intel):** `bookdl-darwin-amd64`
- **macOS (Apple Silicon):** `bookdl-darwin-arm64`
- **Linux (x86_64):** `bookdl-linux-amd64`
- **Linux (ARM64):** `bookdl-linux-arm64`
- **Windows:** `bookdl-windows-amd64.exe`

After downloading:
1. Make the binary executable (macOS/Linux): `chmod +x bookdl-*`
2. Move it to a directory in your PATH: `sudo mv bookdl-* /usr/local/bin/bookdl`

### Homebrew (macOS/Linux)

```bash
brew tap billmal071/bookdl
brew install bookdl
```

### From Source

```bash
# Clone the repository
git clone https://github.com/billmal071/bookdl.git
cd bookdl

# Build
make build

# Or install to GOPATH/bin
make install
```

### Requirements

- Go 1.21 or later (for building from source only)
- Chrome/Chromium (for Cloudflare bypass, optional)

## Usage

### Search for Books

```bash
# Basic search (searches all sources by default)
bookdl search "clean code"

# Search a specific source
bookdl search --source zlibrary "clean code"
bookdl search --source anna "clean code"
bookdl search --source liber3 "clean code"

# Search all sources explicitly
bookdl search --source all "clean code"

# Search with format filter
bookdl search -f epub "design patterns"

# Filter by language
bookdl search -l english "machine learning"

# Filter by year or year range
bookdl search --year 2020 "python"
bookdl search --year 2020-2024 "algorithms"

# Filter by maximum file size
bookdl search --max-size 10MB "data science"

# Combine filters
bookdl search -f pdf -l english --year 2020-2024 "deep learning"

# Limit number of results
bookdl search -n 10 "golang programming"

# Search and immediately download
bookdl search -d "pragmatic programmer"

# Non-interactive mode (print results and exit)
bookdl search --no-interactive "pragmatic programmer"
```

In the interactive selector:
- `↑/↓` - Navigate through results
- `Enter` - Select a book
- `i` - Show book details
- `o` - Open book page in browser (when details visible)
- `m` - Load more results
- `q/Esc` - Cancel

### Queue Multiple Books

Use `-q` flag for multi-select mode to queue multiple books:

```bash
# Search and select multiple books to queue
bookdl search -q "programming"
```

In multi-select mode:
- `Space` - Toggle selection
- `a` - Select all
- `n` - Deselect all
- `Enter` - Confirm and add to queue

### Manage Queue

```bash
# View download queue
bookdl queue

# Clear all pending downloads
bookdl queue clear

# Remove specific items from queue
bookdl queue remove 1 2 3
```

### Download a Book

```bash
# Download by MD5 hash
bookdl download abc123def456789...

# Specify output directory
bookdl download -o ~/Books abc123def456789...
```

### Manage Downloads

```bash
# List all downloads
bookdl list

# List only active downloads
bookdl list --active

# Pause a download
bookdl pause 1

# Pause all downloads
bookdl pause all

# Resume a download
bookdl resume 1

# Resume all paused downloads
bookdl resume all

# Restart a failed download
bookdl restart 1
```

### Verify Downloads

```bash
# Verify a specific download
bookdl verify 1

# Verify all completed downloads
bookdl verify --all

# Verify and automatically re-download corrupted files
bookdl verify --all --fix

# Re-verify downloads that failed verification
bookdl verify --failed
```

### Manage Cache

```bash
# View cache statistics
bookdl cache stats

# Clear all cached search results
bookdl cache clear

# Clean expired cache entries
bookdl cache clean

# Enable/disable caching
bookdl cache enable
bookdl cache disable
```

### Shell Completions

```bash
# Generate completions for your shell
bookdl completion bash   # Bash
bookdl completion zsh    # Zsh
bookdl completion fish   # Fish
bookdl completion powershell  # PowerShell

# Install bash completions
bookdl completion bash > /etc/bash_completion.d/bookdl

# Install zsh completions
bookdl completion zsh > "${fpath[1]}/_bookdl"
```

### Configuration

```bash
# Show config file path
bookdl config path

# Get a config value
bookdl config get downloads.path

# Set a config value
bookdl config set downloads.path ~/Books
```

Configuration file location: `~/.config/bookdl/config.yaml`

```yaml
anna:
  base_url: "annas-archive.gl"
  api_key: ""  # Optional API key for faster access

zlibrary:
  base_url: "z-library.sk"

liber3:
  base_url: "liber3.eth.limo"

downloads:
  path: "~/Downloads/books"
  max_concurrent: 2  # Number of simultaneous downloads
  chunk_size: 5242880  # 5MB chunks
  timeout: 30m  # Maximum download timeout
  auto_resume: true
  notifications: false  # Enable desktop notifications

browser:
  page_load_timeout: 60s  # Timeout for initial page load
  max_countdown_wait: 90s  # Max time to wait for download countdown
  poll_interval: 3s  # How often to check for download link
  verbose_logging: false  # Enable detailed browser logging

cache:
  enabled: true  # Enable search result caching
  ttl: 24h  # Time-to-live for cached results
```

Environment variables can override config values with the `BOOKDL_` prefix:
```bash
export BOOKDL_DOWNLOADS_PATH=~/Books
export BOOKDL_ANNA_API_KEY=your-api-key
```

## How It Works

1. **Search**: Queries configured sources (Anna's Archive, Z-Library, Liber3) for books matching your search
2. **Selection**: Presents results in an interactive terminal UI, grouped by source
3. **Download**: Fetches the book using available mirrors with automatic fallback
4. **Resumable**: Downloads are split into chunks and tracked in a local SQLite database

When Cloudflare protection is detected, bookdl automatically falls back to a headless browser to bypass the challenge. Z-Library uses client-side rendering via Web Components, so the browser is always used for Z-Library searches.

## Troubleshooting

### Download Stuck on "Resolving download link"

If a download gets stuck while resolving the download link (especially with slow_download URLs):

1. **Increase browser timeout** - Some mirrors have long countdown timers:
   ```bash
   bookdl config set browser.max_countdown_wait 120s
   ```

2. **Enable verbose logging** to see what's happening:
   ```bash
   bookdl config set browser.verbose_logging true
   ```

3. **Try again** - The stuck download was automatically terminated. You can restart it:
   ```bash
   bookdl download <md5-hash>
   ```

### Progress Feedback

The improved browser resolution now shows:
- "Waiting for download link (max 90s)..." when starting
- Progress updates every 15 seconds during countdown
- "Download link found after Xs" when successful
- Clear timeout messages if the limit is exceeded

## Project Structure

```
bookdl/
├── cmd/bookdl/          # Entry point
├── internal/
│   ├── anna/            # Anna's Archive client (API, scraper, browser)
│   ├── zlibrary/        # Z-Library client (scraper, browser with Web Components)
│   ├── liber3/          # Liber3 client (scraper, browser)
│   ├── search/          # Multi-source search orchestrator
│   ├── cli/             # CLI commands
│   ├── config/          # Configuration management
│   ├── db/              # SQLite database layer
│   ├── downloader/      # Download manager
│   ├── notify/          # Desktop notifications
│   └── tui/             # Terminal UI components
├── build/               # Build output
├── Makefile             # Build automation
└── IMPROVEMENTS.md      # Planned features
```

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide, and [IMPROVEMENTS.md](IMPROVEMENTS.md) for planned features and ideas.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Disclaimer

This tool is for educational and personal use only. Please respect copyright laws and the terms of service of the sources accessed. The authors are not responsible for any misuse of this software.

bookdl

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README