Commands

Every command, option and exit code. This page is generated from the program itself, so it cannot describe a version that does not exist. For the same list as JSON, run tg commands --json.

How a command line is built:

tg [profile] [options] <resource> <verb> [arguments]

The first word is the profile when it is not a command: tg work chats list lists the chats of profile work, and tg chats list those of the default profile. TG_PROFILE does the same for a whole shell session; without either, the profile is default.

Options for every command

Option	What it does
`-V, --version`	output the version number.
`-v, --verbose`	more detail in what is shown: -v ids, -vv everything we know. Default: `0`.
`--json`	machine-readable output: one JSON value on stdout, nothing else.
`--jsonl`	machine-readable output: one JSON object per line, for streaming and jq.
`--quiet`	diagnostics off; a failure is still said.
`--trace`	the connection's own log lines on stderr — never message content.
`--timeout <duration>`	give up on the whole command after this — 30s, 2m, 500ms.
`--offline`	answer from what was recorded and never connect; fails if nothing was.
`--yes`	go ahead without the question an ask level puts before a write.
`--record`	keep this run — ids and timings, never message content.
`--no-record`	do not keep it, whatever the configuration says.

`tg session`

log this profile in to Telegram, or out

`tg session start`

tg session start [method] [options]

Argument		What it is
`method`	optional	how to log in. One of: `qr`, `phone`. Default: `qr`.

Option	What it does
`--app <how>`	the first time only: how to get this profile's app from my.telegram.org. One of: `browser`, `auto`. Default: `browser`.
`--qr-file <png>`	write the QR code to this PNG instead of drawing it, for an agent to pass on.

`tg session end`

log this profile out on Telegram's side and forget the session here

Changes something in Telegram.

tg session end

`tg account`

the logged-in account

`tg account show`

who this profile is logged in as; the phone number shows its last four digits

tg account show [options]

Option	What it does
`--show-phone`	print the whole phone number.

`tg account update`

change the name, the description or the photo everyone sees on your profile

Changes something in Telegram.

tg account update [options]

Option	What it does
`--first-name <name>`	your first name.
`--last-name <name>`	your last name.
`--description <text>`	about you.
`--photo <file>`	a new profile photo — an image file.

`tg account sessions`

where else this account is logged in — not tg session, which is this tool's own login

`tg account sessions list`

every device and app logged in to this account; nothing is ended

tg account sessions list

`tg account sessions end`

log out every other device, your phone included; this one stays

Changes something in Telegram.

tg account sessions end [options]

Option	What it does
`--others`	every session but this one.

`tg chats`

the account's chats

`tg chats list`

chats, newest first, archived ones included

tg chats list [options]

Option	What it does
`--limit <n>`	how many to show.
`--page <n>`	which page, starting at 1.
`--all`	every row, no paging.
`--search <text>`	only chats whose name contains this; at least 3 characters.
`--kind <kind>`	only chats of this kind: dialog, group, channel, saved.
`--unread`	only chats with unread messages.

`tg chats events`

who joined, left, was added or removed, and by whom — from the chat's service messages

tg chats events <chat> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

Option	What it does
`--since-time <time>`	ISO 8601, or 2h / 1d ago; 7 days ago if not given.
`--type <names>`	only these, comma-separated: join, leave, add, remove, create, title, pin.

`tg chats inspect`

what an invite or public link leads to, without joining it

tg chats inspect <link>

Argument		What it is
`link`	required	an invite link or a public one.

`tg chats show`

one chat: its kind, unread count, last message time and who is in it

tg chats show <chat>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

`tg chats members`

who is in a group

`tg chats members list`

everyone in a group, a page at a time, with their role and when they were last seen

tg chats members list <chat> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

Option	What it does
`--limit <n>`	how many to show.
`--page <n>`	which page, starting at 1.
`--all`	every row, no paging.

`tg chats members add`

add people; they are told

Changes something in Telegram.

tg chats members add <chat> <person>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`person`	required	an id, or part of a name.

`tg chats members remove`

remove people; their messages stay

Changes something in Telegram.

tg chats members remove <chat> <person>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`person`	required	an id, or part of a name.

`tg chats mark-read`

mark a chat read; the other side sees that you read it

Changes something in Telegram.

tg chats mark-read <chat> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

Option	What it does
`--until <message>`	only up to this message id; the newest by default.

`tg chats create`

create a group or a channel; the people added are told

Changes something in Telegram.

tg chats create <title> [person] [options]

Argument		What it is
`title`	required	the group's name.
`person`	optional	people to add: an id, or part of a name.

Option	What it does
`--channel`	a private channel instead of a group; people join it by its link.

`tg chats join`

join a group or channel by its link; the others in it see that you joined

Changes something in Telegram.

tg chats join <link>

Argument		What it is
`link`	required	an invite link, or a public one.

`tg chats leave`

leave a group or channel; the others in it see that you left

Changes something in Telegram.

tg chats leave <chat>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

`tg chats update`

rename a group or channel, change its description, or turn one of its settings on or off

Changes something in Telegram.

tg chats update <chat> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

Option	What it does
`--title <title>`	the new name.
`--description <text>`	the new description.
`--all-can-pin <on\|off>`	every member may pin messages.
`--only-admins-add <on\|off>`	only admins may add members.

