tgcli – Telegram CLI

Pure Rust Telegram client. No TDLib. Fast. Cross-platform.

Quick Start

tgcli auth                     # Authenticate (first time)
tgcli sync                     # Incremental sync
tgcli chats list --output markdown      # List chats (markdown recommended)
tgcli messages list --chat 987654321 --output markdown  # List messages from chat
tgcli send --to 123456789 --message "Hello there!"  # Send message

Core Commands

Sync

Fetch updates from Telegram servers. Always incremental (skips duplicates).

tgcli sync                     # Default (shows summary)
tgcli sync -q                  # Quiet (no output)
tgcli sync --full              # Full sync (all messages)
tgcli sync --download-media    # Save media files
tgcli sync --stream            # JSONL streaming (for pipelines)

Chats

Manage chats: list, search, archive, pin, mute, create groups, join, leave.

tgcli chats list --output markdown           # List (markdown recommended)
tgcli chats list --limit 50                  # Limit results
tgcli chats search "DevTeam"                 # Search by name
tgcli chats archive 987654321                # Archive specific chat
tgcli chats pin 987654321                    # Pin chat
tgcli chats mute 987654321                   # Mute notifications
tgcli chats create --group "Project Alpha" --user 111222333  # Create group
tgcli chats join https://t.me/joinchat/...   # Join via invite link
tgcli chats leave 987654321                  # Leave chat

Messages

List, search, show, download, delete messages. Supports forum topics.

tgcli messages list --chat 987654321 --output markdown  # List messages (markdown)
tgcli messages list --chat 987654321 --limit 100        # Limit to 100 messages
tgcli messages list --chat 987654321 --topic 42         # Forum topic messages
tgcli messages search "project deadline" --output markdown  # Local search (markdown)
tgcli messages search --global "urgent task"               # Telegram API search
tgcli messages show --chat 987654321 --message 4567       # Show specific message
tgcli messages context --chat 987654321 --message 4567    # Show with context
tgcli messages download --chat 987654321 --message 4567   # Download media
tgcli messages delete --chat 987654321 --message 4567     # Delete message

Send

Send messages, files, voice/video notes, scheduled messages, replies.

tgcli send --to 123456789 --message "Hello from tgcli"      # Text message
tgcli send --to 123456789 --file report.pdf                  # Send file
tgcli send --to 123456789 --voice note.ogg                   # Voice message
tgcli send --to 123456789 --video video.mp4                  # Video note
tgcli send --to 123456789 --message "Meeting tomorrow" --schedule "tomorrow 9am"  # Scheduled
tgcli send --to 123456789 --message "Agreed" --reply-to 5678 # Reply to message

Contacts

List and search contacts.

tgcli contacts list --output markdown   # List contacts (markdown)
tgcli contacts search "Alice"           # Search by name

Users

Show user info, block/unblock.

tgcli users show 123456789      # Show user profile
tgcli users block 123456789     # Block user
tgcli users unblock 123456789   # Unblock user

Stickers

List, search, and send stickers.

tgcli stickers list --output markdown   # List sticker packs (markdown)
tgcli stickers search "cat"             # Search sticker sets
tgcli stickers send --to 123456789 --sticker CAT_ABC123  # Send sticker

Folders

Create and manage chat folders.

tgcli folders list --output markdown   # List folders (markdown)
tgcli folders create "Work Chats"      # Create new folder
tgcli folders delete 5                 # Delete folder by ID

Admin (Groups/Channels)

Ban, kick, promote, demote members.

tgcli admin ban --chat 111222333 --user 999888777       # Ban user
tgcli admin kick --chat 111222333 --user 999888777      # Kick user
tgcli admin unban --chat 111222333 --user 999888777     # Unban user
tgcli admin promote --chat 111222333 --user 999888777   # Promote to admin
tgcli admin demote --chat 111222333 --user 999888777    # Demote admin

Daemon (Real-Time)

Listen for real-time updates from Telegram servers. Optional — use sync for most workflows.

tgcli daemon                    # Listen for updates
tgcli daemon --stream           # JSONL output
tgcli daemon --no-backfill      # Skip background sync
tgcli daemon --ignore 987654321 # Ignore specific chat
tgcli daemon --ignore-channels  # Skip all channels

Other

tgcli read --chat 987654321              # Mark chat as read
tgcli typing --chat 987654321            # Send typing indicator
tgcli profile show                       # Show your profile
tgcli profile set --first-name "Alex"    # Update your name
tgcli completions bash                   # Shell completions
tgcli wipe                               # Reset database (keeps auth)

Multi-Account

Use --store to manage multiple Telegram accounts:

tgcli --store ~/.tgcli-personal sync
tgcli --store ~/.tgcli-work chats list --output markdown
tgcli --store ~/.tgcli-bot messages list --chat 987654321

Output Formats

Always use markdown when available (recommended for LLMs and piping):

tgcli chats list                    # Human-readable table (default)
tgcli chats list --output markdown  # Markdown (recommended for LLMs/pipes)
tgcli chats list --output json      # JSON for parsing

Markdown advantages:

Readable structure (headers, bullet points, dividers)
Pipe to ripgrep/grep for filtering
Feed to LLMs for processing
Consistent across commands

Storage

Data stored in --store directory (default ~/.tgcli/):

~/.tgcli/session.db    # Telegram session & authentication
~/.tgcli/tgcli.db      # Messages, chats, contacts (FTS5-indexed)
~/.tgcli/media/        # Downloaded media files

Tips & Tricks

Search messages with ripgrep:

tgcli messages list --chat 987654321 --output markdown | rg "keyword"

Export to markdown file:

tgcli messages list --chat 987654321 --output markdown > exported.md

Sync multiple accounts in parallel:

for account in personal work bot; do
  tgcli --store ~/.tgcli-$account sync -q &
done
wait

tgcli