Group and channel administration
Members, invitations, permissions and moderation for groups and channels. Actions require the relevant permissions.
This reference covers group administration commands. Use it to look up member, invitation, permission and moderation options before making a change.
Members, invitations, permissions and moderation for groups and channels. Actions require the relevant permissions.
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. |
--no-input | never prompt or open interactive login; piped input remains available. |
--max-input-bytes <bytes> | maximum buffered input bytes (default: 16777216). |
--max-output-bytes <bytes> | maximum machine output bytes (default: 4194304; 0 disables). |
--fields <paths> | comma-separated item or object fields: id,text; preserve pagination and operation ids. |
--dry-run | preview parsed arguments and permissions before running the action. |
--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. |
Commands
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 | Requirement | 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 audit
members that look like bots, each with its reasons, from the member list and local store; --deep checks selected people individually; removes nobody
tg chats members audit <chat> [options]| Argument | Requirement | 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 |
|---|---|
--budget <pages> | at most this many pages of 200 members, a pause between them (default: 10). |
--min-score <n> | only members scoring at least this; 1 lists everyone with a reason (default: 2). |
--deep <n> | also check the top n profiles, oldest photos, up to 1,000 stored messages each and public ban lists, which are sent their ids — one person a second. |
tg chats members history
who joined, who left and whose profile changed, oldest first — what chats members fetch recorded in the local store; never asks the messenger
tg chats members history <chat> [options]| Argument | Requirement | 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; everything recorded if not given. |
tg chats members fetch
read a group's whole member list into the local store's member history: who joined, who left, daily counts and profile changes; someone is recorded as gone only when every member was read
tg chats members fetch <chat> [options]| Argument | Requirement | 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 |
|---|---|
--track | also fetch it daily while serve runs; chats tracking lists and edits those chats. |
--budget <pages> | at most this many pages of 200 members, a pause between them (default: 10). |
tg chats members add
add people; they are told
Changes something in Telegram.
tg chats members add <chat> <person>| Argument | Requirement | 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 | Requirement | 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 create
create a group or a channel; the people added are told
Changes something in Telegram.
tg chats create <title> [person] [options]| Argument | Requirement | 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 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 | Requirement | 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. |
--join-approval <on|off> | people ask to join, and an admin lets them in. |
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 | Requirement | What it is |
|---|---|---|
chat | required | a chat: its title or part of it, its id, @username, or me for Saved Messages. |
tg chats link create
make another invite link; nobody is told until you share it
Changes something in Telegram.
tg chats link create <chat> [options]| Argument | Requirement | 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 |
|---|---|
--approval | who joins by it asks first, and an admin lets them in; it then has no use limit. |
--expire-time <time> | it stops working then: 2026-09-25T09:00 (local time), or 30m, 2h, 7d from now. |
--max-uses <n> | at most this many people join by it, 1 to 99999. |
tg chats link list
your invite links, newest first, with how many joined and how many wait
tg chats link list <chat> [options]| Argument | Requirement | 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 |
|---|---|
--revoked | the links you stopped, instead. |
--limit <n> | how many. |
tg chats link revoke
stop one link; for the group's own link, the answer is the new one
Changes something in Telegram.
tg chats link revoke <chat> <link>| Argument | Requirement | What it is |
|---|---|---|
chat | required | a chat: its title or part of it, its id, @username, or me for Saved Messages. |
link | required | the link, as chats link list shows it. |
tg chats link update
change one of your invite links, the group's own one too
Changes something in Telegram.
tg chats link update <chat> <link> [options]| Argument | Requirement | What it is |
|---|---|---|
chat | required | a chat: its title or part of it, its id, @username, or me for Saved Messages. |
link | required | the link, as chats link list shows it. |
| Option | What it does |
|---|---|
--approval | who joins by it asks first, and an admin lets them in; it then has no use limit. |
--no-approval | anyone with it joins at once. |
--expire-time <time> | it stops working then: 2026-09-25T09:00 (local time), or 30m, 2h, 7d from now; never takes the expiry away. |
--max-uses <n> | at most this many people join by it, 1 to 99999. |
tg chats link reset
replace the invite link; the old one stops working
Changes something in Telegram.
tg chats link reset <chat>| Argument | Requirement | What it is |
|---|---|---|
chat | required | a chat: its title or part of it, its id, @username, or me for Saved Messages. |
tg chats requests
requests to join a group that needs an admin's approval
tg chats requests list
who asked to join, newest first; only admins see them, and reading tells nobody
tg chats requests list <chat> [options]| Argument | Requirement | 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. |
--search <text> | only people whose name or @username has this. |
--link <link> | only people who asked through this invite link; not with --search. |
tg chats requests accept
let them in; the group sees them join
Changes something in Telegram.
tg chats requests accept <chat> [person] [options]| Argument | Requirement | What it is |
|---|---|---|
chat | required | a chat: its title or part of it, its id, @username, or me for Saved Messages. |
person | optional | who asked: an id from chats requests list. |
| Option | What it does |
|---|---|
--all | every pending request, counted against the hourly limit first. |
--link <link> | with --all: only the requests made by this invite link. |
tg chats requests decline
turn the request away
Changes something in Telegram.
tg chats requests decline <chat> [person] [options]| Argument | Requirement | What it is |
|---|---|---|
chat | required | a chat: its title or part of it, its id, @username, or me for Saved Messages. |
person | optional | who asked: an id from chats requests list. |
| Option | What it does |
|---|---|
--all | decline every pending request; declining does not count toward the hourly sending limit. |
--link <link> | with --all: only the requests made by this invite link. |
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 | Requirement | 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 | Requirement | 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 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 | Requirement | 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. |
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.