`tg chats link`

a group's invite link

`tg chats link show`

the invite link, if you may see it

tg chats link show <chat>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

`tg chats link reset`

replace the invite link; the old one stops working

Changes something in Telegram.

tg chats link reset <chat>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

`tg chats admins`

give or take back a member's admin rights

`tg chats admins add`

make a member an admin with these rights

Changes something in Telegram.

tg chats admins add <chat> <person> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`person`	required	an id, or part of a name.

Option	What it does
`--can <rights>`	what they may do, comma-separated: members, admins, info, pin, link, post, edit, delete.

`tg chats admins remove`

take an admin's rights back; they stay a member

Changes something in Telegram.

tg chats admins remove <chat> <person>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`person`	required	an id, or part of a name.

`tg chats folders`

your chat folders

`tg chats folders list`

your chat folders, in the order the app shows them

tg chats folders list

`tg chats folders create`

create a chat folder

Changes something in Telegram.

tg chats folders create <title> [options]

Argument		What it is
`title`	required	the folder's name; the app may refuse a long one.

Option	What it does
`--chat <chat>`	a chat to put in it, by id or name; repeat it for more.

`tg chats folders update`

rename a folder, or change which chats are in it

Changes something in Telegram.

tg chats folders update <folder> [options]

Argument		What it is
`folder`	required	folder id, or its title exactly.

Option	What it does
`--title <title>`	a new name.
`--add <chat>`	put a chat in it; repeat it for more.
`--remove <chat>`	take a chat out of it; repeat it for more.

`tg chats folders delete`

delete a folder; the chats in it stay

Changes something in Telegram.

tg chats folders delete <folder>

Argument		What it is
`folder`	required	folder id, or its title exactly.

`tg chats rules`

what chats moderate judges a group by, kept in a file of this profile

`tg chats rules show`

the group's rules; the defaults, marked not saved, if it has none yet

tg chats rules show <chat>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

`tg chats rules set`

change one rule; the group's first change writes every rule with its default

Changes something in Telegram.

tg chats rules set <chat> <key> <value>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`key`	required	one of: trusted, blocked, blockedNames, links, invites, forwards, blockedPeople, flood.messages, flood.minutes, flood.action, newAccount.days, newAccount.action, consent.delete, consent.remove.
`value`	required	the new value; a list is comma-separated.

`tg chats rules unset`

put one rule back to its default

Changes something in Telegram.

tg chats rules unset <chat> <key>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`key`	required	one of: trusted, blocked, blockedNames, links, invites, forwards, blockedPeople, flood.messages, flood.minutes, flood.action, newAccount.days, newAccount.action, consent.delete, consent.remove.

`tg chats moderate`

judge a group's new messages and members by its rules, and act as they allow

Changes something in Telegram.

tg chats moderate <chat> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

Option	What it does
`--since-time <time>`	judge what came after this ISO 8601 time, or 2h / 1d ago; the saved point stays.
`--dry-run`	judge and plan; do nothing.
`--allow-dangerous`	yes to every action whose level in the group's rules is ask.
`--max-actions <n>`	at most this many actions in one run; 10 if not given.

`tg contacts`

people this account has a one-to-one chat with

`tg contacts list`

people you have a one-to-one chat with

tg contacts list [options]

Option	What it does
`--limit <n>`	how many to show.
`--page <n>`	which page, starting at 1.
`--all`	every row, no paging.
`--order <recent\|name>`	newest conversation first, or alphabetical. Default: `recent`.
`--search <text>`	only people whose name or @username contains this.

`tg contacts show`

one person and the chats you share with them

tg contacts show <person>

Argument		What it is
`person`	required	their id, @username, or part of their name.

`tg contacts lookup`

who has this phone number — asks for it, or reads it from stdin; never an argument

tg contacts lookup

`tg contacts sync`

take the whole contact list from the messenger into the local store

tg contacts sync

`tg contacts add`

add a person to your contacts — contacts list still shows only people you have a dialog with

Changes something in Telegram.

tg contacts add <person>

Argument		What it is
`person`	required	person id — `contacts lookup` finds one — or part of a known name.

`tg contacts remove`

remove a person from your contacts; the chat stays, a name you gave them may not

Changes something in Telegram.

tg contacts remove <person>

Argument		What it is
`person`	required	person id — `contacts lookup` finds one — or part of a known name.

`tg contacts block`

stop a person from writing to you — they need not be a contact

Changes something in Telegram.

tg contacts block <person>

Argument		What it is
`person`	required	person id — `contacts lookup` finds one — or part of a known name.

`tg contacts unblock`

let a blocked person write to you again

Changes something in Telegram.

tg contacts unblock <person>

Argument		What it is
`person`	required	person id — `contacts lookup` finds one — or part of a known name.

`tg contacts rename`

give a person a name of your own — they do not see it

Changes something in Telegram.

tg contacts rename <person> <first-name> [last-name]

Argument		What it is
`person`	required	person id — `contacts lookup` finds one — or part of a known name.
`first-name`	required	the name you want to see for them.
`last-name`	optional

`tg contacts import`

upload phone numbers and add the people the messenger has under them

Changes something in Telegram.

