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

Tgsession

Install / Use

README