node-telegram-cli

A powerful CLI tool to access your Telegram account directly from the terminal. Send/read messages, manage groups, search conversations, and more — all via Telegram's MTProto protocol.

Installation

npm install -g node-telegram-cli

Requirements: Node.js >= 20

Prerequisites

You need Telegram API credentials:

1. Go to my.telegram.org
2. Log in with your phone number
3. Navigate to API development tools
4. Create a new application
5. Copy api_id and api_hash

Quick Start

# 1. Login (first time only — will ask for api_id, api_hash, phone, OTP)
ntg login

# 2. Send a message
ntg msg @username "Hello from CLI!"

# 3. Read recent conversations
ntg inbox

# 4. Read only unread private chats
ntg inbox --unread --private

# 5. Read messages from a specific chat
ntg inbox --chat @username --limit 20

# 6. Interactive real-time chat
ntg chat @username
# Type messages, press Enter to send. Type /exit to quit.

All Commands

Authentication

Command	Description
ntg login	Log in with phone number + OTP. Saves session for future use
ntg logout	Log out and clear saved session

---

Messaging

Command	Description
ntg msg <peer> <text>	Send a text message
ntg fwd <user> <msg-id>	Forward a message to another user
ntg chat <peer>	Start interactive real-time chat (/exit to quit)
ntg mark-read <peer>	Mark all messages as read
ntg delete-msg <msg-id>	Delete a message by ID
ntg restore-msg <msg-id>	Restore a deleted message (limited support)
ntg inbox [options]	View recent messages or conversations

Message options:

Flag	Description
-s, --silent	Send silently (no notification sound for recipient)

Inbox options:

Flag	Description
-c, --chat <peer>	Show messages from a specific chat
-l, --limit <n>	Number of items to show (default: 10)
-u, --unread	Show only unread conversations
-p, --private	Show only private (1-on-1) chats, exclude groups & channels

Examples:

# Send a message
ntg msg @username "Hello!"

# Send silently (no notification sound)
ntg msg @username "Hello!" --silent

# All recent conversations
ntg inbox

# Only unread
ntg inbox -u

# Only private chats
ntg inbox -p

# Unread private chats only
ntg inbox -u -p

# Last 5 messages from a specific chat
ntg inbox -c @username -l 5

---

Contacts

Command	Description
ntg add-contact <phone> <first> <last>	Add a contact by phone number
ntg rename-contact <user> <first> <last>	Rename an existing contact

Examples:

ntg add-contact +84901234567 "Nguyen" "Van A"
ntg rename-contact @username "New" "Name"

---

Multimedia

Command	Description
ntg send-photo <peer> <file>	Send a photo
ntg send-video <peer> <file>	Send a video
ntg send-file <peer> <file>	Send a text file as plain messages
ntg download <msg-id>	Download media from a message
ntg view <msg-id>	Download media & open with system viewer
ntg fwd-media <msg-id>	Forward media anonymously (strip sender)
ntg set-avatar <file>	Set your profile photo

Download/View options:

Flag	Description
-t, --type <type>	Media type: photo, video, audio, doc

Examples:

ntg send-photo @username ./photo.jpg
ntg send-video @username ./video.mp4
ntg download 12345
ntg download 12345 --type photo
ntg view 12345
ntg set-avatar ./avatar.jpg

---

Group Chat

Command	Description
ntg chat-info <chat>	Show group/channel info (members, type, etc.)
ntg chat-add <chat> <user>	Add a user to a group
ntg chat-kick <chat> <user>	Remove a user from a group
ntg chat-rename <chat> <name>	Rename a group chat
ntg create-group <topic> <users...>	Create a new group with users
ntg chat-set-photo <chat> <file>	Set group chat photo

Examples:

ntg chat-info "My Group"
ntg chat-add "My Group" @newuser
ntg chat-kick "My Group" @baduser
ntg chat-rename "My Group" "New Group Name"
ntg create-group "Project Chat" @user1 @user2 @user3
ntg chat-set-photo "My Group" ./group-photo.jpg

---

Search

Command	Description
ntg search <peer> <pattern>	Search messages in a specific chat
ntg global-search <pattern>	Search messages across all chats

Examples:

ntg search @username "meeting"
ntg global-search "password"

---

Peer Format

The <peer> argument accepts multiple formats:

Format	Example	Description
@username	@johndoe	Telegram username
Phone number	+84901234567	International format
me	me	Your own Saved Messages
Chat title	"My Group"	Group/channel title (use quotes)

Session & Config

All data is stored in ~/.telegram-cli/:

~/.telegram-cli/
├── config.json     # API credentials & session string
└── downloads/      # Downloaded media files

To reset everything: ntg logout or delete ~/.telegram-cli/.

Development

# Clone & install
git clone <repo-url> && cd node-telegram-cli
npm install

# Build
npm run build

# Test locally
npm link
ntg --help

License

MIT