bittorentstats-cli - BitTorrent Tracker Client (CLI)

bittorentstats-cli is a command-line interface (CLI) tool for interacting with BitTorrent UDP trackers. It allows you to announce torrents to a tracker to discover peers and scrape tracker information to get statistics about torrents (completed, leechers, seeders).

Warning

In some countries, if you use this code to obtain information on a torrent that has been declared “illegal”, you could be prosecuted and face sanctions. The server's IP address will be revealed to the tracker and other peers.

Features

• Announce: Announce an infohash to a UDP tracker and retrieve a list of active peers.
• Scrape: Scrape one or more infohashes from a UDP tracker to get torrent statistics (seeders, completed, leechers).
• Flexible Output: Get results in human-readable text format or machine-readable JSON.
• Peer IP Enrichment (Announce JSON output): When using JSON output for the announce command, bittorentstats-cli attempts to enrich peer IP addresses with Autonomous System (AS), Internet Service Provider (ISP), and Organization details using the ip-api.com service (rate-limited to the first 40 peers here).

To-Do

• API serve mode
• Rewriting in Rust
• MIT permissive license (requires code rewriting first)
• Other ? Open to issues and PR (very active and fast, don't hesitate)

Installation

go install github.com/r3m8/bittorentstats-cli@latest

Build from source

git clone https://github.com/r3m8/btshow.git
cd btshow
go build .

Usage

Global Options

• --udp-tracker-host or -u: Specifies the UDP tracker host and port. Default is tracker.torrent.eu.org:451.

bittorentstats-cli announce

Announces an infohash to a tracker and lists the peers.

Syntax

bittorentstats-cli announce [flags] <infohash>

Arguments

• <infohash>: The 40-character hexadecimal representation of the torrent's infohash.

Flags

• --port or -p: The port to announce to the tracker (default: 6881).
• --output or -o: Output format (text or json, default: text).

Examples

Announce an infohash and display peers in text format:

bittorentstats-cli announce 00112233445566778899AABBCCDDEEFF00112233

Announce an infohash and display peers in JSON format with IP enrichment:

bittorentstats-cli announce -o json 00112233445566778899AABBCCDDEEFF00112233

Announce to a specific tracker:

bittorentstats-cli announce -u tracker.example.com:8000 00112233445566778899AABBCCDDEEFF00112233

Output example (only one peer for the demo):

{
  "infohash": "00112233445566778899AABBCCDDEEFF00112233",
  "peers": [
    {
      "ip": "1.2.3.4",
      "port": 12345,
      "as": "AS12345 Example AS",
      "isp": "Example AS",
      "org": "Example A.S"
    }
  ]
}

bittorentstats-cli scrape

Scrapes one or more infohashes from a tracker to get statistics (completed, leechers, seeders).

Syntax

bittorentstats-cli scrape [flags] <infohash1> [infohash2 ...]

Arguments

• <infohash1> [infohash2 ...]: One or more 40-character hexadecimal representations of torrent infohashes.

Flags

• --output or -o: Output format (text or json, default: text).

Examples

Scrape a single infohash:

bittorentstats-cli scrape 00112233445566778899AABBCCDDEEFF00112233

Scrape multiple infohashes and display in JSON format:

bittorentstats-cli scrape -o json 00112233445566778899AABBCCDDEEFF00112233 AABBCCDDEEFF00112233445566778899

Scrape from a specific tracker:

bittorentstats-cli scrape -u tracker.example.com:8000 00112233445566778899AABBCCDDEEFF00112233

Output example:

[
  {
    "infohash": "00112233445566778899AABBCCDDEEFF00112233",
    "completed": 37,
    "leechers": 2,
    "seeders": 26
  }
]

Development

The core logic for interacting with UDP trackers is located in pkg/tracker.go. This package handles the UDP connection, the BitTorrent UDP tracker protocol (connect, announce, scrape actions), and parsing of responses. The cmd package defines the CLI commands using the cobra library.

This project is forked from btshow, and thus inherits the AGPL 3.0 license (I would have liked a permissive license, seriously, don't impose copyleft on these small projects.). This code has been extensively modified to resolve errors and add functionnalities like announce.

If for internal internal purposes this code needs to be modified, or changed to a permissive version like MIT, please contact me.