Skip to content
Documentation

Documentation

tguser is a CLI tool for sending messages to Telegram as a user (MTProto protocol, not a bot). It lets you write to private chats, groups, and channels like a regular person, while named chat identifiers are stored locally in SQLite (similar to git remote).

Stack: Python 3.13 · uv · Kurigram (a Pyrogram fork) · Typer + Rich · Pydantic-Settings · SQLAlchemy 2.0 (async) + SQLite.

Table of Contents

SectionDescription
01. InstallationRequirements, installing globally from GitHub with uv tool install
02. AuthenticationGetting api_id/api_hash, login, logout, current account
03. ConfigurationTGUSER_* variables, file locations
04. Chat ManagementNamed chat aliases (chat add/list/…)
05. Sending MessagesText, files, photos, videos, audio, contacts, and more
06. AI Agent IntegrationCalling tguser globally, exit codes, the ready-made Agent Skill
07. TroubleshootingCommon errors and how to fix them
08. Chat DiscoveryHow to find a chat’s ID (dialogs, resolve)

Quick Start

uv tool install git+https://github.com/yerza06/tguser-cli.git   # install globally from GitHub
tguser login                           # sign in to your account
tguser chat add work -1001234567890    # save a chat under the name "work"
tguser send "Hello" --to work          # send a message

After uv tool install the tguser command is available from any directory — no uv run needed. For installing from a clone and the development workflow (uv sync + uv run), see 01. Installation.

⚠️ Never delete ~/.config/tguser/tguser.session or ~/.config/tguser/tguser.db — they hold your Telegram authorization and your saved chats. What these files are, why they matter, and what happens if you delete them: 03. Configuration.

See also the short overview in the root README.md.