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: durov or @durov
• Numeric ID: 123456789 or -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