tg contacts import <file>

Argument		What it is
`file`	required	one person per line: number, then a comma, a tab or a semicolon, then the name.

`tg messages`

read and send messages

`tg messages list`

a chat's messages, oldest to newest

tg messages list <chat> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

Option	What it does
`--limit <n>`	how many.
`--before-id <id>`	only messages older than this message id.
`--before-time <time>`	only messages older than this ISO 8601 time, or 2h / 1d ago.
`--after-id <id>`	only messages newer than this message id.
`--after-time <time>`	only messages newer than this ISO 8601 time, or 2h / 1d ago.
`--transcribe`	turn voice messages not heard yet into text — by the messenger, or a model on this machine; can take minutes.
`--model <id>`	which downloaded speech model hears them, with --transcribe; `models audio list` shows them.
`--mark-read`	also mark the chat read up to the newest message shown; the other person sees it.

`tg messages search`

search the local store — what was read, fetched or kept by serve; never asks the messenger

tg messages search <text> [options]

Argument		What it is
`text`	required	every word must appear, as a word or the start of one: квартир finds квартира.

Option	What it does
`--chat <chat>`	only this chat: a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`--limit <n>`	how many.
`--regex`	the words are one regular expression, case-insensitive, tested against every stored text.

`tg messages send`

send a text message; without [text], the text is read from stdin

Changes something in Telegram.

