SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillstelegram-cli

telegram-cli

General & other

View repository

Updated 10-16 08:03

About this skill

Telegram CLI

Use the local MTProto/Telethon script for the user's personal account; Telegram Bot API cannot read it.

Quick rules

  • Prefer reads first, then propose the action queue.
  • Write commands are dry-run by default and require --execute.
  • Never run any write command with --execute unless the user explicitly approved that specific action or batch first.
  • For send, present the draft first; send --execute requires approval of the final recipient and text.
  • Mark-read/archive/mute are still Telegram writes; use them only after the user has approved the batch/action.
  • Do not add edit/delete/bulk export/background automation 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.

Setup

Use the skill-local launcher and cached virtualenv. Read local setup for bootstrap, authentication, config, or encrypted credentials, and setup and safety for auth/unread-state behavior. scripts/telegram-readonly remains a compatibility alias.

Non-auth CLI operations have a 60-second deadline. A timed-out --execute write has an unknown outcome; verify it in Telegram before any retry. Interactive auth has no routine operation deadline.

Commands

Show built-in help

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

Authenticate once

<skill-path>/scripts/setup-api-key.sh
<skill-path>/scripts/telegram-cli 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-cli dialogs --limit 50

Read recent messages

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

Search messages

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

Restrict search to one chat:

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

List recent unread chats

Default behavior is opinionated: exclude muted and archived chats.

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

Include muted and/or archived when needed:

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

List recent unread DMs only

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

Send a message

Draft first in chat, ask the user to confirm, then dry-run:

<skill-path>/scripts/telegram-cli send --chat '@username' --text 'Thanks, will check.'

Send only after the user approves final text and recipient:

<skill-path>/scripts/telegram-cli send --chat '@username' --text 'Thanks, will check.' --execute

Mark read

<skill-path>/scripts/telegram-cli mark-read --chat 123456789
<skill-path>/scripts/telegram-cli mark-read --chat 123456789 --execute

Archive or unarchive

<skill-path>/scripts/telegram-cli archive --chat 123456789
<skill-path>/scripts/telegram-cli archive --chat 123456789 --execute
<skill-path>/scripts/telegram-cli archive --chat 123456789 --unarchive --execute

Mute or unmute

<skill-path>/scripts/telegram-cli mute --chat 123456789 --hours 8
<skill-path>/scripts/telegram-cli mute --chat 123456789 --hours 8 --execute
<skill-path>/scripts/telegram-cli mute --chat 123456789 --unmute --execute

Workflow

  1. Confirm setup, then read only the chats/messages needed.
  2. For writes, obtain approval, run the dry-run, verify the JSON target/action, then use --execute.

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

  • Launcher: scripts/telegram-cli
  • Launcher: scripts/telegram-readonly
  • Python implementation: scripts/telegram_cli.py
  • Local bootstrap: scripts/bootstrap_venv.sh
  • Credential setup helper: scripts/setup-api-key.sh
  • Setup notes: references/setup-and-safety.md
  • Config storage: ~/.config/telegram-cli/config.json, or the host's systemd encrypted credential when configured
  • .env is optional fallback only; it is not the preferred long-term setup.
  • ~/.cache/telegram-cli/venv is generated local state and can be recreated with <skill-path>/scripts/bootstrap_venv.sh.
  • ChatGPT/Codex MCP server: mcp/server.mjs

Legacy compatibility

Use the CLI for normal tasks. MCP compatibility code remains for existing consumers; only consult legacy MCP maintenance when explicitly maintaining that code. Do not restart the retired tunnel as part of ordinary setup.

When to stop and ask

Stop and ask before:

  • sending a Telegram message
  • enabling any background watcher/daemon
  • broad exporting of large chat histories
  • changing how secrets/session storage works

Docs

Fast lookup:

  • Telethon client reference: https://docs.telethon.dev/en/stable/quick-references/client-reference.html
  • Telethon TelegramClient API: https://docs.telethon.dev/en/stable/modules/client.html
  • Telegram folders/archive API: https://core.telegram.org/api/folders
  • Telegram notification settings API: https://core.telegram.org/method/account.updateNotifySettings