Clover

Clover (🍀) is a lightweight, fast, leech-only torrent client written in Go. It implements the core BitTorrent protocol to download torrents directly from the terminal.

Features

• Torrent parsing - Implements an encoder and decoder for parsing bencode encoded .torrent files.
• Dual peer discovery - Finds peers via both UDP trackers and the DHT network, merging them into a single stream.
• Concurrent downloads - Manages multiple peer connections to download pieces simultaneously.
• Session management - Supports resuming and deleting stopped downloads.
• Clean CLI stats - Real-time stats showing a progress bar, percentage completed, pieces downloaded, active peer count, and time elapsed.

Getting Started

Prerequisites

• Go

Installation

1. Install Pre-compiled Binary

You can install the latest pre-compiled binary of Clover automatically.

Linux & macOS

Run the following command in your terminal to download and run the installer:

curl -fsSL https://raw.githubusercontent.com/JoelVCrasta/clover/main/scripts/install.sh | sh

Note: By default, this installs the binary to /usr/local/bin. If write permission is denied, it will prompt for sudo. To install to a different directory, download the script and specify BIN_DIR, for example:

curl -fsSL https://raw.githubusercontent.com/JoelVCrasta/clover/main/scripts/install.sh -o install.sh
chmod +x install.sh
BIN_DIR=$HOME/.local/bin ./install.sh

Windows

Run the following command in PowerShell:

irm https://raw.githubusercontent.com/JoelVCrasta/clover/main/scripts/install.ps1 | iex

Note: This downloads clover.exe to $HOME\.clover\bin and appends it to your User PATH environment variable. You will need to restart your terminal after installation.

2. Build from Source

If you have Go installed and want to build the executable from source:

git clone https://github.com/JoelVCrasta/clover.git
cd clover
go build ./cmd/clover

Usage & Commands

1. Download a Torrent

To download a torrent, use the download subcommand. The --input (-i) flag is required.

# Using go run:
go run ./cmd/clover/main.go download -i <path-to-torrent-file> -o <output-directory>

# Using the built binary:
clover download -i <path-to-torrent-file> -o <output-directory>

If the output flag is not provided, then it will download to the ~/Downloads directory.

Examples:

# Download to a specific directory
clover download -i ~/downloads/ubuntu.torrent -o ~/downloads/

# Download to the default ~/Downloads directory
clover download -i ~/downloads/ubuntu.torrent

2. List Paused Downloads

To see the list of paused downloads:

clover list

3. Resume a Download

To resume a paused download by its index (from the list command):

clover resume <index>

4. Delete a Download Session

To delete a download session by its index (from the list command):

clover delete <index>

Project Structure

.
├── client
│   ├── bitfield.go
│   └── client.go
├── cmd
│   ├── clover
│   │   └── main.go
│   └── example
│       └── main.go
├── config
│   └── config.go
├── dht
│   └── dht.go
├── download
│   ├── download.go
│   ├── state.go
│   └── save.go
├── handshake
│   └── handshake.go
├── message
│   └── message.go
├── metainfo
│   ├── decode.go
│   ├── encode.go
│   ├── hash.go
│   └── torrentfile.go
├── peer
│   ├── peer.go
│   └── peer_id.go
├─── tracker
│   ├── scrape.go
│   ├── tracker.go
│   └── tracker_test.go
├── torrent.go
├── discover_peers.go
├── go.mod
└── go.sum