# Telegram User

> Use Telethon against a user's own Telegram account through a UTF-8 JSON CLI for login, status, profile, dialogs, messages, search, saved messages, folders, contacts, and guarded mutations. Configure only with TELEGRAM_API_ID, TELEGRAM_API_HASH, and TELEGRAM_SESSION_FILE.

- Skill: `bgevorkian/telegram-user` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add bgevorkian/telegram-user`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bgevorkian/telegram-user/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: bgevorkian (https://skillmd.com/u/bgevorkian)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bgevorkian/telegram-user

---


# 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.session` or `~/.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](https://github.com/bgevorkian/agent-skills/blob/main/docs/secure-secrets.md). 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:

```bash
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:

```bash
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**:

1. `TELEGRAM_ALLOW_WRITE=true`
2. `--confirm-write`

Guarded operations:

- `send`, `edit`, `delete`
- `saved send`
- `folders add-peers`, `folders remove-peers`, `folders move-peers`, `folders set-title`
- `contacts add`, `contacts delete`
- `raw` when 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_FILE` when 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.
- `raw` accepts inline JSON, `@file.json`, or `-` for stdin.
- Complex raw arguments may use Telethon-style type objects such as `{"_":"InputPeerSelf"}`.

## Tests

```bash
uv run --python 3.13 --with telethon python tests/test_tg.py
```