Tlgr

CLI for Telegram — agent-friendly, daemon-based, with webhook event push.

LLM Mart 8 views 716k listing impressions

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

tlgr in a terminal: listing message event types, parsing Markdown into Telegram entities as JSON, the read-receipt policy, and the stable exit codes

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-code then tlgr 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.md is 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, then claude 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

From the project's README.

Comments (0)

Sign in to join the conversation.

No comments yet.