Skills node-telegram-cli

CLI tool for Telegram via MTProto. Send/read messages, manage groups, search conversations, download media, and automate Telegram workflows. Use when the task involves any Telegram account interaction.

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/baontq23/telegram-cli" ~/.claude/skills/clawdbot-skills-node-telegram-cli && rm -rf "$T"

manifest: skills/baontq23/telegram-cli/SKILL.md

source content

Source & Trust

Repository: https://github.com/baontq23/node-telegram-cli
npm: https://www.npmjs.com/package/node-telegram-cli (published with provenance)
Credentials are stored securely via OS Keychain (macOS Keychain / Windows Credential Manager / Linux Secret Service), not in plaintext files

Installation

Requires Node.js >= 20
Install globally:
```
npm install -g node-telegram-cli
```
Verify:
```
ntg --version
```
Run
```
ntg login
```
once — interactive, requires phone number + OTP code from Telegram

Critical Rule: Always Use JSON Mode

Add
```
--json
```
flag to every command for machine-readable output
```
--json
```
is a global flag — place it before or after the subcommand

Example:

ntg --json inbox

ntg --json search @user "keyword"

Peer Format

```
@username
```
— most reliable, e.g.
```
@johndoe
```
Phone number — for contacts without username, e.g.
```
+84901234567
```
```
me
```
— your own Saved Messages
Chat title — group/channel name in quotes, e.g.
```
"My Group"
```

Read Commands (No Side Effects)

```
ntg --json inbox
```
— list recent conversations
```
ntg --json inbox --unread
```
— only unread conversations
```
ntg --json inbox --private
```
— only private 1-on-1 chats
```
ntg --json inbox --unread --private
```
— combine filters

ntg --json inbox --chat <peer> --limit <n>

— messages from a specific chat

```
ntg --json search <peer> "keyword"
```
— search in a specific chat
```
ntg --json global-search "keyword"
```
— search across all chats
```
ntg --json chat-info <chat>
```
— show group/channel info

Write Commands (Has Side Effects)

```
ntg msg <peer> "text"
```
— send a text message
```
ntg msg <peer> "text" --silent
```
— send silently (no notification sound)
```
ntg fwd <user> <msgId>
```
— forward a message by ID
```
ntg mark-read <peer>
```
— mark all messages as read
```
ntg delete-msg <msgId>
```
— delete a message
```
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 <msgId> --chat <peer>
```
— download media from a message
```
ntg download <msgId> --chat <peer> --type <type>
```
— specify media type (photo, video, audio, doc)
```
ntg view <msgId> --chat <peer>
```
— download and open with system viewer
```
ntg clean-downloads
```
— delete all downloaded media files

Group Management

```
ntg create-group "Topic" @user1 @user2
```
— create a new group
```
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> "New Name"
```
— rename a group
```
ntg chat-set-photo <chat> <file>
```
— set group photo

Contact Management

ntg add-contact <phone> <firstName> <lastName>

— add a contact

ntg rename-contact <user> <firstName> <lastName>

— rename a contact

JSON Output Schemas

Inbox (conversation list)

```
name
```
— contact/chat display name
```
peer
```
— identifier to use as
```
<peer>
```
argument
```
peerType
```
— "username" | "phone" | "id"
```
type
```
— "user" | "group" | "channel"
```
unreadCount
```
— number of unread messages
```
lastMessage
```
— text/caption (empty string if media-only)
```
lastMessageId
```
— use with
```
ntg download <id>
```
for media
```
mediaType
```
— "photo" | "video" | "document" | "audio" | "voice" | "sticker" | "location" | "contact" | "poll" | null
```
date
```
— ISO 8601 timestamp

Chat messages (inbox --chat)

```
id
```
— message ID
```
date
```
— ISO 8601 timestamp
```
sender
```
— sender display name
```
text
```
— message text/caption
```
mediaType
```
— same values as above
```
isOutgoing
```
— true if sent by you

Error Handling

Exit code
```
0
```
= success
Exit code
```
1
```
= error (not logged in, peer not found, etc.)
If not logged in, commands fail with: "Not logged in. Run ntg login first."

Important Notes

Do NOT use
```
ntg chat <peer>
```
— it is interactive, blocks stdin, not suitable for automation
Session persists until
```
ntg logout
```
is called — no re-login needed between commands
Downloaded files are saved to
```
~/.telegram-cli/downloads/
```
Always specify
```
--chat <peer>
```
when downloading media to identify the source chat