tgcli

tgcli — Read-Only Telegram CLI

Read-only CLI that authenticates as the user's personal Telegram account via MTProto. All output is structured for agent consumption.

Binary: tgcli (installed globally via npm install -g @notxcain/tgcli) Session: ~/.tgcli/session (mode 0600) Config: ~/.tgcli/config.json

Output format

Always use the default TOON format. TOON is 30-60% smaller than JSON and you can parse it just fine. Never add --json unless:

• Piping output to jq
• The user explicitly asks for JSON output

Flag	Format
(default)	TOON — always use this
--json	JSON — only when piping to jq or user requests it
--plain	Human-readable plain text

Commands

auth

Interactive authentication. Requires API credentials from https://my.telegram.org/auth.

tgcli auth

folders

List all chat folders. Returns array of { id, name }.

tgcli folders

search [query]

Search dialogs by name, or list chats in a folder. Requires either a query or --folder.

tgcli search "Tech"
tgcli search --folder 248
tgcli search "Mom" --folder 248

Option	Default	Description
--folder <id>	—	Filter to chats in this folder (use tgcli folders to list)
--limit <n>	20	Maximum results

Returns array of:

{ "id": "123456789", "name": "John Doe", "type": "dm|group|channel", "unreadCount": 3 }

active

List chats with recent activity.

tgcli active
tgcli active --days 3

Option	Default	Description
--days <n>	5	Number of days to look back
--limit <n>	50	Maximum results

Returns same shape as search.

info <chat-id>

Get chat metadata.

tgcli info "123456789"

Returns:

{ "id": "123456789", "name": "John Doe", "type": "dm|group|channel", "memberCount": 2 }

read <chat-id>

Read messages from a chat.

tgcli read "123456789" --limit 10
tgcli read "123456789" --after 2026-02-20
tgcli read "123456789" --before 2026-02-22 --after 2026-02-20

Option	Default	Description
--limit <n>	50	Maximum messages
--before <date>	—	Messages before this ISO date
--after <date>	—	Messages after this ISO date

Returns array of:

{
  "id": 4522,
  "date": "2026-02-22T10:31:00Z",
  "from": "John Doe",
  "text": "Here's the file",
  "media": { "type": "photo|video|document|sticker|voice|audio|other", "filename": "report.pdf", "size": 245000, "mimeType": "application/pdf", "width": 1920, "height": 1080, "duration": 120 }
}

media is null when the message has no attachment.

download <chat-id> <message-id>

Download media from a specific message.

tgcli download "123456789" 4522
tgcli download "123456789" 4522 --out-dir /tmp

Option	Default	Description
--out-dir <path>	.	Output directory

Returns:

{ "path": "/tmp/report.pdf", "size": 245000, "mimeType": "application/pdf" }