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
| Section | Description |
|---|---|
| 01. Installation | Requirements, installing globally from GitHub with uv tool install |
| 02. Authentication | Getting api_id/api_hash, login, logout, current account |
| 03. Configuration | TGUSER_* variables, file locations |
| 04. Chat Management | Named chat aliases (chat add/list/…) |
| 05. Sending Messages | Text, files, photos, videos, audio, contacts, and more |
| 06. AI Agent Integration | Calling tguser globally, exit codes, the ready-made Agent Skill |
| 07. Troubleshooting | Common errors and how to fix them |
| 08. Chat Discovery | How 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 messageAfter 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.sessionor~/.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.