tlgr CLI
A CLI for driving a Telegram account from the terminal: a daemon, JSON output for agents, webhook events and a Claude Code skill.
- 199 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent gets full access to the Telegram account: reading, sending and deleting messages in your name.
- The session file opens the account, and two processes on it can get authorization revoked.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/tlgrDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent gets full access to the Telegram account: reading, sending and deleting messages in your name.
- The session file opens the account, and two processes on it can get authorization revoked.
This is third-party code. Review the repository files before installing.
What it does
tlgr gives full access to a Telegram account from the command line. Every operation is a separate command: sending and searching messages, chats, contacts, media download and upload, forwarding, reactions and scheduling. There are three output modes: tables for humans, JSON (`--json`) for agents and TSV (`--plain`) for pipelines. The daemon `tlgr daemon start` holds the session and takes commands through an IPC socket, and events can be pushed to a webhook. Login is ordinary commands, `tlgr auth send-code` and `tlgr auth verify-code`, so a person only needs to read the code. Secrets pass through `--x-env`, `--x-stdin` or `--x-file`, never through arguments. The repository includes a `tlgr` skill for Claude Code, Codex, Cursor and OpenClaw and a Claude Code plugin.
Who it is for. Developers and channel admins who want to drive their own Telegram account from scripts and through an agent.
Good fit when
- An agent must send a message or file to a chat in your name on command.
- You need chat history search with JSON output for further processing.
- Incoming messages should go to a webhook as events.
- Messages need scheduling and forwarding between chats from a YAML job.
Not a fit when
- You need a bot with a BotFather token: tlgr acts as you, under a user account.
- The account cannot be handed to an agent: it gets full control over your messages.
- You want to message strangers in bulk: that breaks Telegram rules.
Example request
Use tlgr to find the latest messages about the release in my chats and show the result as JSON.Limitations
The agent gets full control of your account: reading, sending and deleting messages, so keep confirmations and grant access only to a trusted client. Two processes on one session file can get authorization revoked, so stop the daemon before upgrading from 1.x. The session is stored in a local file, so protect it. Login needs a code from Telegram that a person reads. The PyPI package is named `tlgr-cli`. The last commit dates to October 2026.
How to disable. Stop the daemon, run `tlgr logout` to sign out of the account, then `pipx uninstall tlgr-cli`. Also end the session in Telegram settings.
FAQ
How do I install tlgr?
Run `pipx install tlgr-cli`. The command is `tlgr` and the PyPI package is `tlgr-cli` because the short name was taken.
How do I add the skill?
With `npx skills add tlgrcli/tlgr`. Claude Code also has a plugin: `claude plugin marketplace add tlgrcli/tlgr`, then `claude plugin install tlgr@tlgr`.
How do I log in?
Run `tlgr config init`, then `tlgr login +15551234567` and `tlgr daemon start`. A person reads the code from Telegram.
How do I pass secrets?
Through `--x-env`, `--x-stdin` or `--x-file`, never through command line arguments.
What about upgrading from 1.x?
Stop the running daemon first: two processes on one session file can get authorization revoked. The order is in `docs/UPGRADING.md`.
Discussion
No questions or reviews yet.
Related
CLI toolsUntether bridges Claude Code, Codex and OpenCode with Telegram: voice or text tasks, live progress, approvals with buttons.
A Telegram bot drives Claude Code on your computer: you message the chat and the agent edits the project and streams the reply.
Connects Claude Code, Cursor, Codex or OpenCode to Telegram, Slack and Discord: teammates message a bot, an agent replies
Upgrade for the official Claude Code Telegram plugin: voice messages, live progress, buttons, memory and an agents board
A plugin that makes Claude Code a background assistant: scheduled tasks, Telegram, Discord and Slack replies, a web dashboard.
A CLI that keeps Claude Code agents running around the clock in PTY sessions, steered from Telegram, a dashboard and cron.
README in short
The README starts with pipx install and an agent note, then shows a quickstart and the CLI plus daemon scheme. Message commands and other Telegram operations follow.