Telegram MTPROTO CLI

Read-only Telegram CLI via MTProto. Lists chats, fetches messages, downloads media, manages local accounts/sessions. Does not send messages or modify Telegra...

Security Scan

The skill is internally consistent with its stated purpose (a read-only Telegram MTProto CLI); the only notable risk is the normal trust required to install an npm package and manage Telegram credentials/sessions locally.

Purpose & Capability

Name/description, required credentials (api_id/api_hash, phone/OTP), and runtime filesystem/network access (session files, media downloads, outbound TCP to Telegram DCs) all align with a read-only MTProto CLI. No unrelated credentials, binaries, or paths are requested.

Instruction Scope

SKILL.md instructs only how to install and use the 'tg' CLI and how to authenticate interactively. It does not ask the agent to read unrelated files, exfiltrate data to third parties, or perform write operations on Telegram. It explicitly warns about sensitive session files and not logging credentials.

Install Mechanism

Install is an npm global package (npm install -g tg-mtproto-cli) with a GitHub repo listed — this is expected for a CLI published on npm but is a moderate-risk install vector because npm package installs run third-party code. No arbitrary URL downloads or extract steps are present.

Credentials

Requested credentials are limited to Telegram API credentials and phone/OTP (interactive). Storage in system keychain and session files is appropriate for the stated functionality. No unrelated environment variables or secrets are requested.

Persistence & Privilege

Skill is instruction-only and not always:true; it does not request persistent system-wide privileges or modify other skills. The default platform ability for agents to invoke skills autonomously remains in place, which is normal and not a concern given the other checks.

Assessment

This skill appears to do what it says: it uses an npm-published CLI for read-only access to Telegram via MTProto. Before installing, verify the npm package and GitHub repo (maintainer reputation, recent commits, issues), be aware that 'npm install -g' runs third-party code, and only enter your Telegram api_id/api_hash and phone OTP interactively when you trust the environment. Protect the session files (~/.tg-mtproto-cli/sessions/) and the system keychain entries; consider using an account with limited access if you want to reduce risk. If you are uncomfortable installing global npm packages or allowing the agent to run installed CLIs autonomously, do not install or restrict agent invocation.

tg — Telegram CLI via MTProto

CLI tool for reading Telegram data directly via MTProto protocol. No Bot API, no limits.

Required binaries

Binary	Install	Purpose
tg	npm install -g tg-mtproto-cli	Core CLI
jq (optional)	brew install jq or apt install jq	JSON filtering in workflow examples

Source and provenance:

• npm: npmjs.com/package/tg-mtproto-cli
• GitHub: github.com/cyberash-dev/tg-mtproto-cli

Verify after install:

tg --version
npm ls -g tg-mtproto-cli

Required credentials

Credential	How to obtain	Storage
Telegram api_id + api_hash	my.telegram.org/apps	System keychain (macOS Keychain / Windows Credential Vault / Linux Secret Service)
Phone number + OTP code	Interactive prompt during tg auth	Not persisted; used once for session creation

Credentials are entered interactively via tg auth. No environment variables required.

Runtime surface

Resource	Access	Details
Network	Outbound TCP to Telegram DC servers	MTProto protocol, required for all commands
Session files	Read/write ~/.tg-mtproto-cli/sessions/*.session	SQLite databases with auth keys; created by tg auth
System keychain	Read/write	Stores api_id, api_hash, account metadata, default account
Filesystem	Write (only tg download)	Saves media to --out dir or current directory

Guardrails

• The CLI is read-only by design — it has no commands to send messages, create chats, modify groups, or perform any write operations on Telegram. The only write targets are local: session files and downloaded media.
• tg download writes files only to the explicitly specified --out directory or cwd.
• Session files contain sensitive auth material — do not read, copy, or expose ~/.tg-mtproto-cli/sessions/ contents.
• Do not log or display api_id / api_hash values.
• If tg auth is needed, inform the user — it requires interactive input (phone, OTP) and cannot be automated.

Chat identification

Chats can be referenced by:

• Username: @username or username
• Numeric ID: -1001234567890 (groups/supergroups use negative IDs)
• Phone: [phone] (for private chats)

To find a chat's numeric ID, use tg chats --json | jq '.[] | {id, title}'.

Commands reference

List chats

tg chats [--type private|group|supergroup|channel] [--limit 50] [--offset 0]

Read messages

tg messages <chat> [-n 100] [--all] [--topic <id>] [--after <datetime>]

Flag	Description
-n <count>	Number of messages (default: 100)
--all	Entire history (shows progress)
--topic <id>	Forum topic (get IDs via tg topics <chat>)
--after <datetime>	Only messages after this time

--after formats: 2026-02-22, 2026-02-22T10:00, 10:00 (today).

When --after + -n are combined: filter by date first, then take last N.

List forum topics

tg topics <chat>

Returns topic IDs needed for --topic flag.

Download media

tg download <chat> <messageId> [--out <dir>]

Downloads the media attachment from a specific message. Get message IDs from tg messages output (shown as #<id>).

Account management

tg auth                          # authenticate (interactive)
tg logout [alias]                # remove session
tg accounts                      # list accounts
tg accounts rename <old> <new>   # rename alias
tg default <alias>               # set default

Global flags

Flag	Effect
--account <alias>	Use specific account instead of default
--json	JSON output (for scripting/piping)

JSON output

All commands support --json for structured output. Dates are ISO 8601.

tg chats --json
tg messages @chat -n 10 --json
tg download @chat 42 --json

Message JSON schema

{
  "id": 42,
  "chatId": -1001234567890,
  "senderName": "John",
  "text": "Hello",
  "date": "2026-02-22T10:15:00.000Z",
  "media": { "type": "photo", "fileName": null, "mimeType": "image/jpeg", "size": 262525 },
  "replyToId": null,
  "isOutgoing": false
}

media is null when no attachment. media.type: photo, video, document, audio, voice, sticker.

Common workflows

Extract text from a chat since a date

tg messages @channel --after 2026-02-01 --json | jq -r '.[].text // empty'

Find messages with photos

tg messages @chat -n 500 --json | jq '[.[] | select(.media.type == "photo")]'

Download all photos from recent messages

for id in $(tg messages @chat -n 50 --json | jq -r '.[] | select(.media.type == "photo") | .id'); do
  tg download @chat "$id" --out ./photos
done

Read a forum topic

tg topics -1001234567890          # find topic ID
tg messages -1001234567890 --topic 42 -n 20

Multi-account usage

tg chats --account work
tg messages @chat -n 10 --account personal

Exit codes

Code	Meaning
0	Success
1	Runtime error (invalid args, chat not found)
2	Auth required (no account, expired session) — run tg auth

Troubleshooting

• "No default account" → run tg auth or use --account <alias>
• "Session expired" → run tg auth to re-authenticate
• Chat not found → use numeric ID from tg chats --json
• Empty messages → check chat ID sign (groups are negative)