swtormy/tgbot-cli

A command-line tool for the Telegram Bot API and your own Telegram account (MTProto), built for AI agents. One binary, no server, JSON in and out.
tgbot is an unofficial, independent project and is not affiliated with, endorsed by, or sponsored by Telegram.
Inspired by Google's Gemini API CLI.
bash
export TELEGRAM_BOT_TOKEN="123456:ABC..." # from @BotFather
tgbot send 123456789 "build finished"
An agent with a shell (Claude Code, Cursor, Grok Build, Codex, and others) can call every Bot API method with it. There is no MCP server to run and no tool schemas sitting in the agent's context. The agent learns the commands from the binary itself, only when it needs them.
Two modes in one binary:
| | Bot mode (tgbot send ...) | User mode (tgbot user ...) |
| Acts as | a bot from @BotFather | your own Telegram account |
| Login | a token in an environment variable | once, with a code from your Telegram app |
| Good for | notifications, bot workflows | reading and searching your chats, replying as you, watching for messages |
| Docs | this page | docs/USER_MODE.md |
## Install
macOS and Linux:
bash
curl -fsSL https://raw.githubusercontent.com/swtormy/tgbot-cli/main/scripts/install.sh | bash
Or with Go:
bash
go install github.com/swtormy/tgbot-cli/cmd/tgbot@latest
Prebuilt binaries for macOS, Linux and Windows are on the releases page.
### Download a release binary
Pick the archive for your OS and CPU from a GitHub release (draft releases are visible to repo collaborators until published):
| Platform | Archive |
| Linux x86_64 | tgbot_linux_amd64.tar.gz |
| Linux arm64 | tgbot_linux_arm64.tar.gz |
| macOS Intel | tgbot_darwin_amd64.tar.gz |
| macOS Apple Silicon | tgbot_darwin_arm64.tar.gz |
| Windows x86_64 | tgbot_windows_amd64.zip |
| Windows arm64 | tgbot_windows_arm64.zip |
Each archive contains the tgbot binary (.exe on Windows), LICENSE, NOTICE, THIRD_PARTY_NOTICES, and full dependency license texts under third_party_licenses/. Verify the download against checksums.txt from the same release:
bash
curl -fsSLO https://github.com/swtormy/tgbot-cli/releases/download/vX.Y.Z/checksums.txt
curl -fsSLO https://github.com/swtormy/tgbot-cli/releases/download/vX.Y.Z/tgbot_linux_amd64.tar.gz
grep ' tgbot_linux_amd64.tar.gz$' checksums.txt | sha256sum -c -
tar -xzf tgbot_linux_amd64.tar.gz
./tgbot_linux_amd64/tgbot --version
Replace vX.Y.Z with the tag you downloaded. On macOS without GNU sha256sum, use shasum -a 256 -c the same way.
## Quick start
1. Create a bot with @BotFather and export its token as TELEGRAM_BOT_TOKEN.
2. Send the bot a message so it can write to you back, then read your chat id:
bash
tgbot updates --jq '.updates[].message.chat.id'
3. Send something:
bash
tgbot send 123456789 "hello from tgbot"
tgbot sendPhoto --chat_id 123456789 --photo @cat.jpg --caption "meow"
Every call can be previewed first with --dry-run. It needs no token and prints the request that would be sent.
## Give it to your agent
The skill is built into the binary, so one command installs it:
bash
tgbot skill install # ./.claude/skills/tgbot/SKILL.md (Claude Code)
tgbot skill install --agent cursor --global
tgbot skill install --agent grok
tgbot skill install --agent agents # shared .agents/skills folder