A fast, scriptable command-line tool for downloading photos, videos, documents, and other media from any Telegram channel, group, or chat — with smart resume, deduplication, filtering, named profiles, and a friendly setup wizard.

It also exposes a background-job layer with a JSON API, which powers the Raycast extension.

• Everything, filtered — pick media types, date ranges, size bounds, caption keywords (plain or /regex/), and specific senders.
• Smart resume — partial downloads continue where they left off; completed files are skipped on re-run.
• Deduplication — by Telegram file ID (no re-download) and by content hash.
• Flexible organisation — filename templates + optional subfolders by type, date, or sender, plus optional .json metadata sidecars.
• Resource-aware — disk-space estimate before downloading and a pause threshold while running.
• Profiles — save a configuration once, re-run it forever.
• Background jobs — detached downloads you can monitor from anywhere (see docs/json-api.md).

pipx install tgdl      # recommended — isolated, on your PATH
# or
pip install tgdl

Requires Python 3.11+.

tgdl init                       # one-time: API credentials + login
tgdl download                   # interactive wizard, then download
tgdl download @somechannel      # pre-fill the channel
tgdl download --dry-run         # preview without saving anything

You'll need a Telegram API ID and API hash from https://my.telegram.org → API Development Tools. tgdl init walks you through it.

Start a detached download and monitor it from any process:

echo '{"channel":"@somechannel","media_types":["photo","video"]}' > cfg.json
tgdl job start --config cfg.json        # → {"job_id": "...", "pid": ...}
tgdl job list --json
tgdl job status <job_id> --json

The full, stable contract is documented in docs/json-api.md.

See CONTRIBUTING.md. Bug reports and PRs welcome.

MIT © Olufemi Okikioluwa