Telegram Readonly

Use the local skill script for Telegram reads from the user's personal account.

This skill exists because Telegram Bot API is the wrong tool for reading a real personal account. Use MTProto via Telethon instead.

Quick rules

Use this skill only for reads.
Do not improvise write actions.
Do not add send/edit/delete logic to the wrapper unless the user explicitly asks.
Treat the Telethon session like a high-privilege secret.
Assume unread preservation is best-effort until tested on a real chat.

Local setup

Prefer the skill-local script and a skill-local virtual environment over any global CLI install. Prefer saved Telegram config over shell-exported environment variables once setup is complete. Treat .venv as generated local state, not part of the skill itself.

Bootstrap the local environment:

<skill-path>/scripts/bootstrap_venv.sh

After bootstrap, use:

<skill-path>/scripts/telegram-readonly

If .venv is missing later, just run the bootstrap script again.

Primary config path:

~/.config/telegram-readonly/config.json

Recommended one-time setup:

Make sure api_id and api_hash are available.
Run:

<skill-path>/scripts/telegram-readonly auth

After successful login, the config file stores api_id, api_hash, and the Telegram session string so future reads do not need exported shell variables.

Commands

Show built-in help

<skill-path>/scripts/telegram-readonly help

Authenticate once

export TELEGRAM_API_ID='12345678'
export TELEGRAM_API_HASH='your_api_hash'
<skill-path>/scripts/telegram-readonly auth

List chats

dialogs --query does token-based matching across name, username, and title, so queries like petros skynet work even when the exact full string is not present as one substring.

<skill-path>/scripts/telegram-readonly dialogs --limit 50

Read recent messages

<skill-path>/scripts/telegram-readonly messages --chat '@username' --limit 50 --reverse

Search messages

<skill-path>/scripts/telegram-readonly search 'invoice' --limit 50

Restrict search to one chat:

<skill-path>/scripts/telegram-readonly search 'deadline' --chat '@username' --limit 50

List recent unread chats

Default behavior is opinionated: exclude muted and archived chats.

<skill-path>/scripts/telegram-readonly unread-dialogs --limit 10

Include muted and/or archived when needed:

<skill-path>/scripts/telegram-readonly unread-dialogs --limit 10 --include-muted --include-archived

List recent unread DMs only

<skill-path>/scripts/telegram-readonly unread-dms --limit 10

Workflow

Read references/setup-and-safety.md if setup, auth, or unread-state behavior matters.
Ensure the skill-local virtual environment is bootstrapped.
Ensure Telegram API credentials exist.
Run auth once to create the session and write ~/.config/telegram-readonly/config.json.
Use dialogs, messages, search, unread-dialogs, or unread-dms as needed.
Keep usage narrow and intentional.

Expected outputs

The wrapper returns JSON. Parse it instead of relying on fragile text scraping.

Dialog objects include:

is_user
is_group
is_channel
is_bot
archived
muted
unread counters

Files

Package repo: https://github.com/ropl-btc/telegram-readonly-cli
Launcher: scripts/telegram-readonly
Python implementation: scripts/telegram_readonly.py
Local bootstrap: scripts/bootstrap_venv.sh
Setup notes: references/setup-and-safety.md
Config storage: ~/.config/telegram-readonly/config.json
.env is optional fallback only; it is not the preferred long-term setup.
.venv/ is generated local state and can be recreated with scripts/bootstrap_venv.sh.

When to stop and ask

Stop and ask before:

adding write capabilities
enabling any background watcher/daemon
broad exporting of large chat histories
changing how secrets/session storage works