English · Русский
A CLI tool for sending messages to Telegram as a user account (MTProto protocol, not a bot) — built for AI agents such as Hermes-Agent, OpenClaw, Claude Code, Codex CLI and the like.
An agent can write to private chats, groups and channels like a regular person, while named chat
identifiers are stored locally in SQLite (similar to git remote).
Python 3.13 · uv · Kurigram (a Pyrogram fork) · Typer + Rich · Pydantic-Settings · SQLAlchemy 2.0 (async) + aiosqlite.
Straight from GitHub — no need to clone the repository:
uv tool install git+https://github.com/yerza06/tguser-cli.gitIf you already have a clone (or want to change the code):
git clone https://github.com/yerza06/tguser-cli.git
cd tguser-cli
uv tool install .The command builds the package, creates an isolated environment for it in
~/.local/share/uv/tools/tguser/ and puts the executable into ~/.local/bin/tguser. After that
tguser runs from any directory — no uv run, no need to be in the repository root. That is
exactly what AI agents need: their working directory is not known in advance.
uv tool install git+https://github.com/yerza06/tguser-cli.git --force # update to the latest version
uv tool install . --force # reinstall after code changes (from a clone)
uv tool install -e . # editable mode: edits apply immediately
uv tool uninstall tguser # removeFor developing the tool itself uv sync is enough — then you run it as uv run tguser … from the
project root. Details: Installation.
Get your api_id and api_hash at https://my.telegram.org (the API development tools section),
then sign in:
tguser login # asks for api_id/api_hash and phone number (if unset), and the code
tguser whoami # show the current account
tguser logout # sign out and delete the session
tguser version # version, config path and whether a session existsCredentials are stored in ~/.config/tguser/.env, the session in ~/.config/tguser/tguser.session,
and the chat database in ~/.config/tguser/tguser.db.
⚠️ Never delete~/.config/tguser/tguser.sessionor~/.config/tguser/tguser.db. They are the tool's working state: your Telegram authorization and every saved chat name. They cannot be restored automatically — once deleted you have to go throughtguser loginagain and re-add every alias by hand. To sign out, usetguser logoutrather than deleting the file. More details in Configuration.
You can also set the environment variables manually (see .env.example):
export TGUSER_API_ID=1234567
export TGUSER_API_HASH=0123456789abcdef0123456789abcdef
export TGUSER_PHONE_NUMBER=+15551234567 # optional: skips the phone prompt in `login`tguser chat add work -1001234567890 # add an alias
tguser chat list # table of all chats (or just `tguser chat`)
tguser chat get-id work # print the ID
tguser chat replace-id work -100999 # replace the ID
tguser chat rename work team # rename
tguser chat remove team # deleteThe target (--to) is a saved chat name, a numeric ID, an @username, or me (Saved Messages).
All media commands support two syntaxes — flags and positional arguments:
# Text
tguser send "Hello" --to work
tguser send "Hello" work
# Photos (several are sent as an album), with a caption
tguser sendphoto a.png b.png --to work --caption "Photos"
tguser sendphoto a.png b.png work "Photos"
# Documents (several can be grouped with -G/--group)
tguser sendfile report.pdf --to work --caption "Report"
tguser sendfile part1.pdf part2.pdf --to work --group
# Audio / video / voice / video note / sticker
tguser sendaudio track.mp3 --to me
tguser sendvideo clip.mp4 me "Clip"
tguser sendvoice voice.ogg --to me
tguser sendvideonote note.mp4 --to me
tguser sendsticker sticker.webp --to me
# Contact
tguser sendcontact --phone +77001234567 --first-name John --last-name Smith --to work
tguser sendcontact +77001234567 John Smith workThe repository ships a ready-made Agent Skill — a description of the tool that an agent loads by itself as soon as a task involves Telegram. One command to install:
npx skills add https://github.com/yerza06/tguser-cli --skills tguserThe installer asks which agents to set the skill up for and puts it into the right directory
(~/.claude/skills/ for Claude Code, ~/.codex/skills/ for Codex CLI, ~/.agents/skills/ for
Cline/Zed/Warp and so on). The skill follows the open
Agent Skills specification, so it works in any agent that
supports it.
Source: skills/tguser/; details in
AI Agent Integration.
The skill cannot sign in to an account:
tguser loginis run once by a human.
src/tguser/
├── cli.py # root Typer application
├── config.py # Pydantic-Settings
├── client.py # Kurigram client + run_async
├── console.py # Rich output helpers
├── resolver.py # alias from the DB → chat_id
├── db/ # models and CRUD (SQLAlchemy async)
└── commands/ # auth / chat / send
skills/tguser/ # Agent Skill (skills.sh)
├── SKILL.md # short instructions + frontmatter
└── references/ # full flag tables and troubleshooting
site/ # documentation website (Hugo + Hextra → GitHub Pages)
├── hugo.yaml
└── content/ # landing page + docs, English and Russian
Once the Python prototype is solid — a possible port of the CLI to Rust (Typer → clap, Kurigram → grammers/tdlib).