tgcli – Telegram CLI

Description

--- name: tgcli description: Telegram CLI for syncing, searching, sending messages, and managing chats. Pure Rust implementation with no TDLib dependency. Supports multi-account setups, local FTS5 search, media download, scheduled messages, and real-time daemon mode. Use for interacting with Telegram from the command line or in scripts. --- # tgcli – Telegram CLI Pure Rust Telegram client. No TDLib. Fast. Cross-platform. ## Quick Start ```bash 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). ```bash 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. ```bash 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. ```bash 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. ```bash 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. ```bash tgcli contacts list --output markdown # List contacts (markdown) tgcli contacts search "Alice" # Search by name ``` ### Users Show user info, block/unblock. ```bash 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. ```bash 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. ```bash 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. ```bash 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. ```bash 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 ```bash 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: ```bash 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): ```bash 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:** ```bash tgcli messages list --chat 987654321 --output markdown | rg "keyword" ``` **Export to markdown file:** ```bash tgcli messages list --chat 987654321 --output markdown > exported.md ``` **Sync multiple accounts in parallel:** ```bash for account in personal work bot; do tgcli --store ~/.tgcli-$account sync -q & done wait ``` ## Links - GitHub: https://github.com/dgrr/tgcli - Crates.io: https://crates.io/crates/tgcli

Security Status