Full Telegram account control from the terminal. Agent-friendly, daemon-based, with webhook event push.

pipx install tlgr-cli
The command is tlgr; the distribution on PyPI is tlgr-cli, because the
shorter name was taken by an unrelated project. pipx is the recommendation
because tlgr runs a long-lived daemon and wants its own environment;
pip install tlgr-cli into a virtualenv works the same way. To track the
development tip instead, install from the repository:
pipx install git+https://github.com/tlgrcli/tlgr.git
For agents: logging in is a sequence of ordinary commands —
tlgr auth send-codethentlgr auth verify-code— so only reading the code needs a person. Secrets come from--x-env/--x-stdin/--x-file, never argv. See AGENT.md for the full agent reference.plugin/skills/tlgr/SKILL.mdis the same guidance as an Agent Skill for Claude Code, Codex, Cursor, OpenClaw and others:npx skills add tlgrcli/tlgr. In Claude Code it also installs as a plugin:claude plugin marketplace add tlgrcli/tlgr, thenclaude plugin install tlgr@tlgr.
Coming from tlgr 1.x with a running daemon? Stop it before you upgrade — two processes on one session file is how an authorization gets revoked. docs/UPGRADING.md is the ten-minute cutover, including the six output shapes an agent has to adapt to.
Quickstart
tlgr config init # create config files
tlgr login +15551234567 # authenticate (shortcut for account add)
tlgr daemon start # start background daemon
tlgr send @username "Hello from tlgr" # send a message
tlgr chats --limit 20 # list your chats
tlgr status # check daemon status
CLI
Every Telegram operation available as a single command. Three output modes: human-readable tables (default), JSON (--json) for agents, and plain TSV (--plain) for piping.
flowchart LR
USER["You / Agent"] --> CLI["tlgr CLI"]
CLI -->|"direct"| TG["Telegram API"]
CLI -->|"IPC socket"| DAEMON["tlgr daemon"]
DAEMON --> TG
Shortcuts
Common operations are available as top-level commands for quick access:
tlgr send <chat> <text> # message send
tlgr login <phone> # account add
tlgr logout <alias> # account remove
tlgr status # daemon status
tlgr chats # chat list
tlgr contacts # contact list
tlgr dl <chat> <msg_id>... # media download
tlgr up <chat> <path>... # media upload
Messages
tlgr message send <chat> <text> # --file, --caption, --reply-to, --silent, --parse,
# --schedule, --topic, --send-as, --split
tlgr message list <chat> # --limit, --cursor, --all, --since, --until
tlgr message get <chat> <msg_id> # full metadata
tlgr message delete <chat> <ids...>
tlgr message search <chat> <query> # --from, --media-type, --cursor
tlgr message pin <chat> <msg_id> # and: message unpin
tlgr message react <chat> <id> <emoji> # alias of `reaction add`, see Reactions
tlgr message read <chat> # --up-to
tlgr message edit <chat> <id> <text> # --typing N
tlgr message forward <from> <ids...> --to <chat>
tlgr message link <chat> <msg_id> # shareable t.me link
tlgr message entity list <text> # --parse md: what the formatting actually did
No comments yet.