tg-state-cli

A stateful CLI client for Telegram with local SQLite database, written in TypeScript.

Features

• Local Database: All messages, chats, and users stored in SQLite with FTS support
• Sync Engine: Automatic or manual sync of Telegram data
• Multiple Output Formats: Markdown, JSON, JSONL, CSV, Table
• Full CLI: Complete set of commands for messaging, chats, users, media
• Background Daemon: Run as a background service with continuous sync

Installation

npm install
npm run build

Configuration

Copy config.example.yaml to ~/.config/tg-state-cli/config.yaml:

mkdir -p ~/.config/tg-state-cli
cp config.example.yaml ~/.config/tg-state-cli/config.yaml

Edit the config and add your Telegram API credentials from https://my.telegram.org.

Alternatively, use environment variables:

export TG_STATE_API_ID=12345678
export TG_STATE_API_HASH=your-api-hash

Usage

Authentication

# Login with phone number
tg-state-cli auth login -p +1234567890

# Verify with code
tg-state-cli auth verify 12345

# Check status
tg-state-cli auth status

# Login with bot token
tg-state-cli auth login -b BOT_TOKEN

Syncing

# Sync dialogs list
tg-state-cli sync dialogs

# Sync specific chat
tg-state-cli sync chat 1234567890

# Sync all chats
tg-state-cli sync all

# Start continuous sync
tg-state-cli sync start

Chats

# List chats
tg-state-cli chat list

# List with filters
tg-state-cli chat list -t group --unread

# Get chat info
tg-state-cli chat get 1234567890

# Create group
tg-state-cli chat create "My Group" -u 123,456,789

# Mark as read
tg-state-cli chat read 1234567890

Messages

# List messages
tg-state-cli msg list 1234567890

# Send message
tg-state-cli msg send 1234567890 "Hello!"

# Reply to message
tg-state-cli msg send 1234567890 "Reply" -r 123

# Edit message
tg-state-cli msg edit 1234567890 123 "Edited text"

# Delete messages
tg-state-cli msg delete 1234567890 123 124 125

# Search
tg-state-cli msg search "query"

# Add reaction
tg-state-cli msg react 1234567890 123 👍

Media

# Download media
tg-state-cli media download 1234567890 123 -o photo.jpg

# Send media
tg-state-cli media send 1234567890 photo.jpg -c "Caption"

Users

# Get user info
tg-state-cli user get 123456789

# Search users
tg-state-cli user search "username"

Query & Stats

# Chat statistics
tg-state-cli query stats 1234567890 -d 30

# Top posters
tg-state-cli query top 1234567890

# Activity timeline
tg-state-cli query activity 1234567890

# Media stats
tg-state-cli query media 1234567890

Database

# Show stats
tg-state-cli db stats

# Vacuum
tg-state-cli db vacuum

# Backup
tg-state-cli db backup backup.db

# Prune old data
tg-state-cli db prune 90

Daemon

# Start daemon
tg-state-cli daemon start

# Check status
tg-state-cli daemon status

# Stop daemon
tg-state-cli daemon stop

# Restart
tg-state-cli daemon restart

Export

# Export chat
tg-state-cli export chat 1234567890 -o chat.json

# Export as JSONL
tg-state-cli export chat 1234567890 -f jsonl -o chat.jsonl

# Export as CSV
tg-state-cli export chat 1234567890 -f csv -o chat.csv

Output Formats

# JSON output
tg-state-cli chat list -o json

# JSONL (one JSON per line)
tg-state-cli msg list 123 -o jsonl

# CSV
tg-state-cli user search test -o csv

# Table
tg-state-cli chat list -o table

# Include raw data
tg-state-cli chat get 123 --raw

Development

# Run in dev mode
npm run dev -- auth status

# Build
npm run build

# Type check
npm run typecheck

# Run tests
npm test

License

MIT