better-tg-cli 0.17.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Derek Rein (original skillhq/telegram)
+Copyright (c) 2026 Sergei Polin (better-tg-cli modifications)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# better-tg-cli
+
+An unofficial, agent-friendly command-line client for Telegram on your own account (MTProto via `teleproto`, TL layer 229).
+The binary is `telegram`. Fork of [skillhq/telegram](https://github.com/skillhq/telegram) with bot
+buttons, rich (layer 228+) bot replies, threads and forum topics, compact output for agents, and
+about 60 commands. Run `telegram help-all` for the full command and flag list.
+
+## Installation
+
+```bash
+brew install thevilfer/tap/better-tg-cli   # standalone binary, macOS and Linux, no Node needed
+npm install -g better-tg-cli               # Node >= 20
+```
+
+Both install the `telegram` command. To use it as an agent skill (Claude Code, Codex), clone the
+repo into the skills folder. That folder is the skill (`SKILL.md` + `reference.md`):
+
+```bash
+git clone https://github.com/TheVilfer/better-tg-cli.git ~/.agents/skills/telegram
+ln -s ~/.agents/skills/telegram ~/.claude/skills/telegram
+```
+
+To build from source you need Node >= 20 and [Bun](https://bun.sh) (the bundler):
+`npm install && npm run build && npm install -g .` (or `./install.sh`).
+
+Do **not** install `@skillhq/telegram`. That is the old upstream build on GramJS (layer 198), and
+bot replies show up as `(no text)`.
+
+**Linux note:** secrets go to the macOS Keychain or to 1Password (`telegram auth --op-vault`).
+Without either, the session is kept in `~/.config/tg/config.json5` (mode 0600), and write
+commands stay disabled.
+
+## Authentication
+
+**Your own API keys (default, for everyone):**
+1. Go to https://my.telegram.org/apps and log in with your phone number
+2. Create an application and copy its `api_id` and `api_hash`
+3. Run `telegram auth` and enter them, then your phone, the login code and your 2FA password
+
+**With an invite.** If the maintainer gave you an invite token, you don't need your own keys:
+
+```bash
+telegram auth --invite        # paste the token when asked (or: TG_INVITE=... / --invite -)
+```
+
+The invite service (`broker/`) hands out the app's keys once for your login. The `api_hash` is
+not stored on your machine afterwards, only the `api_id` and your session. Invites are personal,
+limited to a few logins, and can be revoked.
+
+Your session is stored in the macOS Keychain (service `tg-cli`), or in 1Password with
+`--op-vault`. `telegram logout` removes it.
+
+## Commands
+
+### Auth & Status
+
+```bash
+telegram whoami                              # Show logged-in account
+telegram check                               # Verify session/credentials
+```
+
+### Reading
+
+```bash
+telegram chats                               # List all chats
+telegram chats --type group                  # Filter by type (user, group, supergroup, channel)
+telegram read "MetaDAO Community" -n 50      # Read last 50 messages
+telegram read "MetaDAO" --since "1h"         # Messages from last hour
+telegram read @username -n 20                # Read DM with user
+telegram search "futarchy" --chat "MetaDAO"  # Search within chat
+telegram search "futarchy" --all             # Search all chats
+telegram inbox                               # Unread messages summary
+```
+
+### Writing
+
+```bash
+telegram send @username "Hello"              # Send DM
+telegram send "GroupName" "Hello everyone"   # Send to group
+telegram reply "ChatName" 12345 "Response"   # Reply to message ID
+```
+
+### Bot Buttons
+
+```bash
+telegram buttons @SomeBot 12345              # List buttons on a message
+telegram click @SomeBot 12345 2              # Press button #2 (by index)
+telegram click @SomeBot 12345 "Settings"     # Press by label
+telegram click @SomeBot 12345 1 --json       # Machine-readable outcome
+```
+
+Buttons show up inline in `read`/`inbox`/`search` output. After a callback
+press, `click` re-reads the message so you see the bot's edited reply and its
+new buttons — enough to navigate a bot's menus step by step. `click` needs
+write access enabled.
+
+### Reactions, Forwarding & Pinning
+
+```bash
+telegram react "ChatName" 12345 👍           # React with an emoji (--big, --remove)
+telegram reactions "ChatName" 12345          # List who reacted
+telegram forward "FromChat" 12345 "ToChat"   # Forward message(s); comma-separate IDs
+telegram pin "ChatName" 12345                # Pin (--notify to alert members)
+telegram unpin "ChatName" 12345              # Unpin one; omit ID to unpin all
+```
+
+### Editing, Deleting, Polls & Formatting
+
+```bash
+telegram edit "Chat" 12345 "new text"        # Edit your own message
+telegram delete "Chat" 12,13 --just-me       # Delete (revoke by default)
+telegram mark-read "Chat"                    # Clear unread badge
+telegram pinned "Chat"                       # List pinned messages
+telegram send @user "<b>hi</b>" --html       # HTML/Markdown formatting (--markdown)
+telegram send @user "later" --schedule 2h    # Schedule a message
+telegram poll "Chat" "Q?" A B C              # Send a poll
+telegram vote "Chat" 12345 2                 # Vote for option #2
+```
+
+### Real-time, Chats & Profile
+
+```bash
+telegram watch "Chat" -t 30                  # Stream new messages (timeout/limit required)
+telegram join @channel                       # Join (also invite links); leave/create-group/create-channel
+telegram archive "Chat"                      # Archive / unarchive; invite-link "Chat"
+telegram block @user                         # block/unblock; add-contact/del-contact
+telegram set-name "First" "Last"             # set-bio / set-username / set-avatar
+telegram avatar @user                        # Download avatar; inline @gif "cat"; stories @user
+```
+
+All of the above except reads (`reactions`, `pinned`, `watch`, `avatar`, `inline`, `stories`) are write operations and need write access enabled.
+
+### Contacts & Groups
+
+```bash
+telegram contact @username                   # Get contact info
+telegram members "GroupName"                 # List group members
+telegram admins "GroupName"                  # List admins only
+telegram groups                              # List all groups
+telegram groups --admin                      # Groups where you're admin
+telegram kick "GroupName" @username          # Remove a user from a group
+telegram promote "GroupName" @username       # Promote a member to admin
+telegram transfer-owner "GroupName" @username # Transfer ownership (prompts for 2FA password)
+```
+
+> `transfer-owner` is irreversible and requires two-step verification on your account.
+> It works on supergroups/channels only, prompts for your 2FA password securely, and asks
+> you to retype the group name to confirm (`-y` skips the confirmation).
+
+### Muting
+
+```bash
+telegram mute "ChatName"                     # Mute forever
+telegram mute "ChatName" -d 1h              # Mute for 1 hour
+telegram mute @username -d 8h               # Mute DM for 8 hours
+telegram unmute "ChatName"                   # Unmute
+```
+
+### Folders
+
+```bash
+telegram folders                             # List all folders
+telegram folder "Work"                       # Show chats in folder
+telegram folder-add "Work" "ProjectChat"     # Add chat to folder
+telegram folder-remove "Work" "ProjectChat"  # Remove chat from folder
+```
+
+### Utilities
+
+```bash
+telegram sync --days 7                       # Sync last 7 days to markdown
+telegram sync --chat "MetaDAO" --days 30     # Sync specific chat
+```
+
+## Output Formats
+
+All read commands support multiple output formats:
+
+```bash
+telegram chats --json                        # JSON (for scripts/AI)
+telegram read "Chat" --markdown              # Markdown format
+telegram inbox --plain                       # Plain text (no colors)
+```
+
+## Configuration
+
+Configuration is stored in `~/.config/tg/`:
+- `config.json` - API credentials and session
+- Session data is encrypted and stored securely
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run dev                            # Watch mode
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE). Based on [skillhq/telegram](https://github.com/skillhq/telegram)
+by Derek Rein. Not affiliated with or endorsed by Telegram; "Telegram" is a trademark of its owner.

package/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: telegram
+description: Full-featured Telegram CLI on the user's own account — read, search, send, edit and delete messages, read comments/threads and forum topics, manage groups and channels, press bot buttons, react, forward, pin, poll/vote, watch live messages, manage contacts and your own profile, and sync history. Use when the user asks about Telegram messages, wants to check inbox or unread, search chats, send/edit/delete messages, format messages, schedule a message, mute/unmute chats, kick/block users, press bot buttons or navigate bot menus, react with emoji, forward or pin messages, create polls or vote, join/leave/create/archive chats, get invite or message links, watch for new messages in real time, query inline bots, read stories, download media or avatars, manage contacts, or update their own name/bio/username/avatar. Also «телеграм», «тг», «телега», «проверь телеграм», «что в тг», «напиши в телеграм», «прочитай чат», «найди в телеге».
+---
+
+# Telegram CLI
+
+`telegram <command>` runs on the user's own account (MTProto, not a bot).
+
+**Before using an unfamiliar flag, run `telegram help-all -g <word>`.** It lists every command and flag, generated from the code, so it is always current. For behaviour details (threads, bot buttons, sync, JSON shapes, errors), read `reference.md` next to this file.
+
+## Rules
+
+- **Chat identifiers:** `me` means Saved Messages. A numeric ID is matched exactly (use the ID shown first in `chats`/`inbox`/`search` output). `@username` resolves exactly. Any other text matches chat titles by **substring**. For writes, use an ID or @username.
+- **Writes are off by default.** A write fails with "Write access is disabled". Only the user can turn writes on. `telegram write-access on --for 1h` shows them a confirmation dialog, which you cannot click yourself. Ask first, run it, and wait for their click. Get explicit approval for every message to other people and show the final text first.
+- **Save tokens:**
+  - Start with `inbox --unmuted`, `chats -q <name>` or `search`, not a full `read`.
+  - Add `--max-text 200` when skimming.
+  - Use `get <chat> <id>` to fetch exactly what you need.
+  - Plain output off a TTY is already compact, one line per item with the ID first. Use `--json` only when you parse with jq.
+- **Long or multi-line text:** pass `-` and pipe it through stdin (`printf '%s' "$text" | telegram send <chat> -`). This avoids quoting bugs.
+
+## Core commands
+
+```bash
+telegram inbox --unmuted -n 20                 # unread chats, most unread first (IDs first)
+telegram chats -q "name"                       # find a chat's ID; --unread, --type channel, --archived
+telegram read <chat> -n 20                     # newest first; --asc, --since 1d, --until 2026-09-01
+telegram read <chat> --unread                  # only what the user hasn't read yet
+telegram read <chat> --from @user              # one sender; --before/--after <msgId> for paging
+telegram read <chat> --thread <postId>         # comments under a post; posts with comments show 💬N in read output
+telegram topics <forum> ; telegram read <forum> --topic <id>
+telegram get <chat> <id> [id...]               # exact messages
+telegram search "query" -n 20                  # global; --chat <c> [--from @u], --type photo|url|document|voice|mentions, --since 7d
+telegram info <chat>                           # members, about, linked comments chat, forum?
+telegram members <group> -q name ; telegram contacts -q name
+telegram send <chat> "text"                    # --reply-to <id>, --topic <id>, --html, --silent, --schedule 2h
+telegram reply <chat> <msgId> "text"
+telegram send-file <chat> ./file.pdf -c "caption"
+telegram edit <chat> <msgId> "new text" ; telegram delete <chat> <id,id>
+telegram click <bot> <msgId> <index|label>     # press a bot button; `read` shows [index] label (type)
+telegram react <chat> <msgId> 👍 ; telegram forward <from> <ids> <to> ; telegram pin <chat> <id>
+telegram download <chat> <msgId> -o ./dir
+telegram link <chat> <msgId>                   # t.me link (channels/supergroups)
+telegram watch [chat] -t 60 -n 10 --json       # live stream; always bound it with -t/-n
+telegram sync --chat <c> --output ./dir --resume   # markdown export, incremental
+telegram mark-read <chat> ; telegram mute <chat> -d 8h
+```
+
+## JSON shapes (with `--json`)
+
+`chats`, `contacts` and `members` return an array. `read` and `get` return `{chatTitle, messages[]}`. `search` returns an array of `{messages[]}`, and global hits carry `chatId` and `chatTitle`. `inbox` returns `{totalUnread, chatsWithUnread, chats[]}`; it skips archived chats unless you pass `--include-archived`, and the totals cover all chats even when `-n` cuts the list. Chat objects have `id`, `title`, `type`, `username`, `unreadCount`, `muted`, `archived` and `lastMessage`. Messages have `id`, `date`, `sender`, `senderId`, `text`, `replyToMsgId`, `isOutgoing`, `media`, `buttons` and `replies` (the comment count). Empty fields are omitted.
+
+## If `telegram` is missing
+
+Reinstall with `brew install thevilfer/tap/better-tg-cli` or `npm install -g better-tg-cli`, or from this folder with `npm install && npm run build && npm install -g .` (needs Bun). **Never** install `@skillhq/telegram` from npm or update this skill with the skills CLI: that is an old GramJS build, and bot replies come back as `(no text)`.