{"id":31392208,"url":"https://github.com/dudarev/telegram-reader","last_synced_at":"2026-05-17T17:05:15.409Z","repository":{"id":317059163,"uuid":"1065423014","full_name":"dudarev/telegram-reader","owner":"dudarev","description":"Read-only Telegram CLI for agents and terminals. Markdown output, XDG config, Telethon-based.","archived":false,"fork":false,"pushed_at":"2025-09-28T14:20:34.000Z","size":552,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-28T16:23:26.530Z","etag":null,"topics":["cli","markdown","python","read-only","telegram","telethon"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dudarev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-27T17:40:00.000Z","updated_at":"2025-09-28T14:20:38.000Z","dependencies_parsed_at":"2025-09-28T16:23:53.687Z","dependency_job_id":"33aa0731-a993-4a19-b096-9f3cf0f9fe09","html_url":"https://github.com/dudarev/telegram-reader","commit_stats":null,"previous_names":["dudarev/telegram-reader"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dudarev/telegram-reader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudarev%2Ftelegram-reader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudarev%2Ftelegram-reader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudarev%2Ftelegram-reader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudarev%2Ftelegram-reader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dudarev","download_url":"https://codeload.github.com/dudarev/telegram-reader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dudarev%2Ftelegram-reader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277462588,"owners_count":25822034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-29T02:00:09.175Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","markdown","python","read-only","telegram","telethon"],"created_at":"2025-09-29T03:59:53.567Z","updated_at":"2026-05-17T17:05:15.402Z","avatar_url":"https://github.com/dudarev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# telegram-reader\n\nMinimal, read-only Telegram CLI tool designed for AI agents.\n\n- Read messages from users/groups/channels\n- List dialogs to discover peers\n- Read-only: never sends messages\n- XDG config in `~/.config/telegram-reader/config.yaml`\n- Session stored in `~/.local/share/telegram-reader/`\n\n## Install\n\nWe recommend using [uv](https://github.com/astral-sh/uv) for fast Python package management.\n\n### Development Install\n\nIn your virtual env:\n\n```bash\nuv pip install -e .\n```\n\nTo install testing dependencies (including pytest):\n\n```bash\nuv pip install -e .[test]\n```\n\n### Global Install\n\n```bash\nuv tool install .\n```\n\nFor traditional pip-based installation, see the `pyproject.toml` for dependencies.\n\n## Configure\n\nCreate `~/.config/telegram-reader/config.yaml`:\n\n```yaml\napi_id: 123456\napi_hash: \"your_api_hash\"\n# optional\ndefault_limit: 10\n```\n\nGet `api_id` and `api_hash` from https://my.telegram.org\n\n## Usage\n\n- Initialize/login (prompts for phone, code, optional 2FA):\n\n```bash\ntgr auth\n```\n\n- Agent-focused help (compact guide for automation):\n\n```bash\ntgr agent\n```\n\n- List dialogs (prints a simple Markdown list):\n\n```bash\ntgr dialogs --limit 50\n```\n\n- 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):\n\n```bash\ntgr messages --peer @durov --limit 10\n```\n\n- Include explicit placeholders for media-only messages in the Markdown output:\n\n```bash\ntgr messages --peer @durov --limit 20 --include-media\n```\n\n- Download media while keeping Markdown output for the message stream:\n\n```bash\ntgr messages --peer @durov --limit 20 --include-media --download-media --out ./downloads\n```\n\n- Download voice/audio media for automation workflows. Output is JSONL with one record per downloaded file:\n\n```bash\ntgr media --peer @durov --limit 20 --types voice,audio --out ./downloads\n```\n\nPagination options:\n\n```bash\ntgr messages --peer -1001234567890 --limit 50 --offset-id 12345\n```\n\nOutputs 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.\n\n`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 `\u003cout\u003e/\u003cpeer_id\u003e/`.\n\n## Scope\n\n- Read-only and minimal by design\n- No sending/posting\n- Telethon under the hood\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdudarev%2Ftelegram-reader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdudarev%2Ftelegram-reader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdudarev%2Ftelegram-reader/lists"}