Open-source TypeScript CLI

Your Telegram.
One command away.

Read live chats, build a searchable local memory, and manage conversations without leaving your terminal. Clear enough for people. Structured enough for agents.

Install Telegram CLI Explore the source

Runtime: Node.js 22.12.0+
Command: tg
License: GPL-3.0-only

Live chat

Structured result

Maya · Build room

Release is ready for review.

10:42

~/telegram abridged JSON

tg search "release" --account work --json

{
  "ok": true,
  "schema_version": "2",
  "data": [{
    "chat_name": "Build room",
    "sender_name": "Maya",
    "content": "Release is ready…"
  }]
}

1 matchlocal SQLite · no network

One command surface

From live chat to local memory.

Choose when to talk to Telegram, when to work from SQLite, and when a remote write is allowed. The boundary stays visible in every workflow.

Read live

Inspect unread chats, read recent messages, or listen to the stream without storing results locally.
tg inbox --markdown
Build memory

Sync the chats you need into SQLite, then search and analyze them without reconnecting.
tg sync @team
Act deliberately

Send messages and manage groups with explicit commands and a global remote-write switch.
tg config write-access off

The useful parts, close at hand

A focused toolkit for real Telegram work.

Use one account or several. Stay online for the live moment, or bring the history home for work that should be fast and repeatable.

Liveinbox · read · listen

Keep a terminal window on the conversation.

Watch incoming messages, reply from interactive listen mode, and download attachments as they arrive.

Search locally

Filter synced messages by keyword, regex, sender, chat, or time range.

tg search "incident" --hours 48

Archive to Markdown

Create incremental, rebuildable chat archives with optional media downloads.

tg archive @team --download-media

Separate accounts

Keep authentication sessions and message databases isolated per account.

tg account switch work

Structured on demand

Use stable JSON or YAML envelopes, nonzero exits, and explicit error codes in automation.

tg stats --json

Groupsmembers · admins · invites · topics

Inspect deeply. Manage when you mean to.

Explore group state, then use explicit commands for members, settings, invitations, forum topics, and messages.

❯ tg group members @team ❯ tg group topic list @team ❯ tg group invite list @team

Built for agent workflows

Give an agent commands,
not a browser.

After interactive account authentication, coding agents can query synced history, read structured results, and target a named account without changing your default.

JSON and YAML output
Stable schema and error codes
Explicit --account selection
Remote write-access control

Read the agent guide

Agent skill01 / 01

Teach your coding agent how to use `tg`.

npx skills add https://github.com/will-17173/telegram-cli \
  --skill using-telegram-cli

The included skill documents authentication, synchronization, structured querying, and safe write workflows.

Start here

Three commands to your first chat list.

Telegram CLI needs Node.js 22.12.0 or later. Account authentication runs interactively and stores each account session locally.

1 Install globally
```
npm install -g @will-17173/telegram-cli
```
2 Add an account
```
tg account add
```
3 List your chats
```
tg status
tg chats
```

Then choose a chat and build local history tg sync <chat> && tg search "keyword" --chat <chat>

A visible safety boundary

Read freely.
Gate remote writes.

Turn off Telegram mutations globally while keeping online reads and local database commands available. When you need to act, turn access back on intentionally.

tg config write-access off tg config write-access on

Telegram permissions and rate limits still apply. Large history or media requests may trigger flood waits.

Terminal ready

Bring Telegram into your workflow.

Install the CLI Star on GitHub

Your Telegram.One command away.