tg messages send <chat> [text] [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`text`	optional	the message.

Option	What it does
`--reply-to <message>`	answer this message, by its id in the same chat.
`--send-id <id>`	repeat a send whose outcome was unknown, without risking a second copy.
`--silent`	deliver without a notification.
`--no-preview`	no preview card for a link in the text.
`--md`	read bold, italic, ~~struck~~ and `code` in the text; \ keeps a mark literal.
`--file <file>`	attach a file; the text becomes its caption.
`--photo <file>`	attach a .jpg, .png or .webp as a photo; the text becomes its caption.
`--as-file`	send the --file as a file to download, a video included.
`--voice <file>`	send an Ogg Opus file as a voice message, alone, with no text.
`--allow-any-file`	send a file even from a hidden folder, ~/.ssh or this CLI's own folders.
`--at-time <time>`	let the messenger send it later, even with this machine off: 2026-09-25T09:00 (local time), or 30m, 2h, 1d from now.

`tg messages show`

one message, by its chat and id or by its msg: locator

tg messages show <chat> [message]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages; or a msg: locator, with no message id after it.
`message`	optional	the message id.

`tg messages context`

a message and what came either side of it, oldest first

tg messages context <chat> [message] [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages; or a msg: locator, with no message id after it.
`message`	optional	the message id.

Option	What it does
`--before-n <n>`	how many before it. Default: `5`.
`--after-n <n>`	how many after it. Default: `5`.

`tg messages download`

save a message's photos, files, videos and voice notes to a folder — or a whole chat's with --all

tg messages download <chat> [message] [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`message`	optional	the message id; left out with --all.

Option	What it does
`--output-dir <dir>`	where to save them; created if missing. Default: `.`.
`--all`	every file of the chat, newest first; run it again to continue where it stopped.
`--pause <duration>`	with --all, a pause between pages, to stay under the provider's limits. Default: `1s`.

`tg messages transcribe`

a voice message as text — by Telegram where it can, else by a model on this machine

tg messages transcribe <chat> <message> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`message`	required	the id of a voice message.

Option	What it does
`--local`	use the model on this machine, never the messenger.
`--model <id>`	which downloaded model; implies --local (`models audio list`).

`tg messages edit`

change the text of your own message; the other side may have read it already

Changes something in Telegram.

tg messages edit <chat> <message> [text] [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`message`	required	the id of your own message.
`text`	optional	the new text; without it, read from stdin.

Option	What it does
`--md`	read bold, italic, ~~struck~~ and `code` in the text; \ keeps a mark literal.

`tg messages delete`

delete messages for you only; with --for-everyone, for everyone in the chat

Changes something in Telegram.

tg messages delete <chat> <messages> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`messages`	required	the message ids, at most 10.

Option	What it does
`--for-everyone`	delete for everyone in the chat, not only for you — they cannot get it back.
`--allow-dangerous`	go ahead without the question an ask level puts before a deletion.

`tg messages forward`

forward one message to another chat

Changes something in Telegram.

tg messages forward <chat> <message> [options]

Argument		What it is
`chat`	required	the chat the message is in: a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`message`	required	the message id.

Option	What it does
`--to <chat>`	where it goes: a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`--silent`	deliver it without a notification.
`--send-id <id>`	repeat a forward whose outcome was unknown, without risking a second copy.

`tg messages pin`

pin a message in a chat, quietly unless --notify

Changes something in Telegram.

tg messages pin <chat> <message> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`message`	required	the message id.

Option	What it does
`--notify`	tell the chat's members about the pin.

`tg messages unpin`

unpin a message in a chat

Changes something in Telegram.

tg messages unpin <chat> <message>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`message`	required	the message id.

`tg messages scheduled`

messages waiting to be sent later in a chat, soonest first; cancel one in the app

tg messages scheduled <chat>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

`tg messages links`

why a message is in its conversation: each link it has, and the chain of answers back to the start

tg messages links <chat> <message>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`message`	required	the message id.

`tg reactions`

react to messages

`tg reactions add`

put your reaction on a message; it replaces the one you had

Changes something in Telegram.

tg reactions add <chat> <message> <emoji>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`message`	required	the message id.
`emoji`	required	one emoji, for example 👍.

`tg reactions remove`

take your reaction off a message

Changes something in Telegram.

tg reactions remove <chat> <message>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`message`	required	the message id.

`tg polls`

read a poll, vote in it, close your own, create one

`tg polls show`

a poll and its answer ids, as the message carries it now

tg polls show <chat> <message>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`message`	required	the id of the message that carries the poll.

`tg polls vote`

vote in a poll, or take your vote back; the others see it unless the poll is anonymous

Changes something in Telegram.

tg polls vote <chat> <message> [answers] [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`message`	required	the id of the message that carries the poll.
`answers`	optional	answer ids, as `polls show` prints them.

Option	What it does
`--retract`	take your vote back.

`tg polls close`

close your own poll; nobody can vote after that, and it cannot be reopened

Changes something in Telegram.

tg polls close <chat> <message>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`message`	required	the id of your own message that carries the poll.

`tg polls create`

send a poll to a chat, as a message of its own; public unless --anonymous

Changes something in Telegram.

tg polls create <chat> <question> <answers> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`question`	required	the question.
`answers`	required	two answers or more.

Option	What it does
`--multiple`	people may pick several answers.
`--anonymous`	nobody sees who voted for what.
`--revote`	people may change their vote.
`--silent`	send without a notification.
`--send-id <id>`	repeat a create whose outcome was unknown, without risking a second poll.

`tg models`

models that run on this machine

`tg models audio`

speech models for transcribing voice messages

`tg models audio list`

the speech models, most suitable first, which are downloaded, and which one is the default

tg models audio list

`tg models audio download`

download a speech model once, checked against the sha256 this version expects

tg models audio download <model>

Argument		What it is
`model`	required	a model id from `models audio list`.

`tg inbox`

other people's unread messages in every chat; --new for what arrived since the last check

tg inbox [options]

Option	What it does
`--new`	what arrived since the last check, each message once — for scheduled runs.
`--since-time <time>`	what arrived after this ISO 8601 time, or 2h / 1d ago; the saved point stays put.
`--limit <n>`	at most this many per chat, the newest.
`--all`	muted and archived chats too — left out unless they mention you or reply to you.
`--transcribe`	turn voice messages not heard yet into text — by the messenger, or a model on this machine; can take minutes.
`--model <id>`	which downloaded speech model hears them, with --transcribe; `models audio list` shows them.

`tg review`

every message, yours too, in chats that changed since a point — for reviewing who owes what

tg review [options]

Option	What it does
`--since-time <time>`	where the last review ended — ISO 8601, or 2h / 1d ago; 3 days ago if not given.
`--chat <chat>`	only this chat: a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`--unanswered [duration]`	only questions to you or a group's admins that nobody answered, asked at least this long ago — 4h, 1d; 24h if not given.
`--all`	muted and archived chats too — left out unless they mention you or reply to you.
`--transcribe`	turn voice messages not heard yet into text — by the messenger, or a model on this machine; can take minutes.
`--model <id>`	which downloaded speech model hears them, with --transcribe; `models audio list` shows them.

`tg topics`

the topics of a forum group

`tg topics list`

a forum group's topics, newest activity first

tg topics list <chat> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

Option	What it does
`--limit <n>`	how many to show.
`--page <n>`	which page, starting at 1.
`--all`	every row, no paging.

`tg topics search`

a forum group's topics whose title matches

tg topics search <chat> <text> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`text`	required	words from the topic's title.

Option	What it does
`--limit <n>`	how many to show.
`--page <n>`	which page, starting at 1.
`--all`	every row, no paging.

`tg watch`

print new messages as they arrive, until Ctrl-C or --timeout (either ends it normally)

tg watch [options]

Option	What it does
`--events`	also edits, deletions and reactions; every line then names its event.

`tg serve`

keep the local store current until stopped — what a systemd or launchd unit runs

tg serve

`tg server`

tg serve in the background: start, stop, restart, status, logs; install adds a systemd or launchd unit

`tg server start`

start serve in the background — through the unit if one is installed — and answer once it connects

tg server start

`tg server stop`

stop this profile's serve — through the unit if it runs under one

tg server stop

`tg server restart`

stop it and start it again

tg server restart

`tg server status`

whether serve runs for this profile, since when, who started it, and the unit if there is one

tg server status

`tg server logs`

serve's latest log lines — from the journal under systemd, else its log file

tg server logs [options]

Option	What it does
`-n, --lines <n>`	how many lines. Default: `50`.

`tg server install`

write a systemd user unit or a launchd agent for this profile; starts nothing

tg server install

`tg server uninstall`

remove this profile's unit; stop it first

tg server uninstall

`tg store`

the local store of messages

`tg store status`

per chat: messages stored, the oldest and newest, and the stretches held completely

tg store status [chat]

Argument		What it is
`chat`	optional	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

`tg store fetch`

fetch a chat's history into the local store, newest first; run it again to continue

tg store fetch <chat> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

Option	What it does
`--limit <n>`	at most this many messages in this run; 1000 if not given.
`--page-size <n>`	how many messages one request asks for; 100 if not given.
`--pause <duration>`	pause between pages, to stay under the provider's limits. Default: `1s`.
`--since-time <time>`	stop once it reaches messages older than this: ISO 8601, or 2h / 1d ago.
`--last <n>`	stop once the newest n messages are held.
`--background`	run as a job that outlives this command; `store jobs show` follows it.
`--estimate`	only estimate how many messages, requests and minutes a full fetch would still take — from the store, no request.

`tg store jobs`

background fetch jobs

`tg store jobs list`

background fetch jobs, newest first

tg store jobs list

`tg store jobs show`

one background job — the newest when none is named — and what the store now holds of its chat

tg store jobs show [job]

Argument		What it is
`job`	optional	the job id `store fetch --background` printed.

`tg store jobs cancel`

stop a running background job after its current page; a later fetch resumes where it stopped

tg store jobs cancel <job>

Argument		What it is
`job`	required	the job id.

`tg store export`

a chat's stored messages as JSON lines, oldest first; never asks the messenger

tg store export <chat> [options]

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

Option	What it does
`--format <format>`	jsonl (the default): one message per line; markdown: a transcript with a heading per day, replies and forwards quoted.
`--since-time <time>`	only from this ISO 8601 time, or 30m / 2h / 1d ago, on.
`--output <file>`	write JSON lines, or the transcript, to this new file, readable only by you.

`tg store clear`

delete from the store the chats this account has left, with their messages

tg store clear [options]

Option	What it does
`--left`	the chats this account has left — the only thing this clears.
`--allow-dangerous`	yes, delete — it cannot be undone, and a chat you left cannot be fetched again.

`tg store info`

the store file: where it is, its size, its schema and how many rows it holds; changes nothing

tg store info

`tg store check`

whether the store is healthy — integrity, search indexes, disk, and which chats are behind

tg store check

`tg store migrate`

bring the store up to this build's schema, then normalize the messages stored before it

tg store migrate

`tg store reindex`

rebuild the word index and its typo vocabulary from the stored messages; loses no message

tg store reindex

`tg store backup`

copy the store into a new file, while it is in use; never overwrites a file

tg store backup <file>

Argument		What it is
`file`	required	the new file.

`tg store restore`

put a backup in place of the store; the store it replaces is kept beside it, never deleted

tg store restore <file>

Argument		What it is
`file`	required	a file `store backup` wrote.

`tg conversations`

the conversations inside a chat, found in the stored messages by replies, mentions and who wrote next

`tg conversations build`

find a chat's conversations in what the store holds, replacing the last build; never asks the messenger

tg conversations build [options]

Option	What it does
`--chat <chat>`	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

`tg conversations list`

a chat's conversations, the newest first: when, how many messages, how many people

tg conversations list [options]

Option	What it does
`--chat <chat>`	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`--since-time <time>`	only those that started at this ISO 8601 time, or 30m / 2h / 1d ago, or later.
`--limit <n>`	how many.

`tg conversations show`

one conversation's messages, oldest first — by its id, or the one a message is in

tg conversations show <conversation> [message]

Argument		What it is
`conversation`	required	a conversation id from `conversations list`; or a chat: its title or part of it, its id, @username, or `me` for Saved Messages, with a message.
`message`	optional	a message id in that chat: show the conversation it is in.

`tg conversations batches`

windows of a chat for your own AI agent to link: which earlier message each one answers

`tg conversations batches status`

how many messages still wait for an answer, in how many batches, and how much text

tg conversations batches status [options]

Option	What it does
`--chat <chat>`	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`--size <n>`	messages to answer per batch, 10–200; 50 by default.

`tg conversations batches next`

the next window to answer, with the messages before it; message text goes to stdout only

tg conversations batches next [options]

Option	What it does
`--chat <chat>`	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`--size <n>`	messages to answer per batch, 10–200; 50 by default.

`tg conversations links`

your agent's answers: which earlier message each message of a batch answers

`tg conversations links add`

store your agent's answer to a batch, read as JSON from stdin: { "model", "answers": [{ "message", "parent", "confidence" }] }; all or nothing

tg conversations links add [options]

Option	What it does
`--batch <id>`	the batch id `conversations batches next` printed.

`tg conversations links clear`

drop your agent's answers for a chat, or only one model's; messages are never touched

tg conversations links clear [options]

Option	What it does
`--chat <chat>`	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.
`--model <model>`	only the answers this model gave.

`tg recipients`

the chats this profile may send to, when the list is on

`tg recipients list`

the chats on the list; empty and off until the first add

tg recipients list

`tg recipients add`

allow sending to this chat; the first add turns the list on

Changes something in Telegram.

tg recipients add <chat>

Argument		What it is
`chat`	required	a chat: its title or part of it, its id, @username, or `me` for Saved Messages.

`tg recipients remove`

stop allowing this chat; the list stays on

Changes something in Telegram.

tg recipients remove <chat>

Argument		What it is
`chat`	required	chat id, or the title as the list shows it.

`tg recipients clear`

delete the list, which turns it off: this profile may send to any chat again

Changes something in Telegram.

tg recipients clear

`tg sends`

every attempt to send from this profile — never the text

`tg sends list`

attempts to send, newest first: sent, refused, failed, or not known

tg sends list [options]

Option	What it does
`--limit <n>`	how many to show.

`tg runs`

recorded runs — what this tool did, and when

`tg runs list`

recorded runs, newest first

tg runs list [options]

Option	What it does
`--limit <n>`	how many to show. Default: `20`.

`tg runs show`

one run: what it was, and one line per operation

tg runs show <run-id>

Argument		What it is
`run-id`	required	an id from `tg runs list`.

`tg runs path`

the directory holding one run

tg runs path <run-id>

Argument		What it is
`run-id`	required	an id from `tg runs list`.

`tg config`

the settings in force, and where each one came from

`tg config show`

the profile, the profiles that exist, and each setting with where it came from

tg config show [options]

Option	What it does
`--bot`	the settings a bot command on this profile gets, rather than the personal account's.

`tg config set`

save a setting to the configuration file

Changes something in Telegram.

tg config set <setting> <value> [options]

Argument		What it is
`setting`	required	one of: limit, timeoutMs, color, senderColors, record, keepRunsForDays, readOnly, allow, permissions, sendsPerHour, transcribeWith, speechModel, readOtherBots, updateCheck, skillHint.
`value`	required	a number, true or false, or for allow a list like send,reaction.

Option	What it does
`--defaults`	change what every profile gets, rather than this profile.
`--personal`	only for personal accounts — the personal section of the file.
`--bot`	only for bots — the bot section of the file.

`tg config unset`

remove a setting from the configuration file

Changes something in Telegram.

tg config unset <setting> [options]

Argument		What it is
`setting`	required	one of: limit, timeoutMs, color, senderColors, record, keepRunsForDays, readOnly, allow, permissions, sendsPerHour, transcribeWith, speechModel, readOtherBots, updateCheck, skillHint.

Option	What it does
`--defaults`	change what every profile gets, rather than this profile.
`--personal`	only for personal accounts — the personal section of the file.
`--bot`	only for bots — the bot section of the file.

`tg doctor`

the state this installation is in, without connecting unless --online

tg doctor [options]

Option	What it does
`--online`	also connect once and read the account; sends nothing.

`tg doctor report`

what a problem report holds; writes nothing

`tg doctor report create`

write a problem report to a file, and say where to send it

tg doctor report create [options]

Option	What it does
`--run <id>`	the run the report is about; the newest failed one if not given.
`--output <file>`	where to write it; a new file in this directory if not given.

`tg commands`

every command, option and exit code as JSON — what an agent reads instead of --help

tg commands

`tg complete`

shell completion: tg complete zsh prints the script to source

tg complete [words]

Argument		What it is
`words`	optional

`tg upgrade`

upgrade tg with the package manager that installed it; --check only looks

tg upgrade [options]

Option	What it does
`--check`	say whether a newer version exists, and install nothing.

`tg mcp`

serve this profile to an agent over MCP, on stdin and stdout — claude mcp add tg -- tg mcp

tg mcp [options]

Option	What it does
`--confirm-send`	show the owner every write in a form from the server first.
`--allow-dangerous`	no form before a deletion whose permission level is ask.
`--allow-send`	no longer used — the profile's permissions decide; kept so an old setup still starts.
`--allow-mark-read`	no longer used — the profile's permissions decide.
`--allow-delete`	no longer used — the profile's permissions decide.

`tg mcp config`

print the mcpServers entry for Claude Desktop, Cursor and others, with full paths; writes nothing

tg mcp config [options]

Option	What it does
`--confirm-send`	show the owner every write in a form from the server first.
`--allow-dangerous`	no form before a deletion whose permission level is ask.
`--allow-send`	no longer used — the profile's permissions decide; kept so an old setup still starts.
`--allow-mark-read`	no longer used — the profile's permissions decide.
`--allow-delete`	no longer used — the profile's permissions decide.

`tg bot`

a Telegram bot, through the official Bot API and a bot token — not your personal account

`tg bot auth`

the bot token this profile uses

`tg bot auth set`

check a bot token with Telegram, then keep it — typed at a hidden prompt or piped on stdin

Changes something in Telegram.

tg bot auth set

`tg bot auth show`

where this profile's bot token comes from, and which bot it is

tg bot auth show

`tg bot auth remove`

forget this profile's bot token

Changes something in Telegram.

tg bot auth remove

`tg bot list`

every name on this machine that has a bot token; --check asks Telegram which bot each is

tg bot list [options]

Option	What it does
`--check`	ask Telegram who each bot is.

`tg bot chats`

the chats this bot is in — Telegram gives a bot no list of them, so list shows the ones it has seen

`tg bot chats list`

chats this bot has seen on this machine — not a complete list from Telegram

tg bot chats list

`tg bot chats show`

one chat from Telegram, and remember it

tg bot chats show <chat>

Argument		What it is
`chat`	required	a chat id, user: for a person, or the title of a chat this bot has seen.

`tg bot chats leave`

take the bot out of a chat; only an admin of the chat can bring it back

Changes something in Telegram.

tg bot chats leave <chat>

Argument		What it is
`chat`	required	a chat id, or the title of a chat this bot has seen.

`tg bot chats action`

show what the bot is doing in a chat — typing, sending a photo — for a few seconds

Changes something in Telegram.

tg bot chats action <chat> <action>

Argument		What it is
`chat`	required	a chat id, user: for a person, or the title of a chat this bot has seen.
`action`	required	what the chat sees. One of: `typing`, `photo`, `video`, `voice`, `file`.

`tg bot messages`

the messages in the chats this bot is in

`tg bot messages send`

send a message as the bot; without [text], the text is read from stdin

Changes something in Telegram.

tg bot messages send <chat> [text] [options]

Argument		What it is
`chat`	required	a chat id, user: for a person, or the title of a chat this bot has seen.
`text`	optional	the message.

Option	What it does
`--reply-to <message>`	answer this message, by its id in the same chat.
`--silent`	deliver without a notification.
`--md`	read bold, italic, ~~struck~~ and `code` in the text; \ keeps a mark literal.
`--html`	the text is HTML: , , , .
`--file <file>`	attach a file; the text becomes its caption.
`--photo <file>`	attach a .jpg, .png or .webp as a photo; the text becomes its caption.
`--as-file`	send the --file as a file to download, a video included.
`--voice <file>`	send an Ogg Opus file as a voice message, alone, with no text.
`--allow-any-file`	send a file even from a hidden folder, ~/.ssh or this CLI's own folders.

`tg bot messages list`

the latest messages in a chat; where Telegram gives a bot no history, and with --offline, the ones this bot has seen on this machine

tg bot messages list <chat>

Argument		What it is
`chat`	required	a chat id, user: for a person, or the title of a chat this bot has seen.

`tg bot messages show`

one message by its id in a chat

tg bot messages show <chat> <message>

Argument		What it is
`chat`	required	a chat id, user: for a person, or the title of a chat this bot has seen.
`message`	required	message id.

`tg bot messages edit`

replace the text of a message the bot sent

Changes something in Telegram.

tg bot messages edit <chat> <message> <text> [options]

Argument		What it is
`chat`	required	a chat id, user: for a person, or the title of a chat this bot has seen.
`message`	required	message id.
`text`	required	the new text.

Option	What it does
`--md`	read bold, italic, ~~struck~~ and `code` in the text; \ keeps a mark literal.
`--html`	the text is HTML: , , , .

`tg bot messages delete`

delete messages in a chat the bot can delete in; it cannot be undone

Changes something in Telegram.

tg bot messages delete <chat> <messages> [options]

Argument		What it is
`chat`	required	a chat id, user: for a person, or the title of a chat this bot has seen.
`messages`	required	message ids.

Option	What it does
`--allow-dangerous`	delete without asking.

`tg bot messages pin`

pin a message in a chat; quietly unless --notify

Changes something in Telegram.

tg bot messages pin <chat> <message> [options]

Argument		What it is
`chat`	required	a chat id, user: for a person, or the title of a chat this bot has seen.
`message`	required	message id.

Option	What it does
`--notify`	tell the chat's members.

`tg bot messages unpin`

unpin a message in a chat

Changes something in Telegram.

tg bot messages unpin <chat> <message>

Argument		What it is
`chat`	required	a chat id, user: for a person, or the title of a chat this bot has seen.
`message`	required	message id.

`tg bot recipients`

the chats this bot may write to; with no list, every chat — clear removes the list

`tg bot recipients list`

the chats on the list, or nothing when there is no list

tg bot recipients list

`tg bot recipients add`

allow a chat: its id, user:<id>, or the title of a chat this bot has seen

Changes something in Telegram.

tg bot recipients add <chat>

Argument		What it is
`chat`	required

`tg bot recipients remove`

take a chat off the list

Changes something in Telegram.

tg bot recipients remove <chat>

Argument		What it is
`chat`	required

`tg bot recipients clear`

remove the list: the bot may write to any chat again

Changes something in Telegram.

tg bot recipients clear

`tg bot sends`

what this bot sent, edited and deleted from this machine — ids and outcomes, never text

`tg bot sends list`

tg bot sends list

`tg skill`

the instructions an agent is given for this tool

`tg skill show`

print SKILL.md — tg skill install puts it where Claude Code, Codex and Gemini CLI look for it

tg skill show [name]

Argument		What it is
`name`	optional	one of the skills shipped for a task: link-conversations.

`tg skill install`

write SKILL.md to ~/.claude/skills/tg-cli/ (Claude Code) and ~/.agents/skills/tg-cli/ (Codex, Gemini CLI)

tg skill install [options]

Option	What it does
`--for <agents>`	which agents to install for. One of: `claude`, `agents`, `all`. Default: `all`.

Exit codes

Branch on the code, not on the text: the text can change, the code does not.

Code	When
`0`	it worked
`2`	`validation_error`
`3`	`configuration_error`
`4`	`authentication_error`
`5`	`permission_error`
`6`	`not_found`
`7`	`confirmation_required`
`8`	`rate_limited`
`9`	`timeout`
`10`	`network_error`
`11`	`provider_error`
`12`	`provider_unavailable`
`13`	`invalid_response`
`14`	`outcome_unknown`
`130`	`cancelled`
`1`	anything else

0 and only 0 means the operation was done. 14 (outcome_unknown) means a message may have gone: repeat it only with the same --send-id, which Telegram uses to drop a second copy.

Options for every commandCopy Anchor Link

tg sessionCopy Anchor Link

tg session startCopy Anchor Link

tg session endCopy Anchor Link

tg accountCopy Anchor Link

tg account showCopy Anchor Link

tg account updateCopy Anchor Link

tg account sessionsCopy Anchor Link

tg account sessions listCopy Anchor Link

tg account sessions endCopy Anchor Link

tg chatsCopy Anchor Link

tg chats listCopy Anchor Link

tg chats eventsCopy Anchor Link

tg chats inspectCopy Anchor Link

tg chats showCopy Anchor Link

tg chats membersCopy Anchor Link

tg chats members listCopy Anchor Link

tg chats members addCopy Anchor Link

tg chats members removeCopy Anchor Link

tg chats mark-readCopy Anchor Link

tg chats createCopy Anchor Link

tg chats joinCopy Anchor Link

tg chats leaveCopy Anchor Link

tg chats updateCopy Anchor Link

tg chats linkCopy Anchor Link

tg chats link showCopy Anchor Link

tg chats link resetCopy Anchor Link

tg chats adminsCopy Anchor Link

tg chats admins addCopy Anchor Link

tg chats admins removeCopy Anchor Link

tg chats foldersCopy Anchor Link

tg chats folders listCopy Anchor Link

tg chats folders createCopy Anchor Link

tg chats folders updateCopy Anchor Link

tg chats folders deleteCopy Anchor Link

tg chats rulesCopy Anchor Link

tg chats rules showCopy Anchor Link

tg chats rules setCopy Anchor Link

tg chats rules unsetCopy Anchor Link

tg chats moderateCopy Anchor Link

tg contactsCopy Anchor Link

tg contacts listCopy Anchor Link

tg contacts showCopy Anchor Link

tg contacts lookupCopy Anchor Link

tg contacts syncCopy Anchor Link

tg contacts addCopy Anchor Link

tg contacts removeCopy Anchor Link

tg contacts blockCopy Anchor Link

tg contacts unblockCopy Anchor Link

tg contacts renameCopy Anchor Link

tg contacts importCopy Anchor Link

tg messagesCopy Anchor Link

tg messages listCopy Anchor Link

tg messages searchCopy Anchor Link

tg messages sendCopy Anchor Link

tg messages showCopy Anchor Link

tg messages contextCopy Anchor Link

tg messages downloadCopy Anchor Link

tg messages transcribeCopy Anchor Link

tg messages editCopy Anchor Link

tg messages deleteCopy Anchor Link

tg messages forwardCopy Anchor Link

tg messages pinCopy Anchor Link

tg messages unpinCopy Anchor Link

tg messages scheduledCopy Anchor Link

tg messages linksCopy Anchor Link

tg reactionsCopy Anchor Link

tg reactions addCopy Anchor Link

tg reactions removeCopy Anchor Link

tg pollsCopy Anchor Link

tg polls showCopy Anchor Link

tg polls voteCopy Anchor Link

tg polls closeCopy Anchor Link

tg polls createCopy Anchor Link

tg modelsCopy Anchor Link

tg models audioCopy Anchor Link

tg models audio listCopy Anchor Link

tg models audio downloadCopy Anchor Link

tg inboxCopy Anchor Link

Options for every command

`tg session`

`tg session start`

`tg session end`

`tg account`

`tg account show`

`tg account update`

`tg account sessions`

`tg account sessions list`

`tg account sessions end`

`tg chats`

`tg chats list`

`tg chats events`

`tg chats inspect`

`tg chats show`

`tg chats members`

`tg chats members list`

`tg chats members add`

`tg chats members remove`

`tg chats mark-read`

`tg chats create`

`tg chats join`

`tg chats leave`

`tg chats update`

`tg chats link`

`tg chats link show`

`tg chats link reset`

`tg chats admins`

`tg chats admins add`

`tg chats admins remove`

`tg chats folders`

`tg chats folders list`

`tg chats folders create`

`tg chats folders update`

`tg chats folders delete`

`tg chats rules`

`tg chats rules show`

`tg chats rules set`

`tg chats rules unset`

`tg chats moderate`

`tg contacts`

`tg contacts list`

`tg contacts show`

`tg contacts lookup`

`tg contacts sync`

`tg contacts add`

`tg contacts remove`

`tg contacts block`

`tg contacts unblock`

`tg contacts rename`

`tg contacts import`

`tg messages`

`tg messages list`

`tg messages search`

`tg messages send`

`tg messages show`

`tg messages context`

`tg messages download`

`tg messages transcribe`

`tg messages edit`

`tg messages delete`

`tg messages forward`

`tg messages pin`

`tg messages unpin`

`tg messages scheduled`

`tg messages links`

`tg reactions`

`tg reactions add`

`tg reactions remove`

`tg polls`

`tg polls show`

`tg polls vote`

`tg polls close`

`tg polls create`

`tg models`

`tg models audio`

`tg models audio list`

`tg models audio download`

`tg inbox`

`tg review`