bgevorkian Telegram User
Generic Telegram user-account skill built on Telethon. It uses only environment-based configuration, prints UTF-8 JSON, keeps login explicit and interactive, and blocks writes unless both gates are enabled.
Local .env
The CLI automatically loads a private .env beside this SKILL.md through pass-cli. Copy .env.example to .env; never commit the real file. The Telethon session remains separate machine-local state.
Configuration
| Variable | Required | Default |
|---|---|---|
TELEGRAM_API_ID |
for all network commands | none |
TELEGRAM_API_HASH |
for all network commands | none |
TELEGRAM_SESSION_FILE |
no | platform user-data path |
TELEGRAM_ALLOW_WRITE |
no | false |
Default session path:
- Windows:
%APPDATA%/telegram-user/telethon.session - Linux/macOS:
$XDG_DATA_HOME/telegram-user/telethon.sessionor~/.local/share/telegram-user/telethon.session
The session file contains the Telegram authorization key and is machine-local state. Authenticate once on each computer. Do not store the session file in Git, a password manager, a shared drive, or another synchronization service. A password manager may provide TELEGRAM_API_ID and TELEGRAM_API_HASH, but it does not replace the per-machine login session.
Secret setup
Before configuring API credentials, ask which secret manager and local profile the user wants. Follow Secure secret profiles. Do not invent or publish profile names or secret references. Treat the Telethon session as a separate credential file with private permissions. If the user asks for the author's method, use process-scoped pass-cli run for environment credentials. Never request or display resolved values or session contents.
Run
From this skill directory:
uv run --python 3.13 --with telethon python scripts/tg.py status
uv run --python 3.13 scripts/login.py
uv run --python 3.13 --with telethon python scripts/tg.py me
uv run --python 3.13 --with telethon python scripts/tg.py dialogs --limit 50
uv run --python 3.13 --with telethon python scripts/tg.py messages me --limit 20
uv run --python 3.13 --with telethon python scripts/tg.py search "invoice" --chat me --limit 20
uv run --python 3.13 --with telethon python scripts/tg.py saved messages --limit 20
uv run --python 3.13 --with telethon python scripts/tg.py folders list
uv run --python 3.13 --with telethon python scripts/tg.py folders get work
uv run --python 3.13 --with telethon python scripts/tg.py contacts list --limit 100
uv run --python 3.13 --with telethon python scripts/tg.py raw messages.GetDialogFiltersRequest '{}'
Interactive login uses QR authorization by default. Give users this command exactly as written:
uv run --python 3.13 scripts/login.py
If the user explicitly requests phone authorization, append --phone; the number itself remains optional. Do not invent shell prompts, environment prefixes, or unrelated arguments.
Use --help on the root command or any subcommand.
Write gate
These commands mutate Telegram state and require both:
TELEGRAM_ALLOW_WRITE=true--confirm-write
Guarded operations:
send,edit,deletesaved sendfolders add-peers,folders remove-peers,folders move-peers,folders set-titlecontacts add,contacts deleterawwhen the method is not confidently read-only
Read commands do not require the gate.
Notes
- Login defaults to a terminal QR code and stores authorization only in the local SQLite session. Phone login is an explicit fallback.
- Login never prints API hashes, session bytes, or 2FA passwords.
- Set
TELEGRAM_SESSION_FILEwhen an agent-specific local state path is preferred; its parent directory is created automatically. folders move-peers --to DEST [--from SOURCE] PEER...adds first, then removes from the source; if removal fails, peers remain safely present in both folders rather than being lost.- Prompts are written to stderr so stdout stays machine-readable JSON.
rawaccepts inline JSON,@file.json, or-for stdin.- Complex raw arguments may use Telethon-style type objects such as
{"_":"InputPeerSelf"}.
Tests
uv run --python 3.13 --with telethon python tests/test_tg.py