tg-cli

tg-cli — read-only Telegram CLI for quick channel access in AI agents.

Stack

• TypeScript
• Bun
• GramJS (telegram)
• Commander.js

Install

npm install -g @insuline/tg-cli

Usage

tg auth login

tg auth status
tg auth logout


tg search "my channel"
tg info @channel

tg read @channel

tg read @channel/123
tg stats @channel/123

Global flags

--limit N         default 20
--offset N        default 0
--pretty          pretty-print JSON output

JSON format

{
  "ok": true,
  "data": { ... },
  "meta": { "count": 20, "has_more": true }
}

read returns media metadata in media:

{
  "type": "photo",
  "raw_class_name": "MessageMediaPhoto",
  "file_id": "5253...",
  "access_hash": "6924...",
  "file_reference": "A...==",
  "dc_id": 2,
  "width": 1103,
  "height": 1280,
  "has_stickers": false
}

На прямой публичный URL Telegram сейчас не даёт — пока возвращаются только метаданные для последующей загрузки через Telegram API.

Errors

{
  "ok": false,
  "error": {
    "code": "CHANNEL_NOT_FOUND",
    "message": "..."
  }
}

Config

Stored in ~/.tg-cli/:

• session.json — GramJS StringSession
• config.json — Telegram API credentials

Credentials priority:

1. TG_API_ID + TG_API_HASH
2. ~/.tg-cli/config.json
3. Interactive prompt on first login