tg — Telegram CLI via MTProto

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

Required binaries

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

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

Runtime surface

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: +1234567890 (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>]

--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

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

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)