Telegram Readonly

Read the user's personal Telegram account in a controlled, read-only way via Telethon/MTProto. Use when you need to inspect Telegram chats, list dialogs, rea...

Security Scan

The skill's code and docs implement a read-only Telethon wrapper as claimed, but the registry metadata omits the required Telegram credentials and the runtime stores a high-privilege session string — you should verify the upstream repo and think carefully before installing or giving this skill access to credentials.

Purpose & Capability

The SKILL.md and the included script implement a read-only Telethon/MTProto client (dialogs, messages, search, unread lists), which matches the declared purpose. However, the registry metadata lists no required environment variables or primary credential despite the runtime and docs requiring TELEGRAM_API_ID, TELEGRAM_API_HASH, and a session string. That metadata omission is an incoherence that should be resolved before trusting the package.

Instruction Scope

The SKILL.md instructs only read actions and explicitly forbids writes; the code follows that surface (auth, dialogs, messages, search, unread queries). It also instructs saving a Telethon session string to ~/.config/telegram-readonly/config.json and to protect it. No external endpoints other than Telegram/Telethon are referenced. This is mostly scoped appropriately but the explicit storage of a high-privilege session file increases risk and should be reviewed.

Install Mechanism

There is no registry install spec; the docs recommend pipx install from a GitHub repo (git+https://github.com/ropl-btc/telegram-readonly-cli.git) or cloning/installing locally. Installing directly from a GitHub repo is common but has moderate risk — you should inspect the upstream repository and its release history before installing. The package does not pull from obscure hosts or URL shorteners, which is good.

Credentials

The runtime requires TELEGRAM_API_ID and TELEGRAM_API_HASH and either performs an interactive auth to create a TELEGRAM_SESSION_STRING or accepts it from env. The registry however declared no required env vars or primary credential. Requesting those Telegram credentials/session is appropriate for the described functionality, but the registry metadata failing to declare them is a mismatch and reduces transparency. The session string is a high-privilege secret — treat it like a password.

Persistence & Privilege

The skill writes a session file to ~/.config/telegram-readonly/config.json and sets file mode to 600, which is expected behavior for a local session. always is false and autonomous invocation is allowed (platform default). Persisting the session is necessary for functionality but increases long-term access risk; the SKILL.md acknowledges this and warns users to protect the file.

What to consider before installing

This skill implements a read-only Telethon client and legitimately needs TELEGRAM_API_ID, TELEGRAM_API_HASH, and a session string; however the registry metadata does not declare those env vars — that's an inconsistency you should not ignore. Before installing: (1) inspect the upstream GitHub repo (https://github.com/ropl-btc/telegram-readonly-cli) — review code, recent commits, open issues, and releases; (2) prefer cloning and reviewing locally before pipx installing; (3) do not provide your session string or credentials to untrusted agents or services; use the interactive auth flow and protect ~/.config/telegram-readonly/config.json (permission 600 is set by the script); (4) avoid exposing TELEGRAM_SESSION_STRING via environment to other processes/agents that could read env vars; (5) consider disabling autonomous invocation for agents that will have access to these credentials or run the skill only under direct user control. The metadata mismatch lowers trust — resolve that (ask the publisher to declare required env vars) before granting the skill access to your Telegram credentials.

Use the installed telegram-readonly CLI 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.

Installation preference

Prefer an installed CLI over hardcoded script paths.

Preferred install:

pipx install git+https://github.com/ropl-btc/telegram-readonly-cli.git

Fallback inside a repo checkout:

pip install .

After install, use:

telegram-readonly

Commands

Show built-in help

telegram-readonly help

Authenticate once

export TELEGRAM_API_ID='12345678'
export TELEGRAM_API_HASH='your_api_hash'
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.

telegram-readonly dialogs --limit 50

Read recent messages

telegram-readonly messages --chat '@username' --limit 50 --reverse

Search messages

telegram-readonly search 'invoice' --limit 50

Restrict search to one chat:

telegram-readonly search 'deadline' --chat '@username' --limit 50

List recent unread chats

Default behavior is opinionated: exclude muted and archived chats.

telegram-readonly unread-dialogs --limit 10

Include muted and/or archived when needed:

telegram-readonly unread-dialogs --limit 10 --include-muted --include-archived

List recent unread DMs only

telegram-readonly unread-dms --limit 10

Workflow

1. Read references/setup-and-safety.md if setup, auth, or unread-state behavior matters.
2. Ensure the telegram-readonly CLI is installed.
3. Ensure Telegram API credentials exist.
4. Run auth once to create the session.
5. Use dialogs, messages, search, unread-dialogs, or unread-dms as needed.
6. 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
• Compatibility wrapper: scripts/telegram_readonly.py
• Setup notes: references/setup-and-safety.md
• Config storage: ~/.config/telegram-readonly/config.json

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