Metadata-Version: 2.5
Name: telegram-export-md
Version: 0.4.1
Summary: Convert Telegram Desktop chat exports (result.json) into clean, readable Markdown files
Project-URL: Homepage, https://github.com/Retro-Zero/telegram-export-md
Project-URL: Repository, https://github.com/Retro-Zero/telegram-export-md
Project-URL: Changelog, https://github.com/Retro-Zero/telegram-export-md/releases
Author-email: Arian Karimi <arian.karimion@gmail.com>
License: MIT
License-File: LICENSE
Keywords: backup,chat,cli,export,markdown,telegram
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Provides-Extra: fetch
Requires-Dist: telethon<2,>=1.34; extra == 'fetch'
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Provides-Extra: ui
Requires-Dist: textual<3,>=1.0; extra == 'ui'
Description-Content-Type: text/markdown

# telegram-export-md

> Turn Telegram's unreadable `result.json` export into clean, searchable Markdown files.

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](pyproject.toml)
[![PyPI](https://img.shields.io/pypi/v/telegram-export-md.svg)](https://pypi.org/project/telegram-export-md/)
[![CI](https://github.com/Retro-Zero/telegram-export-md/actions/workflows/ci.yml/badge.svg)](https://github.com/Retro-Zero/telegram-export-md/actions/workflows/ci.yml)

**🌐 Languages:** English · [فارسی](README.fa.md)

Telegram Desktop's built-in **Export chat history** gives you a giant `result.json`
(plus folders full of media) — technically complete, practically unreadable.
`telegram-export-md` converts it into one tidy Markdown file per chat, with
formatting, replies, forwards, polls, and media all preserved.

**Zero dependencies. Pure Python standard library.**

![terminal demo](assets/demo.gif)

## Before → After

**Before** — raw export JSON:

```json
{"id": 183, "type": "message", "date": "2021-01-01T10:00:00",
 "from": "Arian", "text": [{"type": "plain", "text": "hello "},
 {"type": "bold", "text": "everyone"}, {"type": "plain", "text": "?"}]}
```

**After** — rendered Markdown:

```markdown
**2021-01-01 10:00 — Arian**

hello **everyone**?

---

**2021-01-02 18:30 — Arian**

![](media/Gaming Crew/photo_1.jpg)

*1920×1080*
```

## Features

- 📄 **One Markdown file per chat**, plus an `index.md` table of contents
- 🖥 **Terminal UI** (optional extra) — browse exports, tick chats, convert, and preview the Markdown with Textual
- 📡 **`fetch` mode** (optional extra) — pull chats straight from Telegram's servers, no desktop app needed
- 🎨 **Telegram formatting preserved** — bold, italic, code, pre, strikethrough, underline, links
- 💬 **Replies resolved** — quoted with sender and a snippet of the original message
- ↩️ **Forwards, edits, and polls** rendered faithfully
- 🖼 **Media support** — photos embed, everything else links; `--copy-media` makes the backup self-contained
- 🔍 **Filters** — pick chats by name or id, slice by date range
- 🧹 **Service messages** (joins, pins, calls) can be excluded
- 🐍 **No dependencies** — works on Python 3.10+, Windows/macOS/Linux

## Install

```bash
# from PyPI
pipx install telegram-export-md

# optional: fetch mode (pull chats from Telegram's servers via their API)
pipx install 'telegram-export-md[fetch]'

# optional: terminal UI (browse + convert + preview)
pipx install 'telegram-export-md[ui]'

# or directly from this repo
uv tool install git+https://github.com/Retro-Zero/telegram-export-md.git
# or
pip install git+https://github.com/Retro-Zero/telegram-export-md.git
```

## Usage

### 1. Export your data

In Telegram Desktop: **Settings → Advanced → Export chat history**.
Tick **JSON** as the format and check **Include photos and videos** if you want media.
This creates a folder containing `result.json` and media subfolders.

### 2. Convert

```bash
tg-export-md ~/Downloads/Telegram-Export -o ~/telegram-backup
```

Result:

```
telegram-backup/
├── index.md
├── Gaming Crew.md
├── Saved Messages.md
└── media/
    └── Gaming Crew/
        ├── photo_1.jpg
        └── video_1.mp4
```

### Options

| Option | Description |
|---|---|
| `export` | Path to the export folder (containing `result.json`) or to `result.json` itself |
| `-o, --output` | Output directory (default: `./markdown`) |
| `--chat TEXT` | Only export chats whose name **or id** contains `TEXT` |
| `--since YYYY-MM-DD` | Only messages on or after this date |
| `--until YYYY-MM-DD` | Only messages on or before this date |
| `--copy-media` | Copy media into the output folder (self-contained backup) |
| `--no-media` | Omit media references entirely |
| `--no-service` | Skip service messages (joins, pins, calls, …) |
| `--quiet` | Only print errors |

### Examples

```bash
# One chat, as a searchable text archive
tg-export-md export/ -o backup --chat "Gaming Crew" --copy-media

# Everything from 2022, text only
tg-export-md export/ -o backup --since 2022-01-01 --no-media

# Point straight at the JSON file
tg-export-md export/result.json -o backup
```

## Automatic backup with `fetch`

No desktop app? No problem. `tg-export-md fetch` pulls chats straight from
Telegram's servers into the **same `result.json` + media format** the desktop
export produces — so the converter above works unchanged, and you get backups
you can schedule.

### Setup (once)

1. Get free API keys at [my.telegram.org](https://my.telegram.org) →
   **API development tools**
2. Make the keys available — either:

   ```bash
   export TG_API_ID=123456
   export TG_API_HASH=yourhash
   ```

   or save them in `~/.config/telegram-export-md/config.ini`:

   ```ini
   [telegram]
   api_id = 123456
   api_hash = yourhash
   ```

3. Install with the extra: `pipx install 'telegram-export-md[fetch]'`

### Run

Run **without flags** for an interactive picker: after login it lists your
chats and lets you choose which ones to export, which media types to download
(photo, video, voice, audio, document, sticker, animation), and optional
limits — last N messages per chat, a per-file size cap, and a date range.

```bash
tg-export-md fetch -o ~/telegram-export
```

The first run asks for your phone number and a login code Telegram sends you —
the session is saved, so later runs are automatic. Everything the picker asks
is also available as a flag, so cron jobs stay hands-free:

```bash
tg-export-md fetch -o ~/telegram-export --chat "Family" --media-types photo,video --last 500 --max-size 100mb
tg-export-md ~/telegram-export -o ~/telegram-backup
```

| Flag | Description |
|---|---|
| `--chat TEXT` | only fetch chats whose name or id contains `TEXT` |
| `--since / --until YYYY-MM-DD` | date range |
| `--last N` (alias `--limit`) | only the last N messages per chat (newest) |
| `--media` | download all media types |
| `--media-types TYPES` | which media to download: photo,video,voice,audio,document,sticker,animation |
| `--max-size SIZE` | skip files larger than this (e.g. `50mb`, `1gb`) |

## Terminal UI

Prefer pointing and clicking? `tg-export-md ui` launches a terminal UI (built
with [Textual](https://github.com/Textualize/textual)):

1. Browse to your export folder in the file tree
2. Tick the chats you want and set options (copy media, skip service messages, output folder)
3. Hit **Convert** — it runs in the background with a live log
4. Preview the rendered Markdown of any chat, then go back and tweak

```bash
pipx install 'telegram-export-md[ui]'
tg-export-md ui
```

## Notes

- **Large exports** — the whole `result.json` is loaded into memory; exports up to a
  few hundred MB work fine on a modern laptop. Streaming support is on the roadmap.
- **Media paths** without `--copy-media` point back into your original export folder.
  Use `--copy-media` for a backup you can move or archive.
- **Restricted chats** — in chats where the other side enabled *Restrict saving
  content*, the full text history still exports, but their media can't be saved by
  anyone (by design). `fetch` keeps the messages with media placeholders and prints
  a per-file warning, plus a "could not be saved" count in the end summary. Secret
  chats (end-to-end encrypted) are never visible to the API at all.
- **Media availability** — `fetch` downloads whatever media is still available
  at fetch time; files that are already gone are kept as references in the
  JSON and counted in the end summary.
- Export JSON is generated by **Telegram Desktop** (Windows/macOS/Linux).
  Exports from other clients may differ slightly — open an issue if something doesn't parse.

## Roadmap

- [ ] Streaming parse for huge exports
- [ ] Support the HTML export format
- [ ] Per-year splitting (`--split`)
- [ ] `--format obsidian` for vault-friendly output

## Contributing

Bug reports, feature requests, and PRs are welcome. Please open an issue first
for anything beyond a small fix.

## License

[MIT](LICENSE)
