miolamio Telegram CLI - Agent-First Telegram Client
Prerequisites
The tg command must be available. Install globally:
npm install -g @miolamio/tg-cli
You must be authenticated before using any command (except tg auth login):
tg auth status
If not logged in, the user must authenticate interactively (requires TTY):
tg auth login
Quick start
# check auth
tg auth status
# list your chats
tg chat list --limit 10
# read recent messages from a chat
tg message history @username --limit 20
# send a message
tg message send @username "Hello from Claude Code!"
# search across all chats
tg message search --query "meeting notes"
# download media from a message
tg media download @channel 42
Output modes
All commands support 4 output modes. Default is JSON.
tg chat list # JSON (default) - structured envelope { ok, data }
tg chat list --human # Human-readable - formatted for display
tg chat list --jsonl # JSONL streaming - one JSON object per line, no envelope
tg chat list --toon # TOON - token-efficient for LLMs (31-40% savings)
tg chat list --fields "id,title" # Select specific fields (dot notation for nested)
For agent workflows: prefer --toon for large outputs (saves tokens) or --jsonl for streaming list data. Use --fields to narrow output to only what you need.
Mutually exclusive: --toon / --human / --jsonl (pick one).
Global options
Available on every command:
--json # JSON output (default)
--human # Human-readable output
--jsonl # One JSON object per line (list commands)
--toon # Token-efficient TOON output
--fields <fields> # Comma-separated field selection (dot notation)
-v, --verbose # Show extra info on stderr
-q, --quiet # Suppress stderr output
--profile <name> # Use named profile (default: "default")
--config <path> # Custom config file path
--daemon # Route through persistent daemon connection
Commands
Auth
tg auth login # Interactive login (TTY required)
tg auth login --client desktop # Login with official client preset (no API keys needed)
tg auth status # Check if logged in, show current user
tg auth logout # Destroy session
Available --client presets: desktop, android, ios, macos, web-z, web-k.
Session
tg session export # Export portable session string
tg session import <session> # Import session (argument or stdin)
tg session import --skip-verify # Import without verifying connection
Chat
tg chat list # List all dialogs
tg chat list --type user # Filter: user, group, channel, supergroup
tg chat list --limit 20 --offset 5 # Paginate
tg chat info <chat> # Get chat details (title, members, permissions)
tg chat join <target> # Join by username, @username, or invite link
tg chat leave <chat> # Leave a chat
tg chat resolve <input> # Resolve username/ID/phone to full entity
tg chat invite-info <link> # Check invite link without joining
tg chat members <chat> # List members
tg chat members <chat> --search "John" # Search members by name
tg chat members <chat> --limit 50 --offset 0
tg chat topics <chat> # List forum topics (supergroups only)
tg chat create "My Group" # Create supergroup (default)
tg chat create "News" --type channel # Create channel
tg chat create "Team" --type group --description "Team chat"
tg chat edit <chat> --title "New Name" # Edit title
tg chat edit <chat> --description "Updated desc" # Edit description
tg chat kick <chat> <user> # Kick user from group/channel
Message - Reading
tg message history <chat> # Read message history (default: 50 messages)
tg message history <chat> --limit 100
tg message history <chat> --since 2026-03-01T00:00:00Z
tg message history <chat> --until 2026-03-13T23:59:59Z
tg message history <chat> --topic <id> # Forum topic messages
tg message get <chat> <ids> # Get specific messages by ID (comma-separated, max 100)
tg message pinned <chat> # Get pinned messages
tg message pinned <chat> --limit 10 --offset 0
tg message replies <channel> <ids> # Read replies/comments on channel posts
tg message replies <channel> <ids> --limit 50
Message - Searching
tg message search --query "keyword" # Search across all chats
tg message search --query "keyword" --chat @username # Search in specific chat
tg message search --chat @channel --filter photos # Filter by media type
tg message search --chat @group --topic <id> # Search within forum topic
tg message search --limit 20 --offset 0 # Paginate results
Search filters (17 types):
photos, videos, photo_video, documents, urls, gifs, voice, music, round, round_voice, chat_photos, phone_calls, mentions, geo, contacts, pinned
Message - Sending & Interaction
tg message send <chat> "Hello!" # Send text message
tg message send <chat> "Reply" --reply-to 42 # Reply to a message
tg message send <chat> "Topic msg" --topic <id> # Send to forum topic
echo "piped text" | tg message send <chat> - # Send from stdin
tg message edit <chat> <id> "Updated text" # Edit sent message (48h window)
echo "new text" | tg message edit <chat> <id> - # Edit from stdin
tg message forward <from> <ids> <to> # Forward messages (comma-separated IDs)
tg message react <chat> <id> <emoji> # React to a message
tg message react <chat> <id> <emoji> --remove # Remove reaction
tg message delete <chat> <ids> --revoke # Delete for everyone
tg message delete <chat> <ids> --for-me # Delete for self only
tg message pin <chat> <id> # Pin message (silent)
tg message pin <chat> <id> --notify # Pin with notification
tg message unpin <chat> <id> # Unpin message
Message - Polls
tg message poll <chat> --question "Lunch?" --option "Pizza" --option "Sushi" --option "Tacos"
tg message poll <chat> --question "Capital of France?" --option "London" --option "Paris" --option "Berlin" --quiz --correct 1 --solution "Paris is the capital"
tg message poll <chat> --question "Pick all" --option "A" --option "B" --option "C" --multiple
tg message poll <chat> --question "Vote" --option "Yes" --option "No" --public
tg message poll <chat> --question "Quick?" --option "A" --option "B" --close-in 3600
Message - Watch (requires daemon)
tg message watch <chat> # Stream new messages in real-time (JSONL)
tg message watch <chat> --topic <id> # Watch specific forum topic
Requires a running daemon (tg daemon start). Outputs JSONL stream of messages.
Media
tg media download <chat> <ids> # Download media from messages
tg media download <chat> <ids> -o ./photo.jpg # Save to specific path
tg media send <chat> ./photo.jpg # Upload and send single file
tg media send <chat> ./a.jpg ./b.jpg # Send as album (multiple files)
tg media send <chat> ./doc.pdf --caption "Report" # With caption
tg media send <chat> ./img.png --reply-to 42 # Reply with media
tg media send <chat> ./img.png --topic <id> # Send to forum topic
User
tg user profile <users> # Get profiles (comma-separated IDs/usernames)
tg user block <user> # Block user
tg user unblock <user> # Unblock user
tg user blocked # List blocked users
tg user blocked --limit 20 --offset 0
Contact
tg contact list # List all contacts
tg contact list --limit 50 --offset 0
tg contact add @username # Add by username or ID
tg contact add +1234567890 --first-name "John" --last-name "Doe" # Add by phone
tg contact delete <user> # Delete contact
tg contact search "query" # Search contacts
tg contact search "query" --global # Search all Telegram users
tg contact search "query" --limit 10
Daemon
Persistent connection for faster sequential operations and real-time features:
tg daemon start # Start background daemon (5 min idle timeout)
tg daemon start --idle-timeout 600 # Custom idle timeout in seconds
tg daemon start --foreground # Run in foreground (don't fork)
tg daemon stop # Stop running daemon
tg daemon status # Check status (running, pid, uptime)
Use --daemon flag on any command to route through persistent connection.
Shell Completion
tg completion bash # Generate bash completion script
tg completion zsh # Generate zsh completion script
tg completion fish # Generate fish completion script
Chat identifiers
Most commands accept <chat> which can be:
- Username:
durovor@durov - Numeric ID:
123456789or-100123456789 - Phone number:
+1234567890
Examples
Monitor a channel for new messages
tg message history @channel --limit 5 --toon
Search and read a conversation thread
tg message search --query "project update" --chat @team_group --limit 10
# then read replies to a specific message
tg message replies @team_group 1234 --limit 20
Send a file with context
tg media send @colleague ./report.pdf --caption "Q1 Report - see page 3 for highlights"
Get overview of a group
tg chat info @group_name
tg chat members @group_name --limit 10
tg message pinned @group_name
tg message history @group_name --limit 10 --toon
Forward messages between chats
tg message forward @source_chat 100,101,102 @destination_chat
Create a poll
tg message poll @team_chat --question "Sprint retrospective: what went well?" --option "CI/CD improvements" --option "Code review process" --option "Documentation" --option "Testing coverage" --multiple --public
Export session for use in another environment
tg session export
# Copy the session string to the new environment
tg session import "exported_session_string_here"
Narrow output with --fields
tg chat list --fields "id,title,type" --limit 5
tg message history @chat --fields "id,text,date,senderId" --limit 10
tg user profile @username --fields "id,username,firstName,bio"
Specific tasks
- Authentication & sessions references/authentication.md
- Message workflows references/message-workflows.md
- Media handling references/media-handling.md
- Output modes & field selection references/output-modes.md
- Agent automation patterns references/agent-patterns.md