Skip to content
Back to search

tlgr

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tlgrcli--tlgr/badge.svg)](/listings/tlgrcli--tlgr)

HTML

<a href="/listings/tlgrcli--tlgr"><img src="/api/listings/tlgrcli--tlgr/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "tlgr",
  3. "description": "The tlgr plugin for Claude Code: Telegram from the terminal, through the tlgr CLI.",
  4. "owner": {
  5. "name": "tlgrcli",
  6. "url": "https://github.com/tlgrcli"
  7. },
  8. "strict": true,
  9. "plugins": [
  10. {
  11. "name": "tlgr",
  12. "source": "./plugin",
  13. "description": "Read and act on a personal Telegram account through the tlgr CLI.",
  14. "strict": true
  15. }
  16. ]
  17. }
README.md · README · 918 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # tlgr
  2. <p align="center"><img src="assets/brand/logo-512.png" width="160" alt="tlgr logo"></p>
  3. <p align="center"><a href="https://www.producthunt.com/products/tlgr"><img src="https://img.shields.io/badge/Product_Hunt-Live_now-DA552F?style=for-the-badge&logo=producthunt&logoColor=white" alt="tlgr is live on Product Hunt"></a></p>
  4. Full Telegram account control from the terminal. Agent-friendly, daemon-based, with webhook event push.
  5. <p align="center"><img src="assets/demo/tlgr-demo.gif" width="720" alt="tlgr in a terminal: listing message event types, parsing Markdown into Telegram entities as JSON, the read-receipt policy, and the stable exit codes"></p>
  6. ```
  7. pipx install tlgr-cli
  8. ```
  9. The command is `tlgr`; the distribution on PyPI is `tlgr-cli`, because the
  10. shorter name was taken by an unrelated project. `pipx` is the recommendation
  11. because tlgr runs a long-lived daemon and wants its own environment;
  12. `pip install tlgr-cli` into a virtualenv works the same way. To track the
  13. development tip instead, install from the repository:
  14. ```
  15. pipx install git+https://github.com/tlgrcli/tlgr.git
  16. ```
  17. > **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](AGENT.md) for the full agent reference.
  18. > [`plugin/skills/tlgr/SKILL.md`](plugin/skills/tlgr/SKILL.md) is the same guidance as an [Agent Skill](https://agentskills.io) for Claude Code, Codex, Cursor, OpenClaw and others: `npx skills add tlgrcli/tlgr`.
  19. > In Claude Code it also installs as a plugin: `claude plugin marketplace add tlgrcli/tlgr`, then `claude plugin install tlgr@tlgr`.
  20. > **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](docs/UPGRADING.md) is the ten-minute cutover, including the six output shapes an agent has to adapt to.
  21. ## Quickstart
  22. ```bash
  23. tlgr config init # create config files
  24. tlgr login +15551234567 # authenticate (shortcut for account add)
  25. tlgr daemon start # start background daemon
  26. tlgr send @username "Hello from tlgr" # send a message
  27. tlgr chats --limit 20 # list your chats
  28. tlgr status # check daemon status
  29. ```
  30. ## CLI
  31. 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.
  32. ```mermaid
  33. flowchart LR
  34. USER["You / Agent"] --> CLI["tlgr CLI"]
  35. CLI -->|"direct"| TG["Telegram API"]
  36. CLI -->|"IPC socket"| DAEMON["tlgr daemon"]
  37. DAEMON --> TG
  38. ```
  39. ### Shortcuts
  40. Common operations are available as top-level commands for quick access:
  41. ```bash
  42. tlgr send <chat> <text> # message send
  43. tlgr login <phone> # account add
  44. tlgr logout <alias> # account remove
  45. tlgr status # daemon status
  46. tlgr chats # chat list
  47. tlgr contacts # contact list
  48. tlgr dl <chat> <msg_id>... # media download
  49. tlgr up <chat> <path>... # media upload
  50. ```
  51. ### Messages
  52. ```bash
  53. tlgr message send <chat> <text> # --file, --caption, --reply-to, --silent, --parse,
  54. # --schedule, --topic, --send-as, --split
  55. tlgr message list <chat> # --limit, --cursor, --all, --since, --until
  56. tlgr message get <chat> <msg_id> # full metadata
  57. tlgr message delete <chat> <ids...>
  58. tlgr message search <chat> <query> # --from, --media-type, --cursor
  59. tlgr message pin <chat> <msg_id> # and: message unpin
  60. tlgr message react <chat> <id> <emoji> # alias of `reaction add`, see Reactions
  61. tlgr message read <chat> # --up-to
  62. tlgr message edit <chat> <id> <text> # --typing N
  63. tlgr message forward <from> <ids...> --to <chat>
  64. tlgr message link <chat> <msg_id> # shareable t.me link
  65. tlgr message entity list <text> # --parse md: what the formatting actually did
  66. ```
  67. `message send` supports `--typing N` / `--typing-auto` to show a realistic
  68. "typing…" indicator before the message lands. Text over 4096 UTF-16 units is
  69. refused unless you pass `--split`.
  70. That is the everyday tenth of the group. It also has `preview`, `compose`,
  71. `summarize`, `translate`, `transcribe`, `report`, `thread list`, `view get`,
  72. `read-receipt list`, `scheduled send`, `paid set`, `fact-check set`,
  73. `dice list`, `effect list`, `game *`, `sponsored *`, `suggested *` and
  74. `tone *` — 43 operations in all, generated from one registry, with generated
  75. reference in [`docs/reference/message.md`](docs/reference/message.md).
  76. `msg` is an alias for `message` (e.g. `tlgr msg send @user "hello"`).
  77. ### Polls, reactions, checklists and places
  78. ```bash
  79. tlgr poll create <chat> "Lunch?" Pizza Sushi # --quiz --correct N, --multiple,
  80. # --public-voters, --duration 2h
  81. tlgr poll vote <chat> <msg_id> 0 # answers are addressed by index
  82. tlgr poll get <chat> <msg_id> # results, and why you cannot vote
  83. tlgr poll close <chat> <msg_id> --yes
  84. tlgr reaction add <chat> <msg_id> 👍 # keeps the reactions you already had
  85. tlgr reaction remove <chat> <msg_id> # all of mine
  86. tlgr reaction user list <chat> <msg_id> # who reacted, per emoji
  87. tlgr reaction chat set <chat> --some 👍,❤ # what this chat allows (admin)
  88. tlgr todo create <chat> "Release" "tag it" "ship it"
  89. tlgr todo toggle <chat> <msg_id> --done 1 --undone 2
  90. tlgr location send <chat> -- <lat> <lon>
  91. tlgr location live start <chat> -- <lat> <lon> --period 1h
  92. tlgr search global "release notes" # every chat, one cursor
  93. ```
  94. Three things worth knowing before scripting these. A poll answer is an opaque
  95. identifier on the wire, so tlgr resolves your index against the server's own
  96. copy — `--shuffle` cannot make index 1 mean two answers. `sendReaction` carries
  97. your *whole* reaction set, so `reaction add` reads what is there and resends
  98. it rather than replacing it, and `mine` in the reply is the set afterwards. A
  99. checklist task id is never renumbered, because completions are keyed by it.
  100. Anything that spends Stars — `reaction pay`, `search post` past its free quota
  101. — has no default amount and refuses to run without an explicit one.
  102. Generated reference: [`poll`](docs/reference/poll.md),
  103. [`reaction`](docs/reference/reaction.md), [`todo`](docs/reference/todo.md),
  104. [`location`](docs/reference/location.md), [`search`](docs/reference/search.md).
  105. ### Drafts
  106. Prepare a reply without sending it — you send (or discard) it later from any
  107. Telegram client. The human-in-the-loop primitive for agents.
  108. ```bash
  109. tlgr draft set <chat> <text> # --reply-to, --parse
  110. tlgr draft clear <chat> # --all --yes to clear every draft
  111. tlgr draft list # all non-empty drafts across chats
  112. ```
  113. `draft set` returns the saved draft, and `draft list` reports marked chat ids
  114. (`-100…` for channels) with `raw_id` beside them. See
  115. [`docs/reference/draft.md`](docs/reference/draft.md).
  116. ### Chats
  117. ```bash
  118. tlgr chat list # --folder, --type, --search, --unread, --pinned, --muted
  119. tlgr inbox # shortcut: chat list (add --unread)
  120. tlgr catchup # every unread chat with its recent messages, read-only
  121. tlgr chat open <chat> # history AND a read receipt; --no-read to peek
  122. tlgr chat read <chat>... # the receipt without the history; --folder, --from-file
  123. tlgr chat unread <chat> # the undo for an accidental receipt
  124. tlgr chat get <chat> # --full for getFullUser/getFullChat/getFullChannel
  125. tlgr chat posters <chat> # distinct senders + message counts, walked internally
  126. tlgr chat archive <chat>... [--undo] # one RPC for any number of peers
  127. tlgr chat mute <chat> --for 8h # or --until, --forever, --off, --stories, --folder
  128. tlgr chat pin <chat>... [--unpin] # --folder pins inside a chat folder; --order rewrites it
  129. tlgr chat clear <chat> --yes # history goes, chat stays
  130. tlgr chat delete <chat> --yes # --for-both, or --for-everyone if you own it
  131. tlgr chat leave <chat>... --yes # --delete-history, --remove-from-folders
  132. tlgr chat typing <chat> # --action record-audio, upload-photo, …
  133. tlgr chat notify set <chat> --silent on
  134. tlgr chat ttl set <chat> 1d # auto-delete timer; omit the period to read it
  135. tlgr chat theme set <chat> --emoji 🌷
  136. tlgr chat wallpaper set <chat> --slug pattern
  137. tlgr chat badge get --limits # the unread badge, and the chat-list limits behind it
  138. tlgr chat report <chat> --spam --yes
  139. ```
  140. Members, admins, invites and topics:
  141. ```
  142. tlgr chat member list <chat> --filter admins # `chat members` still works
  143. tlgr chat member ban <chat> @spammer --purge --report --yes
  144. tlgr chat member restrict <chat> @noisy --deny send-media --until 7d
  145. tlgr chat admin promote <chat> @alice --rights ban-users,delete-messages
  146. tlgr chat permission list --mask member # the canonical right names
  147. tlgr chat permission set <chat> --deny send-stickers
  148. tlgr chat invite create <chat> --limit 25 --expires 7d
  149. tlgr chat request approve <chat> --all --yes
  150. tlgr chat topic create <chat> Releases # the id `--topic` takes
  151. tlgr chat setting set <chat> --slow-mode 30s --hidden-members on
  152. tlgr chat create <name> --type supergroup # --members, --photo, --username
  153. tlgr chat stats get <channel> --load-graphs
  154. tlgr boost add <channel>
  155. ```
  156. `chat list` returns a page of dialogs whose peer is nested under `chat`;
  157. `chat catchup` and `chat list` never emit a read receipt, `chat open` does on
  158. purpose, and `chat unread` restores only your own badge. A member row keeps
  159. its participant wrapper (status, rank, promoter, both rights masks) and every
  160. mask is allow-polarity, so `chat permission get` round-trips straight back
  161. into `chat permission set`. Full reference:
  162. [`docs/reference/chat.md`](docs/reference/chat.md).
  163. ### Folders
  164. A chat folder is a filter, not a container, so every edit rewrites the whole
  165. filter in one call — and `--folder <name|id>` works on `chat list`,
  166. `chat read`, `chat mute`, `chat pin` and `chat badge get`.
  167. ```bash
  168. tlgr folder list --with-counts
  169. tlgr folder create Work --groups --emoji 💼
  170. tlgr folder add Work @alice # --pin to pin it inside the folder
  171. tlgr folder remove Work @alice --exclude
  172. tlgr folder reorder main Work Family
  173. tlgr folder join t.me/addlist/SLUG # previews; --chats/--all-chats to actually join
  174. tlgr folder share set Work --all-eligible
  175. ```
  176. Full reference: [`docs/reference/folder.md`](docs/reference/folder.md).
  177. ### Contacts
  178. ```bash
  179. tlgr contact list # --with-status --sort last-seen --export vcard --out FILE
  180. tlgr contact add <user|+phone> [name] # --first-name --last-name --note --share-phone
  181. tlgr contact rename <user> # --first-name, --last-name (tags non-contacts too)
  182. tlgr contact remove <user>... # --phone reaches numbers with no account
  183. tlgr contact search <query> # --mine-only --global-only --recent
  184. tlgr contact note set <user> <text> # --clear
  185. tlgr contact status list # online / last-seen for every contact, in one call
  186. tlgr contact birthday list
  187. tlgr contact close-friends list|set
  188. tlgr contact blocked list|set # --stories for the story blocklist
  189. tlgr contact top list|set # frequent contacts, by category
  190. tlgr contact import <file.vcf|csv> # bulk phonebook import
  191. tlgr contact sync <file> # diff a phonebook against the server (--apply)
  192. tlgr contact saved list # every number ever uploaded, account or not
  193. tlgr contact share <user> --to <chat>
  194. tlgr contact share-phone <user> # irreversible
  195. ```
  196. An empty `contact add` by phone is **ambiguous** — the number may have no
  197. account, or its owner may refuse lookups by phone — and `reason` says so
  198. rather than the reply claiming "no such user".
  199. ### Users
  200. ```bash
  201. tlgr user get <user> # --full --translate-bio LANG --from-chat/--from-message
  202. tlgr user dialog-status <user> # does THIS account have prior history with them?
  203. tlgr user hide-stories <user>... # v1's spelling of `story hide` (--unhide)
  204. tlgr user block <user> # --stories --report-spam --delete-history
  205. tlgr user unblock <user>
  206. tlgr user can-message <user>... # free | premium | paid (and the Stars price)
  207. tlgr user chat list <user> # groups you share (--leave-all)
  208. tlgr user link <user> # --profile --text; `me --token` for a contact token
  209. tlgr user photo list|set <user>
  210. tlgr user music list <user>
  211. tlgr user personal-channel get <user>
  212. tlgr user birthday set <user> <date>
  213. ```
  214. `dialog-status` distinguishes "yes", "definitively no", and "cannot tell"
  215. (exit 13) instead of guessing. Never infer "no history" from an entity
  216. resolution error — see AGENT.md for why.
  217. `hide-stories` is idempotent: it reads the current flag first and reports
  218. `already: true` without an RPC, so a bulk pass over hundreds of peers is
  219. nearly free to repeat.
  220. ### Resolving references
  221. ```bash
  222. tlgr resolve peer <ref>... # @username | id | +phone | t.me link | me
  223. tlgr resolve username <name>
  224. tlgr resolve phone <+number> # --offline formats and validates, no RPC
  225. tlgr resolve link <url> # classify any t.me / tg:// link (--open)
  226. tlgr resolve cache get # inspect the per-account peer database
  227. ```
  228. `resolve link` never *acts*: it says what a link is and names the command
  229. that would follow it in `delegated_to`. A phone lookup that comes back empty
  230. exits 13, never 5 — no account and a privacy refusal are indistinguishable.
  231. ### Stories
  232. ```bash
  233. tlgr story feed list # the stories bar (--hidden, --unread-only)
  234. tlgr story list <chat> # active; --profile, --archive, --album ID
  235. tlgr story get <chat> <id> # --views, --link, --areas-out, --translate
  236. tlgr story post <file>... # --caption, --privacy, --allow, --exclude,
  237. # --period, --pin, --album, --area-url, …
  238. tlgr story read <chat> # clears YOUR ring; --register-view to be seen
  239. tlgr story react|reply|share <chat> <id>
  240. tlgr story pin|unpin|hide|unhide <chat> [<id>...]
  241. tlgr story viewer list <chat> <id> # --contacts, --q, --csv PATH
  242. tlgr story blocklist set <user>... # "Hide my stories from"
  243. tlgr story album create|edit|list|delete|reorder <chat> …
  244. tlgr story can-post | stealth set | search | stats get | export | live start | watch
  245. ```
  246. `story read` clears your own unread ring and tells the poster nothing;
  247. `--register-view` is what puts you in their viewer list, and it is opt-in.
  248. `--privacy` sets the base audience and `--allow`/`--exclude` layer exceptions
  249. on top, in that order, so "contacts, except Bob" is expressible.
  250. ### Media, stickers, GIFs and emoji
  251. ```bash
  252. tlgr media get <chat> <msg_id> # kind, size, duration, ids — no download
  253. tlgr media download <chat> <msg_id>... # --out-dir, --thumb, --range, --resume,
  254. # --connections, --verify, --all, --read
  255. tlgr media upload <chat> <path>... # --as, --caption, --spoiler, --album,
  256. # --ttl, --no-send, --dedupe, --paid-stars
  257. tlgr media list <chat> --type photo # the shared-media tabs
  258. tlgr media search <query> # across every chat
  259. tlgr media export <chat> # resumable archive with a manifest
  260. tlgr media transfer list|stop|retry # the Downloads panel
  261. tlgr media limit get # the server's own limits, never guessed
  262. tlgr sticker set list|get|add|remove # install / uninstall a set
  263. tlgr sticker pack create|add|edit # a pack you own (`emoji set …` too)
  264. tlgr sticker fave|recent|search
  265. tlgr gif list|add|remove|search|send
  266. tlgr emoji get|list|search
  267. ```
  268. A file's `file_reference` expires in hours, so every command that touches
  269. bytes re-fetches its source first; `media file-id get --source` is how a
  270. stored id is made usable again.
  271. ### Calls and video chats
  272. tlgr speaks the **signalling** half of calls and carries no audio or video: it
  273. rings, answers, hangs up, mutes, moderates, records and observes, and nobody
  274. can hear it. Every answer says so (`"media": "none"`).
  275. ```bash
  276. tlgr call start @alice # --video, --check (rings nothing), --wait
  277. tlgr call accept <call> # --ack-only marks it received (busy-lock)
  278. tlgr call decline <call> # --reason missed|busy, --reply "can't talk"
  279. tlgr call end <call> # --reason, --duration
  280. tlgr call log list # the Calls tab; --missed, --with @alice
  281. tlgr call watch # who is ringing, as NDJSON, for a notifier
  282. ```
  283. ```bash
  284. tlgr vc create <chat> --yes # video chat, livestream or --rtmp
  285. tlgr vc get <chat> # state, recording, limits, stream channels
  286. tlgr vc participant list <chat> # --raised-hands, --video
  287. tlgr vc mute <chat> [@alice] # --for-me; `vc unmute` = "allow to speak"
  288. tlgr vc link <chat> --speaker # invite links; `vc rtmp get` for the key
  289. tlgr vc watch <chat> # the only way to read the in-call chat
  290. tlgr vc download <chat> --out live.ogg # record a livestream (it cannot play one)
  291. ```
  292. ```bash
  293. tlgr conference create # a t.me/call/<slug> link, no crypto needed
  294. tlgr conference invite <call> @alice # rings them; falls back to the link
  295. tlgr conference decline <msg_id> # refuse, or cancel an invite you sent
  296. ```
  297. Conferences are end-to-end encrypted. Reading, ringing and revoking are
  298. complete; **joining**, **removing somebody** and **sending inside** need a
  299. signed `e2e.chain` block that tlgr cannot build — pass one with `--block` and
  300. `--public-key`, or the command exits 2 naming what is missing.
  301. ### Bots, inline mode, mini apps and payments
  302. ```bash
  303. tlgr bot get <bot> # the profile card: commands, menu, flags
  304. tlgr bot list --owned|--similar-to|--popular-apps|--recent
  305. tlgr bot start <bot> --param <payload> # /start with a hidden deep-link payload
  306. tlgr bot command send <bot> start # '@botusername' added in a group
  307. tlgr bot press <chat> <msg_id> --button 0
  308. tlgr bot url-auth get|accept|decline # Telegram Login, inspected before granted
  309. tlgr bot menu|permission|access|preview|affiliate|verification|token …
  310. tlgr inline query <bot> <query> # @bot query, the bot's own paging
  311. tlgr inline send <bot> <q> --chat <c> --pick 0
  312. tlgr inline search gif|venue|image # the built-in bots, named by the server
  313. tlgr webapp get|open|send|invoke|watch # mini apps; `open` prints the URL only
  314. tlgr payment form get|receipt get|info get|card get
  315. tlgr payment invoice export|send # asking someone else to pay
  316. tlgr payment subscription list|set # cancel or resume a Star subscription
  317. ```
  318. Three things this group does *not* do, on purpose:
  319. - **It never pays.** `sendPaymentForm`, `sendStarsForm`, `validateRequestedInfo`
  320. and `fulfillStarsSubscription` are absent from the surface, not hidden behind
  321. a flag. `payment form get` reports `payable_here: false` and says why.
  322. - **It never opens a browser.** `webapp open` prints the signed mini-app URL,
  323. which carries your init data and is a credential, not a link.
  324. - **It never presses a button that discloses something without being told to.**
  325. A phone number, a location, a chat or a poll each needs its own flag;
  326. without one tlgr prints what it would send and exits 2.
  327. ### Profile, privacy and notifications
  328. ```bash
  329. tlgr profile get # --no-full skips the userFull round trip
  330. tlgr profile update # --first-name, --last-name, --bio, --birthday, --channel
  331. tlgr profile photo set avatar.jpg # --video, --emoji ID, --photo-id ID, --fallback
  332. tlgr profile username set ada # --check, --on/--off, --order a,b
  333. tlgr profile status set 5301 # --until +7d, --clear
  334. tlgr profile color set 5 # --profile, collectible:<slug>
  335. tlgr profile presence set online # tlgr reports neither unless asked
  336. tlgr profile link --qr # --collectible for the Fragment record
  337. tlgr privacy get [key] # omit for every key
  338. tlgr privacy set last-seen contacts --add-disallow @nosy
  339. tlgr privacy global set --hide-read-marks on
  340. tlgr privacy blocked list|set @spammer # --unblock, --stories
  341. tlgr notify get private # or groups|channels|stories|reactions|<chat>
  342. tlgr notify set private --mute 2h # --unmute, --sound ringtone:ID, --preview off
  343. tlgr notify exception list|clear
  344. tlgr notify ringtone list|set chime.ogg
  345. ```
  346. ### Settings, business, Premium, Stars and gifts
  347. ```bash
  348. tlgr settings get # every cloud key, each with what its setter accepts
  349. tlgr settings set auto-delete 1w # sensitive-content, top-peers, browser, language…
  350. tlgr settings theme list|install Nord
  351. tlgr settings language list
  352. tlgr business get # hours, location, intro, greeting, away, links, bots
  353. tlgr business set --tz Europe/London --open 'mon-fri 09:00-18:00'
  354. tlgr business reply add hello --text "Hi! I will reply shortly."
  355. tlgr business bot set @mybot --reply-to --read --new-chats # no --all, by design
  356. tlgr premium status | premium feature list --limits
  357. tlgr stars balance get | stars transaction list --out
  358. tlgr gift list | gift get msg:120 | gift set msg:120 --pin
  359. tlgr giveaway get @channel 42 | giveaway code apply <slug>
  360. ```
  361. tlgr never spends money: the commands that would need a payment form signed
  362. report the price and stop.
  363. ### Accounts
  364. ```bash
  365. tlgr account add <phone> # starts the login; prints the verify-code line to run next
  366. tlgr account add --bot --token-env TLGR_BOT_TOKEN --alias helper
  367. tlgr account import <file.session> # import an existing Telethon session (no re-auth); --alias
  368. tlgr account export <alias> --out ./work.string
  369. tlgr account list # (* = default)
  370. tlgr account switch <alias>
  371. tlgr account logout <alias> # revokes the authorization on the server
  372. tlgr account remove <alias> # local only, unless --logout
  373. tlgr account rename <old> <new>
  374. tlgr account info [alias]
  375. tlgr account check [alias] # authorized / revoked / banned / frozen / offline
  376. tlgr account sync [alias] # refresh stored profile from live Telegram
  377. ```
  378. `info`, `check` and `sync` take the alias positionally, but also honor the
  379. global `-a/--account` flag; with neither, they fall back to the active
  380. account. Session files are stored `0600` — they are full account credentials,
  381. and so is anything `account export` produces, which is why it writes to a
  382. `0600` file unless `--stdout` says you meant to print it.
  383. **`logout` is not `remove`.** `logout` revokes the authorization server-side
  384. (v1 never did, so a removed account went on showing in every other client's
  385. Devices list) and keeps the alias so you can log back in; `remove` deletes the
  386. local record and says, in its answer, that the server-side session is still
  387. alive unless you passed `--logout`.
  388. ### Logging in
  389. ```bash
  390. tlgr auth send-code <phone> --alias work --api-id 12345 --api-hash-env TLGR_API_HASH
  391. tlgr auth verify-code <code> --alias work --password-env TLGR_2FA_PASSWORD
  392. tlgr auth qr --alias work # streams tg://login tokens until one is approved
  393. tlgr auth recover # forgot the cloud password (recovery email)
  394. tlgr auth code list # the login code Telegram sent this account (chat 777000)
  395. tlgr auth tos # read the Terms of Service; --accept is a separate run
  396. ```
  397. The pending login lives in the daemon — which owns the session file, so two
  398. processes never open it at once — and is mirrored to
  399. `<account>/login-state.json` at `0600`, which is what lets the two steps run
  400. minutes apart. `auth verify-code` exits 4 when the account has a cloud
  401. password and none was supplied: add `--password-env` and re-run the same line.
  402. ### Sessions, passwords and connected websites
  403. ```bash
  404. tlgr account session list [--unconfirmed] [--pending-password]
  405. tlgr account session terminate <hash>... | --all-others [--deny]
  406. tlgr account session confirm <hash> # "yes, it's me"
  407. tlgr account session set <hash> --calls off # --secret-chats, --auto-terminate 6m
  408. tlgr account session accept-qr 'tg://login?token=…' # approve another device
  409. tlgr account password get [--verify] # 2FA status; --password-env to reveal the recovery address
  410. tlgr account password set --new-password-env TLGR_2FA_NEW_PASSWORD --hint "…"
  411. tlgr account password change --password-env … --new-password-env …
  412. tlgr account password remove --password-env … --yes
  413. tlgr account website list # a *different* list from Devices
  414. tlgr account website revoke <hash>... [--block-bot]
  415. tlgr account passkey list # auditable; a CLI can never create one
  416. tlgr account ttl set 12m # delete my account if I am away this long
  417. ```
  418. `account session list` derives two fields you cannot get by hand:
  419. `deny_deadline` (after it, Telegram auto-confirms an unrecognised login for
  420. you) and `sensitive_actions_eligible_at` (what `SESSION_TOO_FRESH_X` counts
  421. down to). `password change` refuses when the account stores Telegram Passport
  422. documents unless `--keep-passport` acknowledges that they will be lost — the
  423. secure secret is encrypted under the password and tlgr does not implement the
  424. KDF that would re-encrypt it.
  425. ### Daemon
  426. ```bash
  427. tlgr daemon start # --foreground, --catch-up/--no-catch-up
  428. tlgr daemon stop # drains in-flight work rather than killing it
  429. tlgr daemon status # running/ready/healthy, per-account state and lag
  430. tlgr daemon restart # --grace 10s
  431. tlgr daemon reconnect # force a reconnect and a catch-up
  432. tlgr daemon save-state # flush pts/qts and the entity cache now
  433. tlgr daemon logs --follow --level warning
  434. tlgr daemon flood list # rate-limit deadlines this install still owes
  435. tlgr daemon dead-letter list # events no consumer could be given
  436. tlgr daemon install # LaunchAgent on macOS, systemd --user on Linux
  437. ```
  438. ### Watching events
  439. ```bash
  440. tlgr watch # v1's default: new messages
  441. tlgr watch --events all --account all # everything, every connected account
  442. tlgr watch --events read,message_reactions --chat @alice
  443. tlgr watch --since 91820 --print-cursor
  444. tlgr events list --group message # the vocabulary --events accepts
  445. tlgr events get message_new # payload, source constructors, sequence box
  446. ```
  447. Push-driven from the daemon's event bus, not polled: the daemon already holds
  448. the update socket, so a watcher is a bounded queue on it. 114 event types
  449. cover every `Update*` constructor the pinned Telethon can parse — a message
  450. edit, a deletion, a read receipt, a reaction, a typing indicator and every
  451. service message included. v1's `watch` polled `chat list` and `message list`
  452. every two seconds and could only report new messages.
  453. Frames are NDJSON, one per line: exactly one `meta` first, exactly one `end`
  454. last, and events, `heartbeat`, `gap` and `lag` in between. A `gap` frame says
  455. how many events the replay window lost — a number rather than silence.
  456. `--results-only` prints v1's `{event_type, chat_id, data}` line shape.
  457. ### Update state
  458. ```bash
  459. tlgr sync status --channels # pts/qts/seq, per-channel table, lag
  460. tlgr sync catch-up # replay what was missed while offline
  461. tlgr sync difference --chat @news # run getDifference by hand (read-only)
  462. tlgr sync reset # give up on the gap and re-baseline
  463. tlgr sync backfill @news --from-id 91800 --to-id 91900
  464. ```
  465. `catch-up` replays a gap; `reset` gives up on one. Neither is `chat catchup`,
  466. which is the unread digest a human reads.
  467. ### Network and proxies
  468. ```bash
  469. tlgr net status # DC, transport, proxy, latency, clock offset
  470. tlgr net ping --probes 5
  471. tlgr net dc list --ipv6
  472. tlgr proxy add 'tg://proxy?server=1.2.3.4&port=443&secret=dd00' --set
  473. tlgr proxy test --every --reorder
  474. ```
  475. SOCKS5, HTTP and MTProxy; `tg://proxy` and `t.me/proxy` links both parsed.
  476. Credentials live in `~/.tlgr/proxies.json` at mode 0600 and never reach argv
  477. or a listing. `proxy test` probes through a throwaway in-memory session, so a
  478. probe can never become the account's update-receiving connection.
  479. #### Protocol v2
  480. The CLI reaches the daemon over `~/.tlgr/daemon.sock`, created `srw-------`
  481. with the connecting peer's uid checked on every request — v1 left it
  482. world-writable with no authentication at all.
  483. - **The account is always explicit.** The CLI resolves it (`-a` →
  484. `TLGR_ACCOUNT` → `[accounts] default` → active alias) and sends it. The
  485. daemon never picks one: with two accounts configured, v1 used whichever
  486. alias came first out of a set, so you could send from the wrong identity
  487. with no signal.
  488. - **Handshake, and one restart.** A client newer than the running daemon
  489. restarts it exactly once and says so on stderr; `--no-daemon-restart`
  490. refuses instead (exit 11). Two `tlgr` commands racing with no daemon
  491. running produce exactly one daemon.
  492. - **`status` distinguishes alive from working.** `running` is a live process;
  493. `ready` is a daemon that can serve; `healthy` is one whose accounts are
  494. actually working. An account whose connection dropped is `degraded` and its
  495. requests answer exit 8 with a hint instead of `Cannot send requests while
  496. disconnected`; a revoked session is `needs_login` and answers exit 4.
  497. - **A live home is protected.** A tlgr home with a `.production` marker file
  498. is refused unless `TLGR_ALLOW_PRODUCTION_HOME=1`: two processes sharing one
  499. home share session files, and Telegram revokes an auth key it sees two
  500. clients on.
  501. ### Global Flags
  502. ```
  503. --json JSON to stdout (for scripting and agents)
  504. --plain Stable TSV for piping
  505. -a, --account TEXT Account alias to use
  506. --results-only In JSON mode, strip envelope and emit only the primary result
  507. --select FIELDS In JSON mode, project comma-separated fields (supports dot paths)
  508. --enable-commands Comma-separated allowlist of enabled commands (sandboxing)
  509. -n, --dry-run Preview destructive operations without executing
  510. -y, --force Skip confirmations
  511. --no-input Never prompt; fail instead (CI/agent mode)
  512. -v, --verbose Verbose logging to stderr
  513. --version / --help
  514. ```
  515. ### Environment Variables
  516. All global flags can be set via environment variables:
  517. | Variable | Equivalent |
  518. |----------|------------|
  519. | `TLGR_JSON=1` | `--json` |
  520. | `TLGR_PLAIN=1` | `--plain` |
  521. | `TLGR_ACCOUNT=alias` | `--account alias` |
  522. | `TLGR_ENABLE_COMMANDS=cmd1,cmd2` | `--enable-commands cmd1,cmd2` |
  523. | `TLGR_AUTO_JSON=1` | Auto-switch to JSON when stdout is piped (non-TTY) |
  524. ## Webhook -- Event Push
  525. tlgr pushes Telegram events to an external HTTP endpoint in real time. Designed for agentic interfaces like [OpenClaw](https://github.com/openclaw) where an agent receives events and calls `tlgr` CLI commands to act.
  526. ```mermaid
  527. flowchart LR
  528. TG["Telegram"] --> DAEMON["tlgr daemon"]
  529. DAEMON -->|"POST /hooks/agent"| AGENT["Your Agent"]
  530. AGENT -->|"tlgr --json message send ..."| CLI["tlgr CLI"]
  531. CLI --> TG
  532. ```
  533. Configure it with `tlgr webhook set`, which validates every event name against
  534. the taxonomy — a name nobody recognises used to be dropped silently, so the
  535. webhook delivered nothing and never said why:
  536. ```bash
  537. tlgr webhook set --url https://example.com/hooks/agent \
  538. --events message_new,message_edited,message_deleted \
  539. --secret-env TLGR_WEBHOOK_SECRET --enabled
  540. tlgr webhook get # configuration and delivery health; secrets redacted
  541. tlgr webhook test # one delivery, with the exact headers it sent
  542. ```
  543. Or edit `~/.tlgr/webhook.toml` directly. Deliveries carry:
  544. | Header | Meaning |
  545. |---|---|
  546. | `X-Tlgr-Signature` | `sha256=<hmac of the exact body>` — verify over the bytes you received |
  547. | `X-Tlgr-Delivery` | unique per attempt; reused on a re-drive, so it is an idempotency key |
  548. | `X-Tlgr-Seq` | the event's per-account sequence number |
  549. | `X-Tlgr-Event` | the event type |
  550. | `X-Tlgr-Account` | the account alias |
  551. Events arrive as `{"event": <envelope>, "delivery_id": "..."}`:
  552. ```json
  553. {
  554. "event": {
  555. "seq": 91824,
  556. "ts": "2026-09-03T09:14:07Z",
  557. "account": "main",
  558. "type": "message_new",
  559. "payload": { "...": "..." },
  560. "chat_id": -1001234567890
  561. },
  562. "delivery_id": "0f3c…"
  563. }
  564. ```
  565. A delivery that fails every attempt is dead-lettered rather than dropped;
  566. `tlgr daemon dead-letter list` shows them and `daemon dead-letter send`
  567. re-drives them.
  568. ## Gateway -- Background Jobs
  569. tlgr also ships with a deterministic, always-on Gateway that runs background jobs on your Telegram account. Define declarative pipelines in `~/.tlgr/jobs.yaml` that automatically react to incoming messages -- auto-reply, auto-forward, filter by chat type, time of day, content, and more.
  570. ```mermaid
  571. flowchart LR
  572. TG["Telegram event"] --> F["Filters"]
  573. F -->|"passed"| P["Processors"]
  574. P --> A["Actions"]
  575. A --> R["reply / forward / ..."]
  576. ```
  577. A few examples of what you can do:
  578. ```yaml
  579. jobs:
  580. # Auto-reply to all private messages
  581. - name: private-bot
  582. account: main
  583. filters:
  584. chat_type: private
  585. actions:
  586. - reply: "shut up i'm just a bot!"
  587. # Forward breaking news to your archive
  588. - name: news-forward
  589. account: main
  590. filters:
  591. chat_id: "@raw_feed"
  592. types: [text, photo]
  593. contains: [breaking]
  594. actions:
  595. - forward:
  596. to: ["@clean_feed", "@archive"]
  597. processors: [strip_formatting]
  598. # Night-mode auto-reply
  599. - name: night-mode
  600. account: main
  601. filters:
  602. chat_type: private
  603. time_of_day: "23:00-07:00"
  604. actions:
  605. - reply: "I'm sleeping. Will reply tomorrow."
  606. ```
  607. Filters support full AND / OR / NOT composition, 20+ built-in filter types, 7 text processors, and a registry pattern for adding your own.
  608. For the full Gateway reference -- filters, processors, actions, composition, extensibility -- see **[Gateway documentation](tlgr/gateway/README.md)**.
  609. ## Agent / Automation
  610. tlgr is designed to be consumed by LLM agents and automation pipelines.
  611. ### Machine-readable schema
  612. ```bash
  613. tlgr schema # full CLI schema as JSON
  614. tlgr schema message send # schema for a specific command
  615. ```
  616. Agents can discover all commands, flags, positionals, types, and defaults
  617. without parsing `--help`. For commands generated from the operation registry
  618. the schema also carries JSON Schema (draft 2020-12) for the request *and* the
  619. response, plus a generated example — so a call can be validated before it is
  620. made. `tlgr agent whoami --json` reports `output_schema_version: 2`.
  621. ### Feature parity
  622. ```bash
  623. tlgr agent parity # coverage of the pinned Telegram feature catalog
  624. tlgr agent parity --json --uncovered # every gap, by priority and domain
  625. ```
  626. The answer to "can tlgr do X yet" without guessing. 2.0.0 covers 1788 of
  627. 1797 catalogued behaviours and all 178 P0 ones; the nine that remain are
  628. individually waived and each names the MTProto method this build has no
  629. request class for. Nothing in the report is hand-maintained — it is computed
  630. from the registry — and the same report is generated into
  631. [`docs/reference/PARITY.md`](docs/reference/PARITY.md).
  632. ### JSON envelope
  633. Every command wraps its answer — there is no hand-written command left to
  634. answer any other way:
  635. ```json
  636. {"ok": true, "op": "message.send", "result": {...}, "meta": {"request_id": "...", "elapsed_ms": 42}}
  637. {"ok": false, "error": {"error": "...", "code": "RATE_LIMITED", "exit_code": 7, "wait_seconds": 30}}
  638. ```
  639. `--results-only` prints the inner value in either case, which is v1's shape;
  640. `--select` projects fields by dot path. Paginated operations return
  641. `{items, has_more, next_cursor, total}` with an opaque signed cursor.
  642. ### Stable exit codes
  643. ```bash
  644. tlgr exit-codes # print the exit code table
  645. tlgr --json agent exit-codes # as JSON
  646. ```
  647. | Code | Meaning |
  648. |------|---------|
  649. | 0 | Success |
  650. | 1 | Generic failure |
  651. | 2 | Usage / parse error |
  652. | 3 | Empty results |
  653. | 4 | Auth required |
  654. | 5 | Not found |
  655. | 6 | Permission denied |
  656. | 7 | Rate limited |
  657. | 8 | Retryable error |
  658. | 10 | Config error |
  659. | 11 | Daemon error |
  660. | 12 | IPC error |
  661. | 13 | Indeterminate (unknown — not a negative) |
  662. | 130 | Interrupted (SIGINT) |
  663. ### Command sandboxing
  664. Restrict which commands an agent can run:
  665. ```bash
  666. tlgr --enable-commands="message,chat,schema" send @user "hi" # allowed
  667. tlgr --enable-commands="message,chat,schema" account remove foo # blocked (exit 2)
  668. ```
  669. Or via environment: `TLGR_ENABLE_COMMANDS=message,chat,schema`.
  670. For generated commands the allowlist is matched by canonical operation id and
  671. enforced **inside the daemon**, so an alias cannot be used to get past it
  672. (`--enable-commands message.list` permits `tlgr msg list`), and a blocked
  673. operation exits 6. It is a usability guard, not a sandbox: anything that can
  674. reach the socket can reach the session. See [SECURITY.md](SECURITY.md).
  675. ### JSON transforms
  676. ```bash
  677. tlgr --json --results-only chat list # strip pagination/envelope, emit only the chat array
  678. tlgr --json --select "chat.id,unread_count" chat list # project specific fields
  679. ```
  680. ### Auto-JSON for pipelines
  681. Set `TLGR_AUTO_JSON=1` and tlgr automatically outputs JSON whenever stdout is piped (non-TTY), without requiring `--json`.
  682. ### Error hints
  683. Errors include actionable recovery hints:
  684. ```
  685. Error: No session found for account 'main'
  686. Session expired. Run: tlgr account add <phone>
  687. ```
  688. ## Configuration
  689. Config files live in `~/.tlgr/`:
  690. | File | Format | Purpose |
  691. |------|--------|---------|
  692. | `config.toml` | TOML | App defaults, daemon, accounts |
  693. | `jobs.yaml` | YAML | Gateway job definitions |
  694. | `webhook.toml` | TOML | Outbound webhook push |
  695. ```bash
  696. tlgr config init # create defaults
  697. tlgr config validate # check syntax + validate filter/action names
  698. tlgr config path # print config directory
  699. tlgr config keys # list all known config keys
  700. tlgr config list # show current values
  701. tlgr config get <key> # get a single value
  702. tlgr config set <key> <value> # set a value
  703. tlgr config unset <key> # reset to default
  704. ```
  705. ### config.toml
  706. ```toml
  707. [defaults]
  708. output = "human"
  709. [accounts]
  710. default = "main"
  711. [daemon]
  712. auto_start = true
  713. log_level = "info"
  714. ```
  715. ## Multi-Account
  716. ```bash
  717. tlgr account add +15551234567 --alias personal # then: tlgr auth verify-code <code> --alias personal
  718. tlgr account add +15559876543 --alias work
  719. tlgr -a personal message send @friend "Hi"
  720. ```
  721. There is no cap on accounts (official apps stop at three). `tlgr auth code
  722. list -a personal` reads the login code Telegram delivered to *that* account's
  723. service chat, which is how a second account can be onboarded without anyone
  724. reading a phone.
  725. To eliminate wrong-account mistakes in scripts and agents, enable strict
  726. account selection — every command must then carry an explicit `-a <alias>`
  727. (no default-account fallback; violations exit 2):
  728. ```bash
  729. tlgr config set require_account true # or per-invocation: TLGR_REQUIRE_ACCOUNT=1
  730. ```
  731. Jobs can reference different accounts:
  732. ```yaml
  733. jobs:
  734. - name: work-forward
  735. account: work
  736. # ...
  737. ```
  738. ## Privacy
  739. tlgr runs on your machine and has no telemetry; it only talks to Telegram, and to a webhook or proxy if you configure one. See [PRIVACY.md](PRIVACY.md).
  740. ## License
  741. See [LICENSE](LICENSE) for license details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.