Skip to content

tg-agent-cli

A browse-first Telegram bot operator scaffold centered on a local projection database and CLI.

The recommended interoperable split is:

  • call-baxter handles webhook ingress, polling, scheduling, and generic rule execution
  • tg-agent-cli owns the Telegram projection database and browse-first CLI

The design assumes Telegram updates are ephemeral and update-driven, so the main state surface is a local SQLite database that normalizes chats, users, messages, callback queries, media assets, reactions, poll schedules, poll runs, actions, and audits.

Highlights

  • browse-friendly SQLite schema with message/media/action/callback separation
  • pydantic-settings based CLI with nested subcommands
  • media persistence policy with skip, file, and blob storage modes
  • poll scheduling and hook registry extension points
  • direct Telegram Bot API adapter for live status and outbound actions
  • generated Telegram API models kept at the API edge

Quickstart

python -m venv .venv
. .venv/bin/activate
pip install -e .[dev]
pytest -q

TGCLI_BOT_TOKEN=123456:abc tg --database-url ./state.db status

Operator examples

tg --database-url ./state.db chats list
tg --database-url ./state.db messages list --chat-ref chat:-1001234567890
tg --database-url ./state.db message show msg:-1001234567890/9811
tg --database-url ./state.db callbacks list
tg --database-url ./state.db media list --message-ref msg:-1001234567890/9811
TGCLI_BOT_TOKEN=123456:abc tg send text --chat-ref chat:-1001234567890 --text "hello there"

Integration note

Live operator commands such as tg send text should use the direct Telegram Bot API path by default and persist their own action history into tg.db. Reactive or scheduled behavior belongs in call-baxter rules/actions.

See docs/cli.md, docs/architecture.md, docs/schema.md, and docs/call-baxter-integration.md for the scaffold contract.