node-telegram-cliTelegram命令行工具

Source & Trust

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

Installation

1. 1. Requires Node.js >= 20
2. Install globally: INLINECODE0
3. Verify: INLINECODE1
4. Run ntg login once — interactive, requires phone number + OTP code from Telegram

Critical Rule: Always Use JSON Mode

1. 1. Add --json flag to every command for machine-readable output
2. INLINECODE4 is a global flag — place it before or after the subcommand
3. Example: ntg --json inbox, INLINECODE6

Peer Format

1. 1. @username — most reliable, e.g. INLINECODE8
2. Phone number — for contacts without username, e.g. INLINECODE9
3. INLINECODE10 — your own Saved Messages
4. Chat title — group/channel name in quotes, e.g. INLINECODE11

Read Commands (No Side Effects)

1. 1. ntg --json inbox — list recent conversations
2. INLINECODE13 — only unread conversations
3. INLINECODE14 — only private 1-on-1 chats
4. INLINECODE15 — combine filters
5. INLINECODE16 — messages from a specific chat
6. INLINECODE17 — search in a specific chat
7. INLINECODE18 — search across all chats
8. INLINECODE19 — show group/channel info

Write Commands (Has Side Effects)

1. 1. ntg msg <peer> "text" — send a text message
2. INLINECODE21 — send silently (no notification sound)
3. INLINECODE22 — forward a message by ID
4. INLINECODE23 — mark all messages as read
5. INLINECODE24 — delete a message
6. INLINECODE25 — send a photo
7. INLINECODE26 — send a video
8. INLINECODE27 — send a text file as plain messages
9. INLINECODE28 — download media from a message
10. INLINECODE29 — specify media type (photo, video, audio, doc)
11. INLINECODE30 — download and open with system viewer
12. INLINECODE31 — delete all downloaded media files

Group Management

1. 1. ntg create-group "Topic" @user1 @user2 — create a new group
2. INLINECODE33 — add a user to a group
3. INLINECODE34 — remove a user from a group
4. INLINECODE35 — rename a group
5. INLINECODE36 — set group photo

Contact Management

1. 1. ntg add-contact <phone> <firstName> <lastName> — add a contact
2. INLINECODE38 — rename a contact

JSON Output Schemas

Inbox (conversation list)

1. 1. name — contact/chat display name
2. INLINECODE40 — identifier to use as <peer> argument
3. INLINECODE42 — "username" | "phone" | "id"
4. INLINECODE43 — "user" | "group" | "channel"
5. INLINECODE44 — number of unread messages
6. INLINECODE45 — text/caption (empty string if media-only)
7. INLINECODE46 — use with ntg download <id> for media
8. INLINECODE48 — "photo" | "video" | "document" | "audio" | "voice" | "sticker" | "location" | "contact" | "poll" | null
9. INLINECODE49 — ISO 8601 timestamp

Chat messages (inbox --chat)

1. 1. id — message ID
2. INLINECODE51 — ISO 8601 timestamp
3. INLINECODE52 — sender display name
4. INLINECODE53 — message text/caption
5. INLINECODE54 — same values as above
6. INLINECODE55 — true if sent by you

Error Handling

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

Important Notes

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