How to Setup and Use tg-cli to Sync and Automate Telegram from the Terminal (2026)

For developers, system administrators, and AI developers, interacting with Telegram through mobile or desktop apps can be a bottleneck. While Telegram offers a robust official Bot API, it is restricted to bot accounts. If you want to automate your personal Telegram account, search your messages locally, or build script triggers based on your own chats, you need to interface with Telegram's client protocol: MTProto. In 2026, the premier tool for this is tg-cli (popularly known as kabi-tg-cli), a modern command-line client that syncs your chats locally to a SQLite database and provides powerful commands for searching, exporting, and sending messages.

Why tg-cli (kabi-tg-cli) is the Modern Frontier for Telegram Terminal Automation

Previously, developers relied on legacy userbot frameworks or the unmaintained C++ vysheng/tg command-line client. However, those older tools are prone to protocol bugs and account bans. The new tg-cli by jackwener is a modern, lightweight client built using MTProto. It is designed around a local-first architecture: instead of querying Telegram's servers for every search or action, it synchronizes your message history into a local SQLite database. This allows lightning-fast regex search, message exporting, and direct AI agent integration without hitting rate limits.

Satoshi App 🧡🪂 | HashCards

Group 62,863

Satoshi App is your one-stop platform for airdrops and minings. Discover cutting-edge blockchain projects. You can seize the opportunities to become an early adopter.Join Channel:https://t.me/CoreHoneycomb

Tech & Coding Common

Join Group

Gold Club

Group 32,846

Welcome to Goldclub, where high-tech meets high energy. We are a premium electronic tech brand, but this community? This is your playground.We built this space to integrate high energy with high value, creating a loyalty hub that actually gives back.

Tech & Coding United States

Join Group

NetVRk | Official

Group 6,112

NetVRk is a UE5 metaverse built on the blockchain that allows users to Play & Earn via NFTs. Explore the #AI-driven future of #web3 with our $NETVR token 🚀https://www.netvrk.co/Rules: Type #rules in chatBe respectful towards others!

Tech & Coding United States

Join Group

 jailbreakOS™ 🇧🇷

Group 3,222

Grupo pra trocar experiências sobre Jailbreak para iOS . Nosso canal: @CydiaBrasilGrupo sobre iPhone @iPhoneBRGrupo sobre beta @betaOSCanal sobre Apple @iOSBrasil⋅ Respeite as regras. (!rules)

Tech & Coding Brazil

Join Group

Открытый Исходный Кот (ex. Перейти в АйТи)

Group 1,635

Чат единомышленников, интересующихся работой в айти или уже работающих в этом направлении.Чат строго модерируется: мат, хамство, грубости, токсичность недопустимы.YouTube: https://youtube.com/@ОткрытыйИсходныйКотhttps://nometa.xyz/

Tech & Coding Russia

Join Group

Show count: 5 Listings 10 Listings 20 Listings 50 Listings

Load More Listings

Prerequisites for Setting Up tg-cli

Before installing the client, you must obtain your official Telegram API credentials. This connects the command-line client to your account via the secure MTProto layer:

1. Navigate to the official Telegram Developer Portal.
2. Log in using your phone number (including international prefix) and confirm the code sent to your Telegram app.
3. Go to API development tools.
4. Create a new application (you can enter any dummy name and website, e.g., "Terminal Automation").
5. Copy your App api_id (an integer) and App api_hash (a 32-character hex string). Keep these keys secret!

Step 1: Installing tg-cli (kabi-tg-cli)

The tool requires Python 3.10 or higher. The recommended installation method is using uv (a fast Python package installer) or pipx to isolate the tool dependencies globally.

Option A: Install using uv (Recommended)

# Install uv if you haven't already
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Install kabi-tg-cli
uv tool install kabi-tg-cli

Option B: Install using pipx

pip install pipx
pipx ensurepath
pipx install kabi-tg-cli

Step 2: Configuration and Authentication

With the CLI installed, you must configure the environment variables with your API keys. You can save these to a .env file in your working directory or set them globally in your terminal.

# On Windows PowerShell
$env:TG_API_ID="YOUR_API_ID_HERE"
$env:TG_API_HASH="YOUR_API_HASH_HERE"

# On Linux or macOS
export TG_API_ID="YOUR_API_ID_HERE"
export TG_API_HASH="YOUR_API_HASH_HERE"

Now, run the initialization command to log in to your Telegram account. The client will prompt you for your phone number and the login code sent to your active Telegram application.

tg chats

Step 3: Synchronizing Telegram Chats Locally

To populate your local SQLite cache database, use the sync command. This command fetches recent chat histories, media metadata, and sender details, saving them locally.

# Sync recent messages (fetches latest dialogs)
tg sync

# Sync specific chat by ID or username
tg sync --chat "fosscommunity"

Step 4: Common Command Line Operations

Once synchronized, you can interact with Telegram entirely from the command line. Here are the most useful commands:

1. List Joined Chats

tg chats --limit 10

2. Search Message History Locally

Search through your synced database with high speed using keywords or regular expressions.

# Simple keyword search
tg search "database backup"

# Search with regex and limit results
tg search --regex "error|failed" --limit 5

3. Send Messages and Files

# Send a text message to a user or group
tg send "fosscommunity" "Deployment script completed successfully!"

# Send a photo or document
tg send "fosscommunity" --file "./logs/report.pdf" --caption "Daily report"

4. Export Chat Logs to JSON

Export conversation logs to JSON for analysis or model training.

tg export --chat "fosscommunity" --output "./backup/foss_chat.json"

Step 5: Automating Sync with a systemd Timer

If you want to keep your SQLite database constantly updated, you can schedule the tg sync command to run periodically in the background. On Linux systems, this is best accomplished using a systemd user service and timer:

1. Create a service file at ~/.config/systemd/user/tg-sync.service:

[Unit]
Description=Sync Telegram messages to local SQLite database
After=network.target

[Service]
Type=oneshot
Environment="TG_API_ID=YOUR_API_ID_HERE"
Environment="TG_API_HASH=YOUR_API_HASH_HERE"
ExecStart=%h/.local/bin/tg sync
StandardOutput=journal

2. Create a timer file at ~/.config/systemd/user/tg-sync.timer:

[Unit]
Description=Run Telegram Sync every 15 minutes

[Timer]
OnBootSec=5min
OnUnitActiveSec=15min

[Install]
WantedBy=timers.target

3. Enable and start the timer:

systemctl --user daemon-reload
systemctl --user enable --now tg-sync.timer

Frequently Asked Questions (FAQ)

Conclusion

The transition toward local-first developer tools makes tg-cli (kabi-tg-cli) a must-have utility for anyone building automation workflows or integrating AI agents with Telegram. By caching your message history in SQLite, you unlock full-text searching, backup capabilities, and API-less integration. Follow our steps to obtain credentials, configure the environment, and automate the database sync. Explore the Telekit Tech & Coding Category to find other active groups and channels focusing on Python, Linux, and custom scripting tools!