agent-telegram 0.4.1 → 0.6.0

package/README.md

@@ -30,7 +30,7 @@ agent-telegram login                      # Interactive login
 agent-telegram my-info                    # Get your profile
 agent-telegram chat list                  # List all chats
 agent-telegram chat open @username        # View messages from chat
-agent-telegram send --to @user "Hello!"   # Send message
+agent-telegram send @user "Hello!"        # Send message
 agent-telegram stop                       # Stop server
 ```
 
@@ -43,41 +43,66 @@ agent-telegram login                      # Interactive login
 agent-telegram logout                     # Logout and clear session
 agent-telegram my-info                    # Get your profile information
 agent-telegram llms-txt                   # Generate full CLI documentation for LLMs
-
 ```
 
 ### Send Messages
 
+Supports both subcommands and flags for backward compatibility:
+
 ```bash
-agent-telegram send --to @user "text"               # Text message
-agent-telegram send --to @user --photo image.png    # Photo
-agent-telegram send --to @user --video video.mp4    # Video
-agent-telegram send --to @user --voice voice.ogg    # Voice message
-agent-telegram send --to @user --video-note vid.mp4 # Video note (circle)
-agent-telegram send --to @user --sticker file.webp  # Sticker
-agent-telegram send --to @user --gif anim.mp4       # GIF/animation
-agent-telegram send --to @user --document file.pdf  # Document
-agent-telegram send --to @user --audio music.mp3    # Audio
-agent-telegram send --to @user --contact "+1234567890" --first-name "John"  # Contact
-agent-telegram send --to @user --reply-to 123 "Reply text"                  # Reply
-agent-telegram send --to @user --poll "Question?" --option "Yes" --option "No"  # Poll
-agent-telegram send --to @user --latitude 55.7558 --longitude 37.6173       # Location
+# Subcommands (recommended)
+agent-telegram send text @user "Hello!"                    # Text message
+agent-telegram send photo @user image.png                  # Photo
+agent-telegram send photo @user image.png --caption "Nice" # Photo with caption
+agent-telegram send video @user video.mp4                  # Video
+agent-telegram send voice @user voice.ogg                  # Voice message
+agent-telegram send sticker @user file.webp                # Sticker
+agent-telegram send dice @user                             # Dice (random value)
+agent-telegram send dice @user --emoticon 🎯               # Dice with emoticon
+agent-telegram send poll @user "Question?" --option A --option B  # Poll
+agent-telegram send location @user --lat 55.75 --long 37.61      # Location
+agent-telegram send contact @user --phone "+123" --first-name Jo  # Contact
+
+# Flag syntax (still works)
+agent-telegram send --to @user "text"
+agent-telegram send --to @user --photo image.png
+agent-telegram send --to @user --video video.mp4
+agent-telegram send --to @user --voice voice.ogg
+agent-telegram send --to @user --video-note vid.mp4
+agent-telegram send --to @user --sticker file.webp
+agent-telegram send --to @user --gif anim.mp4
+agent-telegram send --to @user --document file.pdf
+agent-telegram send --to @user --audio music.mp3
+agent-telegram send --to @user --dice
+agent-telegram send --to @user --contact "+1234567890" --first-name "John"
+agent-telegram send --to @user --reply-to 123 "Reply text"
+agent-telegram send --to @user --poll "Question?" --option "Yes" --option "No"
+agent-telegram send --to @user --latitude 55.7558 --longitude 37.6173
+
+# Pipe support
+echo "Hello from pipe" | agent-telegram send @user
 ```
 
 ### Message Management (`msg`)
 
 ```bash
-agent-telegram msg read @user             # Mark messages as read
-agent-telegram msg typing @user           # Send typing indicator
-agent-telegram msg scheduled @user        # List scheduled messages
-agent-telegram msg delete @user 123       # Delete message by ID
-agent-telegram msg forward @user --to @other 123  # Forward message
-agent-telegram msg pin @user 123          # Pin message
-agent-telegram msg pin @user 123 --unpin  # Unpin message
-agent-telegram msg reaction @user 123 "👍" # Add reaction
-agent-telegram msg inspect-buttons @user 123      # View inline buttons
-agent-telegram msg press-button @user 123 0 0     # Press button (row, col)
-agent-telegram msg inspect-keyboard @user         # View reply keyboard
+agent-telegram msg list @user              # List messages
+agent-telegram msg list @user --output ids # List message IDs only (pipe-friendly)
+agent-telegram msg read --to @user         # Mark messages as read
+agent-telegram msg typing --to @user       # Send typing indicator
+agent-telegram msg scheduled --to @user    # List scheduled messages
+agent-telegram msg delete --to @user 123   # Delete message by ID
+agent-telegram msg delete --to @user 1,2,3 # Delete multiple messages
+agent-telegram msg forward 123 --from @user --to @other  # Forward message
+agent-telegram msg pin 123 --to @user      # Pin message
+agent-telegram msg pin 123 --to @user --unpin            # Unpin message
+agent-telegram msg reaction 123 "👍" --to @user          # Add reaction
+agent-telegram msg inspect-buttons 123 --to @user        # View inline buttons
+agent-telegram msg press-button 123 0 --to @user         # Press button
+agent-telegram msg inspect-keyboard --to @user           # View reply keyboard
+agent-telegram msg clear --to @user 123,456              # Clear specific messages
+agent-telegram msg clear --to @user --history             # Clear entire history
+agent-telegram msg clear --to @user --history --revoke    # Clear history for both sides
 ```
 
 ### Chat Management (`chat`)
