tgdl-bot

An all-in-one Telegram media & file downloader, archive extractor, cloud storage mirror, and torrent manager. Powered by gallery-dl, aria2c, Google Drive API, and Pyrogram to support up to 2GB uploads per file with real-time status management.

---

Documentation Index

This project uses modular sub-documentation files located in the docs/ directory:

• Direct & Gallery Downloader Reference

  • Direct HTTP/HTTPS downloads (/dl, /direct).
  • Gallery-dl media extraction from 100+ sites (/gdl, /gallerydl).
  • Server mirroring (/m, /mirror).
  • Command flags (-m, -tg, -uz, -p <password>) and batch .txt link file processing.

• Torrent Downloads & Search Engine

  • Headless torrent and magnet downloading (/tor).
  • Interactive multi-provider Torrent Search Engine (/ts, /torsearch, /search).

• Archive Extraction & Volume Splitting

  • Single archive decompression (/unzip [password]).
  • Split archive collector sessions (/unzip split).
  • Multi-archive batch extractions (/unzip multi).
  • Interactive password prompts and Telegram 2GB upload limit safeguards.

• Cloud Storage & Google Drive Integration

  • Google Drive folder and file downloader (/gd2tg).
  • Google Drive authentication guide (Service Accounts & OAuth tokens).
  • External cloud host uploaders: Pixeldrain (/pdup), GoFile (/gfup), FileDitch (/fdup).

• Custom Configuration, Cookies & Task Controls

  • Per-user gallery-dl.conf and cookies.txt manager (/gdlconf).
  • Live task monitor, queue dashboard, and speed metrics (/status).
  • Job cancellation (/cancel [job_id]).

• Installation & System Requirements

  • System prerequisites (FFmpeg, aria2, archive utilities).
  • Local virtual environment setup and configuration.
  • Docker deployment using docker-compose.

---

Quick Reference Overview

Core Commands

Command	Aliases	Description	Sub-Documentation
/dl [flags] <url>	/direct	Download direct HTTP/HTTPS URLs.	Downloaders
/gdl [flags] <url>	/gallerydl	Download albums/posts via gallery-dl.	Downloaders
/mega [flags] <url>	/meganz	Download files & folders from mega.nz / mega.co.nz / mega.io.	Downloaders
/mega -login <email:pass>	/mega -logout, /mega -account	Manage personal MEGA account credentials.	Cloud & Drive
/m [flags] <url>	/mirror	Mirror links/files to server.	Downloaders
/tor <magnet/url>	—	Download torrent magnet or .torrent file.	Torrents
/ts <query>	/torsearch, /search	Search torrents with inline pagination.	Torrents
/unzip [password]	—	Extract archive files.	Archives
/unzip split	—	Multi-part split archive collector session.	Archives
/unzip multi	—	Multi-archive batch extraction session.	Archives
/gd2tg <gdrive_link>	—	Download Google Drive link to Telegram.	Cloud & Drive
/pdup	—	Upload replied media to Pixeldrain.	Cloud & Drive
/gfup	/gofile	Upload replied media to GoFile.	Cloud & Drive
/fdup	/fileditch	Upload replied media to FileDitch.	Cloud & Drive
/gofilekey <token>	/gofile_key	Manage personal GoFile API key.	Cloud & Drive
/pdkey <key>	/pixeldrainkey	Manage personal Pixeldrain API key.	Cloud & Drive
/gdlconf	/gdl_config	Manage custom gallery-dl config & cookies.	Configuration
/status	—	Interactive real-time task manager.	Configuration
/cancel [job_id]	—	Cancel active/queued job.	Configuration
/help	/start	Open interactive paged help menu.	—

---

Quick Start Example

# 1. Clone repository
git clone https://github.com/Burhanverse/tgdl.git
cd tgdl

# 2. Synchronize dependencies using uv
uv sync

# 3. Configure credentials in .env and launch with ./start.sh
cp .env.example .env
./start.sh