https://github.com/dudarev/telegram-reader
Read-only Telegram CLI for agents and terminals. Markdown output, XDG config, Telethon-based.
https://github.com/dudarev/telegram-reader
cli markdown python read-only telegram telethon
Last synced: 26 days ago
JSON representation
Read-only Telegram CLI for agents and terminals. Markdown output, XDG config, Telethon-based.
- Host: GitHub
- URL: https://github.com/dudarev/telegram-reader
- Owner: dudarev
- License: mit
- Created: 2025-09-27T17:40:00.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-28T14:20:34.000Z (9 months ago)
- Last Synced: 2025-09-28T16:23:26.530Z (9 months ago)
- Topics: cli, markdown, python, read-only, telegram, telethon
- Language: Python
- Homepage:
- Size: 539 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Roadmap: docs/ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# telegram-reader
Minimal, read-only Telegram CLI tool designed for AI agents.
- Read messages from users/groups/channels
- List dialogs to discover peers
- Read-only: never sends messages
- XDG config in `~/.config/telegram-reader/config.yaml`
- Session stored in `~/.local/share/telegram-reader/`
## Install
We recommend using [uv](https://github.com/astral-sh/uv) for fast Python package management.
### Development Install
In your virtual env:
```bash
uv pip install -e .
```
To install testing dependencies (including pytest):
```bash
uv pip install -e .[test]
```
### Global Install
```bash
uv tool install .
```
For traditional pip-based installation, see the `pyproject.toml` for dependencies.
## Configure
Create `~/.config/telegram-reader/config.yaml`:
```yaml
api_id: 123456
api_hash: "your_api_hash"
# optional
default_limit: 10
```
Get `api_id` and `api_hash` from https://my.telegram.org
## Usage
- Initialize/login (prompts for phone, code, optional 2FA):
```bash
tgr auth
```
- Agent-focused help (compact guide for automation):
```bash
tgr agent
```
- List dialogs (prints a simple Markdown list):
```bash
tgr dialogs --limit 50
```
- Read messages from a peer (username, t.me link, or numeric id). Output is Markdown blocks with second-level headers set to local human-readable timestamps (YYYY-MM-DD HH:MM):
```bash
tgr messages --peer @durov --limit 10
```
- Include explicit placeholders for media-only messages in the Markdown output:
```bash
tgr messages --peer @durov --limit 20 --include-media
```
- Download media while keeping Markdown output for the message stream:
```bash
tgr messages --peer @durov --limit 20 --include-media --download-media --out ./downloads
```
- Download voice/audio media for automation workflows. Output is JSONL with one record per downloaded file:
```bash
tgr media --peer @durov --limit 20 --types voice,audio --out ./downloads
```
Pagination options:
```bash
tgr messages --peer -1001234567890 --limit 50 --offset-id 12345
```
Outputs Markdown for `tgr messages`. By default empty messages are omitted; `--include-media` renders placeholders for media-only messages. A summary line with the next suggested `offset-id` is printed to stderr.
`tgr media` keeps the same pagination model and writes JSONL metadata that includes Telegram ids, timestamps, media type, and the local download path. Downloaded files use deterministic names under `//`.
## Scope
- Read-only and minimal by design
- No sending/posting
- Telethon under the hood
## License
This project is licensed under the MIT License - see the LICENSE file for details.