@@ -85,72 +110,67 @@ agent-telegram msg inspect-keyboard @user         # View reply keyboard
 ```bash
 agent-telegram chat list                  # List all chats
 agent-telegram chat list -l 50            # List with limit
-agent-telegram chat info @channel         # Get chat information
+agent-telegram chat info --to @channel    # Get chat information
 agent-telegram chat open @user            # View messages
 agent-telegram chat open @user -l 50      # View 50 messages
 agent-telegram chat open @user -l 50 -o 100   # With offset
-agent-telegram chat create-group "Name" @user1 @user2   # Create group
-agent-telegram chat create-channel "Name" "Description" # Create channel
-agent-telegram chat join https://t.me/+invite           # Join via link
-agent-telegram chat subscribe @channel    # Subscribe to channel
-agent-telegram chat leave @group          # Leave chat/channel
-agent-telegram chat invite @group @user   # Invite user
-agent-telegram chat edit-title @group "New Title"       # Edit title
-agent-telegram chat set-photo @group photo.jpg          # Set photo
-agent-telegram chat delete-photo @group   # Delete photo
-agent-telegram chat pin @group            # Pin chat in list
-agent-telegram chat pin @group --unpin    # Unpin from list
-agent-telegram chat mute @group           # Mute notifications
-agent-telegram chat mute @group --unmute  # Unmute
-agent-telegram chat archive @group        # Archive chat
-agent-telegram chat archive @group --unarchive  # Unarchive
-agent-telegram chat topics @forum         # List forum topics
-agent-telegram chat invite-link @group    # Get/create invite link
+agent-telegram chat create-group "Name" --members @user1,@user2  # Create group
+agent-telegram chat create-channel "Name" --description "Desc"   # Create channel
+agent-telegram chat join --link https://t.me/+invite             # Join via link
+agent-telegram chat subscribe --channel @channel                 # Subscribe to channel
+agent-telegram chat leave --to @group     # Leave chat/channel
+agent-telegram chat invite --to @group --user @user              # Invite user
+agent-telegram chat edit-title --to @group --title "New Title"   # Edit title
+agent-telegram chat set-photo --to @group --file photo.jpg       # Set photo
+agent-telegram chat delete-photo --to @group                     # Delete photo
+agent-telegram chat pin --to @group       # Pin chat in list
+agent-telegram chat mute --to @group      # Mute notifications
+agent-telegram chat archive --to @group   # Archive chat
+agent-telegram chat topics --to @forum    # List forum topics
+agent-telegram chat invite-link --to @group  # Get/create invite link
 ```
 
 ### Members & Admins
 
 ```bash
-agent-telegram chat participants @group   # List members
-agent-telegram chat admins @group         # List admins
-agent-telegram chat banned @group         # List banned users
-agent-telegram chat promote-admin @group @user    # Promote to admin
-agent-telegram chat demote-admin @group @user     # Demote admin
-agent-telegram chat slow-mode @group 30   # Set slow mode (seconds)
-agent-telegram chat permissions @group    # Set default permissions
+agent-telegram chat participants --to @group   # List members
+agent-telegram chat admins --to @group         # List admins
+agent-telegram chat banned --to @group         # List banned users
+agent-telegram chat promote-admin --to @group --user @user    # Promote to admin
+agent-telegram chat demote-admin --to @group --user @user     # Demote admin
+agent-telegram chat slow-mode --to @group --seconds 30        # Set slow mode
+agent-telegram chat permissions --to @group --send-messages    # Set permissions
 ```
 
 ### Contacts (`contact`)
 
 ```bash
 agent-telegram contact list               # List contacts
-agent-telegram contact add "+1234567890" "John" "Doe"   # Add contact
-agent-telegram contact delete @user       # Delete contact
+agent-telegram contact add --phone "+1234567890" --first-name "John" --last-name "Doe"
+agent-telegram contact delete --user @user
 ```
 
 ### User (`user`)
 
 ```bash
 agent-telegram user info @user            # Get user info
-agent-telegram user ban @user             # Block user
-agent-telegram user ban @user --unban     # Unblock user
-agent-telegram user mute @user            # Mute user
-agent-telegram user mute @user --unmute   # Unmute user
+agent-telegram user ban --to @user        # Block user
+agent-telegram user ban --to @user -d     # Unblock user
 ```
 
 ### Folders (`folders`)
 
 ```bash
 agent-telegram folders list               # List chat folders
-agent-telegram folders create "Work"      # Create folder
-agent-telegram folders delete 1           # Delete folder by ID
+agent-telegram folders create --title "Work" --include-groups  # Create folder
+agent-telegram folders delete --id 1      # Delete folder by ID
 ```
 
 ### Privacy (`privacy`)
 
 ```bash
-agent-telegram privacy get phone_number   # Get privacy setting
-agent-telegram privacy set phone_number allow_contacts  # Set privacy
+agent-telegram privacy get --key phone_number    # Get privacy setting
+agent-telegram privacy set --key phone_number --rule allow_contacts  # Set privacy
 ```
 
 **Privacy keys:** `status_timestamp`, `phone_number`, `profile_photo`, `forwards`, `phone_call`, `voice_messages`, `about`
