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.
Global options
Apply to every command.
| Option | Purpose |
|---|---|
-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. |
--trace | one line per request on stderr: ids and timings, 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 under max runs — ids and timings, never message content. |
--no-record | do not keep it, whatever the configuration says. |
--serve | start max serve in the background if it is not running (the default). |
--no-serve | do not start it; log in on this command's own connection unless one is running. |
Commands
max chats create
create a group or a channel; the people added are told
Changes something in MAX.
max chats create <title> [person] [options]| Argument | Requirement | Meaning |
|---|---|---|
title | required | the group's name. |
person | optional | people to add: an id, or part of a name. |
| Option | Purpose |
|---|---|
--channel | a private channel instead of a group; people join it by its link. |
max chats members
who is in a group
max chats members list
everyone in a group, a page at a time, with their role and when they were last seen
max chats members list <chat> [options]| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
| Option | Purpose |
|---|---|
--limit <n> | how many to show. |
--page <n> | which page, starting at 1. |
--all | every row, no paging. |
max chats members audit
members that look like bots, each with its reasons — read from the member list and the local store; never one request per person, and it removes nobody
max chats members audit <chat> [options]| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
| Option | Purpose |
|---|---|
--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 in full — profile, photos and everything they wrote — one person a second; the public ban lists cover Telegram only, so nothing is sent. |
max 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
max chats members history <chat> [options]| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
| Option | Purpose |
|---|---|
--since-time <time> | ISO 8601, or 2h / 1d ago; everything recorded if not given. |
max 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
max chats members fetch <chat> [options]| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
| Option | Purpose |
|---|---|
--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). |
max chats members add
add people; they are told
Changes something in MAX.
max chats members add <chat> <person> [options]| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
person | required | an id, or part of a name. |
| Option | Purpose |
|---|---|
--history | the people added also see the messages from before they came. |
max chats members remove
remove people; their messages stay
Changes something in MAX.
max chats members remove <chat> <person>| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
person | required | an id, or part of a name. |
max chats admins
give or take back a member's admin rights
max chats admins add
make a member an admin with these rights
Changes something in MAX.
max chats admins add <chat> <person> [options]| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
person | required | an id, or part of a name. |
| Option | Purpose |
|---|---|
--can <rights> | what they may do, comma-separated: read, members, admins, info, pin, link, post, edit, delete. |
max chats admins remove
take an admin's rights back; they stay a member
Changes something in MAX.
max chats admins remove <chat> <person>| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
person | required | an id, or part of a name. |
max chats update
rename a group or channel, change its description, or turn one of its settings on or off
Changes something in MAX.
max chats update <chat> [options]| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
| Option | Purpose |
|---|---|
--title <title> | the new name. |
--description <text> | the new description. |
--photo <file> | a new photo for it — an image file. |
--all-can-pin <on|off> | every member may pin messages. |
--only-admins-add <on|off> | only admins may add members. |
--only-admins-call <on|off> | only admins may start a call. |
--only-owner-edits-info <on|off> | only the owner may change the name and photo. |
--members-see-link <on|off> | members may see the invite link. |
max chats link
a group's invite link
max chats link show
the invite link, if you may see it
max chats link show <chat>| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
max chats link reset
replace the invite link; the old one stops working
Changes something in MAX.
max chats link reset <chat>| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
max chats requests
requests to join a MAX channel needing approval
max chats requests list
pending requests to join a MAX channel needing approval; admins only; requestedAt is null
max chats requests list <chat> [options]| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
| Option | Purpose |
|---|---|
--limit <n> | how many. |
--search <text> | only people whose name or @username has this. |
--link <link> | not supported by MAX; use name search instead. |
max chats requests accept
let them in; the group sees them join
Changes something in MAX.
max chats requests accept <chat> [person] [options]| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
person | optional | who asked: an id from chats requests list. |
| Option | Purpose |
|---|---|
--all | not supported by MAX; select one person from chats requests list. |
--link <link> | not supported by MAX; select one person from chats requests list. |
max chats requests decline
turn the request away
Changes something in MAX.
max chats requests decline <chat> [person] [options]| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
person | optional | who asked: an id from chats requests list. |
| Option | Purpose |
|---|---|
--all | not supported by MAX; select one person from chats requests list. |
--link <link> | not supported by MAX; select one person from chats requests list. |
max chats moderate
judge a group's new messages and members by its rules, and act as they allow
Changes something in MAX.
max chats moderate <chat> [options]| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
| Option | Purpose |
|---|---|
--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. |
max chats delete
delete a chat from this account; the others in it keep it and its messages
Changes something in MAX.
max chats delete <chat> [options]| Argument | Requirement | Meaning |
|---|---|---|
chat | required | a chat: its id, or part of its title. |
| Option | Purpose |
|---|---|
--allow-dangerous | go ahead without the question an ask level puts before a deletion. |
Exit codes
Scripts should branch on the code, not the message: wording may change, codes remain stable.
| Code | Meaning |
|---|---|
0 | Success |
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 | Any other error |
0, and only 0, means the operation succeeded. 14 — outcome_unknown — means the message may have been sent: its outcome is neither confirmed nor failed. Retry only with the same --send-id.