tgsession

Telegram Session Toolkit Generate, inspect, dump, and convert Telegram sessions between Telethon and Pyrogram.

tgsession is designed to be clean, explicit, and predictable — no magic, no broken conversions, no messy side effects.

✨ Features

• Generate Telethon sessions

• Generate Pyrogram sessions

• Convert sessions:

  • Telethon → Pyrogram (string)
  • Pyrogram → Telethon (planned)

• Inspect Telethon .session files

• Dump Telethon session metadata as JSON

• Clean, colored CLI output (Colorama)

• Works on Linux / Termux / GitHub Actions

⚠️ File-based Pyrogram session conversion is experimental. String sessions are the recommended and stable format.

📦 Installation

git clone https://github.com/ankit-chaubey/tgsession.git
cd tgsession
pip install -e .

Or from PyPI release:

pip install tgsession

🚀 Usage

General Help

tgsession --help

🔧 Generate Sessions

Generate a Telethon session

tgsession gen tl myaccount

Creates:

• myaccount.session (Telethon SQLite session)

Generate a Pyrogram session

tgsession gen pyro myaccount

Creates:

• Pyrogram string session (recommended)

🔍 Inspect Sessions

Inspect a Telethon session

tgsession inspect myaccount.session

Shows:

• DC ID
• Server address
• Port

📤 Dump Sessions

Dump Telethon session as JSON

tgsession dump myaccount.session

Outputs structured metadata useful for debugging and tooling.

🔄 Convert Sessions

Telethon → Pyrogram (string session)

tgsession convert tl myaccount.session pyro

Output:

• Pyrogram string session (printed to stdout)

🧠 Design Philosophy

• Explicit > Implicit
• No hidden authorization steps
• No silent session mutation
• One clear source of truth per session

If something converts — it really converts.

🗂 Project Structure

tgsession/
├── cli.py                 # CLI entry point
├── gen/
│   ├── telethon_gen.py    # Telethon generator
│   └── pyrogram_gen.py    # Pyrogram generator
├── inspect/
│   └── telethon_inspect.py
├── dump/
│   └── telethon_dump.py
├── convert/
│   ├── tl_to_pyro.py
│   └── pyro_to_tl.py
└── core/
    └── utils.py

🛣 Roadmap

• Stable Pyrogram → Telethon conversion
• Optional Pyrogram file session export
• Non-interactive mode (CI friendly)
• Plugin system

👤 Author

Ankit Chaubey GitHub: https://github.com/ankit-chaubey

📄 License

MIT License