@@ -160,9 +180,21 @@ agent-telegram privacy set phone_number allow_contacts  # Set privacy
 ### Search
 
 ```bash
-agent-telegram search "query"             # Search in chats
-agent-telegram search "query" --global    # Global search
-agent-telegram search "query" --in @user  # Search in specific chat
+agent-telegram search global "query"                # Global search
+agent-telegram search global "query" --type bots    # Search bots only
+agent-telegram search in-chat "query" --to @user    # Search in specific chat
+agent-telegram search in-chat "query" --to @user --type photos  # Search photos
+```
+
+### Updates
+
+```bash
+agent-telegram updates                    # Get pending updates
+agent-telegram updates -l 50             # Get 50 updates
+agent-telegram updates --follow           # Continuous polling (JSON Lines)
+agent-telegram updates --follow --type new_message   # Filter by type
+agent-telegram updates --follow --interval 5         # Poll every 5 seconds
+agent-telegram updates --follow | jq '.type'         # Pipe to jq
 ```
 
 ### Server
@@ -177,18 +209,21 @@ agent-telegram stop                       # Stop server
 
 ```bash
 agent-telegram open @user                 # Quick open chat (alias)
-agent-telegram updates                    # Get pending updates
-agent-telegram updates -l 50              # Get 50 updates
 ```
 
-## Options
+## Global Options
 
 | Option | Description |
 |--------|-------------|
 | `-s, --socket <path>` | Path to Unix socket (default: `/tmp/agent-telegram.sock`) |
-| `-j, --json` | JSON output (for agents) |
-| `-l, --limit <n>` | Limit results |
-| `-o, --offset <n>` | Offset for pagination |
+| `-q, --quiet` | Suppress status messages (data still goes to stdout) |
+| `-T, --text` | Output human-readable text instead of JSON |
+| `--output <format>` | Output format: `text`, `json`, `ids` |
+| `--fields <list>` | Select output fields (comma-separated) |
+| `--filter <expr>` | Filter results (e.g., `type=channel`, `stars>1000`) |
+| `--dry-run` | Preview action without executing |
+| `-l, --limit <n>` | Limit results (per command) |
+| `-o, --offset <n>` | Offset for pagination (per command) |
 
 ## Environment Variables
 
@@ -201,34 +236,49 @@ agent-telegram updates -l 50              # Get 50 updates
 
 Default API credentials are built-in, so you can start using agent-telegram immediately. To use your own credentials, get them at https://my.telegram.org and set via environment variables or `.env` file.
 
