Telegram Cli

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    # Comma-separated field selection (dot notation)
-v, --verbose       # Show extra info on stderr
-q, --quiet         # Suppress stderr output
--profile     # Use named profile (default: "default")
--config      # 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            # 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                    # Get chat details (title, members, permissions)
tg chat join                  # Join by username, @username, or invite link
tg chat leave                   # Leave a chat
tg chat resolve               # Resolve username/ID/phone to full entity
tg chat invite-info             # Check invite link without joining
tg chat members                 # List members
tg chat members  --search "John"  # Search members by name
tg chat members  --limit 50 --offset 0
tg chat topics                  # 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  --title "New Name"              # Edit title
tg chat edit  --description "Updated desc"    # Edit description
tg chat kick              # Kick user from group/channel

Message - Reading

tg message history              # Read message history (default: 50 messages)
tg message history  --limit 100
tg message history  --since 2026-03-01T00:00:00Z
tg message history  --until 2026-03-13T23:59:59Z
tg message history  --topic   # Forum topic messages
tg message get             # Get specific messages by ID (comma-separated, max 100)
tg message pinned               # Get pinned messages
tg message pinned  --limit 10 --offset 0
tg message replies      # Read replies/comments on channel posts
tg message replies   --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            # 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  "Hello!"                       # Send text message
tg message send  "Reply" --reply-to 42          # Reply to a message
tg message send  "Topic msg" --topic        # Send to forum topic
echo "piped text" | tg message send  -          # Send from stdin
tg message edit   "Updated text"            # Edit sent message (48h window)
echo "new text" | tg message edit   -       # Edit from stdin
tg message forward                     # Forward messages (comma-separated IDs)
tg message react                     # React to a message
tg message react    --remove         # Remove reaction
tg message delete   --revoke               # Delete for everyone
tg message delete   --for-me               # Delete for self only
tg message pin                              # Pin message (silent)
tg message pin   --notify                   # Pin with notification
tg message unpin                            # Unpin message

Message - Polls

tg message poll  --question "Lunch?" --option "Pizza" --option "Sushi" --option "Tacos"
tg message poll  --question "Capital of France?" --option "London" --option "Paris" --option "Berlin" --quiz --correct 1 --solution "Paris is the capital"
tg message poll  --question "Pick all" --option "A" --option "B" --option "C" --multiple
tg message poll  --question "Vote" --option "Yes" --option "No" --public
tg message poll  --question "Quick?" --option "A" --option "B" --close-in 3600

Message - Watch (requires daemon)

tg message watch                                # Stream new messages in real-time (JSONL)
tg message watch  --topic                   # Watch specific forum topic

Requires a running daemon (tg daemon start). Outputs JSONL stream of messages.

Media

tg media download                          # Download media from messages
tg media download   -o ./photo.jpg         # Save to specific path
tg media send  ./photo.jpg                      # Upload and send single file
tg media send  ./a.jpg ./b.jpg                  # Send as album (multiple files)
tg media send  ./doc.pdf --caption "Report"     # With caption
tg media send  ./img.png --reply-to 42          # Reply with media
tg media send  ./img.png --topic            # Send to forum topic

User

tg user profile                # Get profiles (comma-separated IDs/usernames)
tg user block                   # Block user
tg user unblock                 # 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               # 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 `` 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](references/authentication.md)
• Message workflows [references/message-workflows.md](references/message-workflows.md)
• Media handling [references/media-handling.md](references/media-handling.md)
• Output modes & field selection [references/output-modes.md](references/output-modes.md)
• Agent automation patterns [references/agent-patterns.md](references/agent-patterns.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: miolamio
• Source: miolamio/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.