-## Agent Mode
+## Pipe-Friendly Patterns
 
-Use `--json` / `-j` for machine-readable output:
+All commands output JSON to stdout by default. Status/logs go to stderr.
 
 ```bash
-agent-telegram chat list --json
-agent-telegram chat open @user -l 10 --json
-agent-telegram send --to @user "Hello" --json
+# Get message IDs for piping
+agent-telegram msg list @user --output ids | head -5
+
+# Filter and select fields
+agent-telegram chat list --fields peer,title,type --filter type=channel
+
+# Continuous monitoring with jq
+agent-telegram updates --follow --type new_message | jq '{from: .data.message.from_name, text: .data.message.text}'
+
+# Quiet mode (suppress stderr, data only)
+agent-telegram msg list @user -q | jq '.messages[].text'
+
+# Compose commands
+agent-telegram search global "bot" --output ids | head -3
 ```
 
-### Optimal AI Workflow
+## Usage with AI Agents
 
-```bash
-# 1. Start server and verify status
-agent-telegram serve
-agent-telegram status --json
+### Just ask the agent
 
-# 2. List chats to find targets
-agent-telegram chat list -l 20 --json
+The simplest approach - just tell your agent to use it:
+
+```
+Use agent-telegram to send a message to @username. Run agent-telegram --help to see available commands.
+```
 
-# 3. Read messages from a chat
-agent-telegram chat open @username -l 50 --json
+```markdown
+## Telegram Automation
 
-# 4. Send messages
-agent-telegram send --to @username "Hello!" --json
+Use `agent-telegram` for Telegram automation. Run `agent-telegram --help` for all commands.
 
-# 5. Check for new messages
-agent-telegram updates --json
+Core workflow:
+1. `agent-telegram serve` - Start background server
+2. `agent-telegram status` - Verify connection
+3. `agent-telegram chat list` - List available chats
+4. `agent-telegram msg list @user` - Read messages
+5. `agent-telegram send @user "message"` - Send message
+6. `agent-telegram updates --follow` - Monitor for new messages
 ```
 
 ## IPC Protocol (JSON-RPC)
@@ -244,7 +294,7 @@ echo '{"method":"send_message","params":{"peer":"@user","message":"Hi"}}' | nc -
 
 **Messages:** `send_message`, `send_reply`, `update_message`, `delete_message`, `forward_message`, `get_messages`, `clear_messages`, `clear_history`, `read_messages`, `set_typing`, `get_scheduled_messages`
 
-**Media:** `send_photo`, `send_video`, `send_file`, `send_voice`, `send_video_note`, `send_sticker`, `send_gif`, `send_location`, `send_contact`, `send_poll`
+**Media:** `send_photo`, `send_video`, `send_file`, `send_voice`, `send_video_note`, `send_sticker`, `send_gif`, `send_location`, `send_contact`, `send_poll`, `send_dice`
 
 **Reactions:** `add_reaction`, `remove_reaction`, `list_reactions`
 
@@ -268,6 +318,8 @@ echo '{"method":"send_message","params":{"peer":"@user","message":"Hi"}}' | nc -
 
 **Search:** `search_global`, `search_in_chat`
 
+**Updates:** `get_updates`
+
 **System:** `status`, `shutdown`, `ping`
 
 ## Architecture
@@ -316,29 +368,6 @@ agent-telegram --socket /tmp/agent2.sock serve
 agent-telegram --socket /tmp/agent1.sock chat list
 ```
 
-## Usage with AI Agents
-
-### Just ask the agent
-
-The simplest approach - just tell your agent to use it:
-
-```
-Use agent-telegram to send a message to @username. Run agent-telegram --help to see available commands.
-```
-
-```markdown
-## Telegram Automation
-
-Use `agent-telegram` for Telegram automation. Run `agent-telegram --help` for all commands.
-
-Core workflow:
-1. `agent-telegram serve` - Start background server
-2. `agent-telegram status` - Verify connection
-3. `agent-telegram chat list --json` - List available chats
-4. `agent-telegram chat open @user --json` - Read messages
-5. `agent-telegram send --to @user "message"` - Send message
-```
-
 ## Development
 
 See [DEVELOPMENT.md](DEVELOPMENT.md) for:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-telegram",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Telegram IPC agent CLI - interact with Telegram via command line",
   "bin": {
     "agent-telegram": "./bin/run.js"