Использование tg
Документация: v0.24.0
От первого входа до отправки сообщений — в порядке освоения. Все команды и параметры: Справочник команд. Здесь объясняется, как они связаны.
Каждая команда выполняет одно действие, выводит результат и выходит. Только tg watch, tg serve и tg mcp продолжают работать и сообщают об этом.
Ниже схема команды, а не команда для копирования. Вместо обозначений в скобках подставляют значения, как в примерах ниже.
tg [profile] [options] <resource> <action> [arguments]Начало работы
npm install -g @leemour/tg-cli
tg setup # guided app registration, login and agent skill
tg chats list --limit 5 # your newest chats
tg messages list me # Saved Messages, the latest 20На настройку отведите около пяти минут. История загружается отдельно: выберите чат и объём перед tg store fetch <chat> --last 100. Агент может прочитать tg skill show без входа; tg setup --agent codex явно выбирает его skill. Параметры объяснены в tg setup --help. Для чтения больше ничего не нужно.
Вход
tg setup — команда первого запуска. По умолчанию она автоматически регистрирует приложение и предлагает вход по QR; --app browser и --method phone выбирают альтернативы. Для входа без остальных шагов либо для завершения прерванного или истёкшего входа используйте:
tg session start # QR code: Settings → Devices → Link Desktop Device
tg session start phone # phone number, the code Telegram sends, your 2FA password
tg session start --qr-file login.png # the QR code as a picture, for an agent to show youПри первом подключении нужны api_id и api_hash — данные, по которым Telegram узнаёт программу CLI. Их получают на my.telegram.org. Полная команда tg session start --app auto получает их автоматически; tg session start --app browser позволяет ввести их с сайта вручную. Затем подтвердите вход в аккаунт с телефона. Пошаговый вход по QR и номеру телефона.
Секреты не передаются аргументами. Хеш приложения и пароль 2FA вводятся скрыто, код и телефон — по запросу или через stdin. Аргументы видны процессам в ps и остаются в истории оболочки.
В CI переменные TG_API_ID и TG_API_HASH передают данные приложения вместо хранилища ключей и имеют приоритет над ним.
tg account show # who this profile is logged in as; the phone as its last four digits
tg account show --show-phone # the whole phone number
tg account sessions list # every device and app logged in to the account; ends nothing
tg session end # log out on Telegram's side, and delete the session heresession end завершает сессию и в Telegram: устройство исчезает из списка. Для завершения с другого устройства используйте Настройки → Устройства.
Профили: первое слово
Можно использовать несколько аккаунтов. Профиль задаётся первым словом, а не параметром:
tg chats list # profile "default"
tg work chats list # profile "work"
export TG_PROFILE=work # or for a whole shell sessionПервое слово считается профилем, если это не команда. Имя chats запрещено с пояснением причины. Допустимы буквы, цифры, точки, дефисы и подчёркивания.
Каждый профиль имеет свои сессию, приложение, настройки и получателей. TG_PROFILE_LOCK фиксирует процесс на профиле, чтобы агент не выбрал менее ограниченный (Вход и сессии).
Как указать чат
Везде, где команда принимает <chat>, доступны:
- название или часть:
"Book club",book - идентификатор:
-1001234567890 - имя пользователя:
@example_channel meдля «Избранного»
Если название подходит нескольким чатам, ошибка перечисляет их с идентификаторами. tg не угадывает: отправку в неверный чат нельзя отменить. Повторите с идентификатором. Он не меняется, поэтому используйте его дальше.
messages show и messages context также принимают указатель msg: вместо чата и идентификатора сообщения. Его возвращает messages search --json для каждого результата.
Для человека (<person> в contacts show) можно указать идентификатор, @username или часть имени.
Чтение
Чтение не отмечает сообщения прочитанными. Команды ниже не показывают собеседнику ваш просмотр. Это делают только tg chats mark-read и tg messages list --mark-read (ниже).
Чаты
tg chats list # newest first, archived chats included
tg chats list --unread --kind group # only groups with unread messages
tg chats list --search book # titles containing "book"; at least 3 characters
tg chats show "Book club" # kind, unread count, last message, who is in it--kind принимает dialog (личный чат), group, channel, saved. Фильтры проверяют последние 200 чатов. Для групп и каналов есть отдельный раздел.
Сообщения
tg messages list "Book club" # the latest 20, oldest first
tg messages list "Book club" --limit 50
tg messages show "Book club" 4242 # one message
tg messages context "Book club" 4242 # it, and 5 messages either side
tg messages context "Book club" 4242 --before-n 2 --after-n 10В context выбранное сообщение отмечается ◀ в терминале и "anchor": true в JSON.
Что требует ответа
tg inbox # other people's unread messages, in every chat
tg inbox --since-time 2h # everything that came in during the last two hours
tg inbox --new # what arrived since the last --new — for scheduled runs
tg inbox --new --jsonl # the same for a script: one message per lineinbox показывает только чужие сообщения с указанием чата. Чаты без уведомлений и архив пропускаются, кроме упоминаний и ответов вам; --all включает их. Число пропущенных выводится в stderr.
inbox --new сдвигает сохранённую позицию. Следующий --new продолжает с неё, показывая сообщения один раз. Первый --new охватывает 24 часа. inbox без --new и inbox --since-time позицию не меняют. Обычный inbox повторяет результат, пока сообщения не прочитаны в приложении: сам он не отмечает прочитанным.
За запуск читаются максимум 20 чатов. Остальные перечислены в stderr и skipped с командой чтения. Если ожидающих сообщений больше --limit, показываются самые новые, а stderr объясняет, как прочитать остальные.
Обязательства и ожидания: review
tg review # the last 3 days
tg review --since-time 2026-09-23T09:00 # from where the last review ended
tg review --chat "Book club" --jsonВсе сообщения — ваши и чужие — в чатах с активностью после --since-time. Они помогают понять обещания, ожидания и неясности; классификацию выполняете вы или агент. Отметки прочитанного нет.
В конце stderr показывает прочитанный период. Следующую проверку начинайте с этого --since-time, чтобы не было пропусков. При неполном результате — слишком много чатов или ограничение последними 300 сообщениями — команда предупреждает; границу лучше не сдвигать. Максимум 20 чатов за запуск.
Вопросы без ответа
tg review --unanswered # questions nobody answered in 24 hours
tg review --chat "Neighbours" --unanswered 4h--unanswered [duration] оставляет вопросы, ожидающие вас или администраторов группы. Вопрос — сообщение с ? (знак ? в ссылках не учитывается) или ответ вам/администратору. Он закрыт, если вы или администратор ответили либо написали следом за автором. Вопросы моложе указанного срока (по умолчанию 24 часа) исключаются. Если администраторы неизвестны, учитываются только ваши ответы и выводится предупреждение. Указывайте длительность, например 4h или 1d; число часов без единицы не принимается.
Голосовые сообщения
tg messages transcribe "Book club" 4242 # by Telegram where it can, else a model here
tg messages transcribe "Book club" 4242 --local # only the model on this machine
tg messages list "Book club" --transcribe # every voice message shown that has no text yet
tg inbox --transcribe
tg review --transcribe
tg messages list "Book club" --transcribe --model gigaam-v3Telegram распознаёт речь для Premium и несколько сообщений в неделю по пробной квоте. Иначе работает локальная модель без передачи записи с компьютера. Модель скачивается один раз и только по запросу:
tg models audio list # the models, which is downloaded, which is the default
tg models audio download parakeet-v3 # once, checked against the sha256 this version expects| Модель | Языки | Размер |
|---|---|---|
parakeet-v3 — по умолчанию | 25: болгарский, чешский, датский, немецкий, греческий, английский, испанский, эстонский, финский, французский, хорватский, венгерский, итальянский, литовский, латышский, мальтийский, нидерландский, польский, португальский, румынский, русский, словацкий, словенский, шведский, украинский | 670 МБ |
gigaam-v3 | русский — лучшая из трёх моделей для русского | 232 МБ |
gigaam-v3-ctc | русский — немного быстрее, хуже с заглавными буквами | 225 МБ |
--model выбирает модель для одной команды вместе с --transcribe или в messages transcribe; transcribeWith и speechModel задают значения по умолчанию (Настройки). Расшифровка сохраняется в базе: повторный запрос отвечает сразу. --transcribe может занять несколько минут.
Файлы
tg messages download "Book club" 4242 --output-dir ~/Downloads # one message's files
tg messages download "Book club" --all --output-dir ~/tg-files # every file of the chat, newest firstСохраняются фотографии, файлы, видео и голосовые. Недостающий каталог создаётся. Имя файла сохраняется; безымянный получает идентификатор сообщения. Файлы не перезаписываются. С --all к занятому имени добавляется идентификатор сообщения. --all сохраняет позицию в небольшом файле рядом и продолжает с неё. Файлы доступны только вам.
Люди
tg contacts list # people you have a one-to-one chat with, newest first
tg contacts list --order name --search ann
tg contacts show @example_user # their bio and the chats you share
tg contacts lookup # who has a phone number — asks for it, or reads it from stdin
tg contacts sync # your whole Telegram contact list into the local storecontacts list показывает людей с личными чатами. contacts sync также загружает остальных из адресной книги Telegram. contacts lookup не принимает телефон аргументом: передайте stdin или введите по запросу.
Изменение контактов и собственного профиля:
tg contacts add @example_user # under the name they show
tg contacts rename @example_user Ann "from work" # a name only you see
tg contacts remove @example_user # the chat stays
tg contacts block @example_user # they need not be a contact
tg contacts unblock @example_user
tg contacts import people.txt # one "number, name" per line; never numbers as arguments
tg account update --first-name Ann --description "about me" --photo me.jpg
tg account sessions end --others # logs out every other device, your phone too; asks firstcontacts import возвращает количество и найденных Telegram людей, без телефонов. account sessions end спрашивает подтверждение; --yes подтверждает в скрипте.
Страницы
Списки показывают limit строк (по умолчанию 20). chats list, contacts list, chats members list и topics принимают --page и --all:
tg contacts list --limit 5 # five a page
tg contacts list --limit 5 --page 2 # the sixth to the tenth
tg contacts list --all # every row, no paging⚠ Нумерация страниц живого списка может повторить или пропустить строку. Новое сообщение между запросами сдвигает чаты через границу страниц.
У сообщений чата нет страниц: используйте --before-id, --after-id, --after-time для точного продолжения:
tg messages list "Book club" --before-id 4242 # older than message 4242
tg messages list "Book club" --after-id 4242 # newer than 4242, oldest first
tg messages list "Book club" --after-time 2h # what came in during the last two hours
tg messages list "Book club" --after-time 2026-09-20T09:00
tg messages list "Book club" --before-time 1d # what came before this time yesterdayПодсказка следующей страницы идёт в stderr. --before-id и --after-id принимают идентификатор сообщения. --after-time — ISO 8601 или период назад: 30m, 2h, 1d. В messages context параметры --before-n, --after-n задают число сообщений вокруг выбранного.
Найти чат и написать в него
tg chats list --search book --kind group # groups with "book" in the title
tg contacts list --search ann # people by name or @username
tg messages search "contract" # the text of every message this machine has kept
tg messages search "contract" --chat "Book club"
tg messages search "invoice.*(march|april)" --regexДля поиска чатов и контактов требуется не меньше трёх символов. Локальный messages search использует строгий профиль Lucene: invoic* ищет по началу слова, а invoic — точное слово. Команда не подключается к Telegram: она читает загруженное или сохранённое serve. Для прежнего неточного поиска используйте --language legacy. Найдя чат, используйте его идентификатор.
Отправка
Отправка происходит по команде отправки. По умолчанию дополнительное подтверждение не нужно: вы уже указали чат и текст. Права отдельной команды могут потребовать подтверждение или запретить действие. Также проверяются разрешённые получатели и часовой лимит (Безопасность). Попытки записываются без текста: tg sends list.
tg messages send me "a note to myself"
tg messages send "Book club" "See you at 7" --silent # no notification
tg messages send "Book club" "a link, no card" --no-preview
tg messages send "Book club" "**Bold** and _italic_" --md # Telegram Markdown--md использует форматтер Telegram: **bold** или *bold*, _italic_, __underline__, ~~struck~~ или ~struck~, ||spoiler||, встроенный код, блоки кода с языком, [label](https://example.com) и строки цитат, начинающиеся с > . Стили могут быть вложенными; код и блоки кода нельзя совмещать с другими сущностями, ссылки и цитаты нельзя вкладывать друг в друга. Без флага текст отправляется как есть. Обратная косая черта экранирует знак; _ и * внутри слова остаются буквальными. Незакрытые встроенные знаки остаются в тексте; незакрытый блок кода вызывает ошибку. Ссылки поддерживают абсолютные URL http, https и mailto. messages edit и подписи медиа используют тот же форматтер. В Telegram __text__ — подчёркивание; в MAX __text__ — жирный текст. Одиночный *text* в Telegram теперь тоже означает жирный текст.
Текст через stdin
Если аргумент текста отсутствует, он читается из stdin. Так можно отправить несколько строк и не оставлять текст в ps и истории оболочки:
printf 'first line\n\nthird line' | tg messages send me
tg messages send "Book club" < note.txtОтложенная отправка
tg messages send "Book club" "Tomorrow" --at-time 2026-10-01T09:00 # local time
tg messages send "Book club" "In two hours" --at-time 2h # or 30m, 1d from now
tg messages scheduled "Book club" # what waits to be sent there--at-time передаёт сообщение Telegram, который отправит его даже при выключенном компьютере. Время округляется вниз до минуты. Менее минуты или более года вперёд запрещено. Сообщение учитывается в лимите в час отправки. Отмена и изменение доступны в приложении Telegram; tg этого не делает.
Файлы, фото и голосовые
tg messages send "Book club" "The agenda" --file agenda.pdf # byte for byte; the text is the caption
tg messages send "Book club" --photo picture.jpg # recompressed by Telegram
tg messages send "Book club" --file trip.mp4 # a video plays in the chat
tg messages send "Book club" --file trip.mp4 --as-file # the same video as a file to download
tg messages send "Book club" --voice note.ogg # a voice message, alone, with no text--photo принимает .jpg, .png, .webp. .mp4 и .mov с --file отправляются как видео, если нет --as-file. --voice принимает Ogg Opus (.ogg, .oga, .opus) без текста и других файлов. Скрытые файлы, ~/.ssh, каталоги tg и база запрещены без --allow-any-file: там могут быть ключи и токены.
Ответ на сообщение
tg messages send "Book club" "Agreed" --reply-to 4242Ответ — разновидность отправки; доступны все её параметры.
Неизвестный результат отправки
Код 14 означает обрыв после отправки: сообщение могло уйти. Ошибка содержит --send-id. Повторите с ним: Telegram исключит дубликат.
tg messages send "Book club" "See you at 7" --send-id <id from the error>
tg messages forward "Book club" 4242 --to me --send-id <id from the error>Пересылка и опрос тоже получают идентификатор. Повтор без него создаст второе сообщение. Отправка с --at-time не повторяется: проверьте tg messages scheduled <chat>.
Правка, пересылка, закрепление, удаление
tg messages edit "Book club" 4242 "the corrected text" # your own message; --md as in a send
tg messages forward "Book club" 4242 --to me # checked against the chat it goes to
tg messages pin "Book club" 4242 # quiet unless --notify
tg messages unpin "Book club" 4242
tg messages delete me 4242 4243 --allow-dangerous # at most 10, for you only
tg messages delete me 4242 --allow-dangerous --for-everyoneРедактирование меняет текст, который могли уже прочитать. Пересылка создаёт новое сообщение и проверяется по чату назначения как отправка. Удаление необратимо и требует ответа y или --allow-dangerous. В супергруппах и каналах Telegram удаляет только у всех, поэтому нужен --for-everyone.
В часовой лимит входят: сообщения, пересылки, правки, закрепления с уведомлением и каждое удалённое сообщение. Реакции и тихие закрепления не входят.
Реакции и опросы
tg reactions add "Book club" 4242 👍 # replaces the reaction you had
tg reactions remove "Book club" 4242
tg polls show "Book club" 4250 # the poll and its answer ids
tg polls vote "Book club" 4250 <answer id>
tg polls vote "Book club" 4250 --retract
tg polls create "Book club" "Which day?" Monday Tuesday --anonymous
tg polls close "Book club" 4250 # your own poll; it cannot be reopenedРеакции отображаются под сообщением: 👍 3 🔥 1 (you: 🔥). В публичном опросе голос показывает ваше имя всем. Используйте идентификаторы из polls show, а не позицию ответа. --multiple разрешает несколько вариантов. Изменять голос можно только в опросах с --revote.
Отметка прочитанным
tg chats mark-read "Book club" # up to the newest message
tg chats mark-read "Book club" --until 4242 # only up to this one
tg messages list "Book club" --mark-read # read it, and mark it read up to the newest shownСобеседник видит прочтение. Действие read проходит защиту, но не входит в часовой лимит.
Папки
tg chats folders list # your folders, in the order the app shows them
tg chats folders create "Trips" --chat "Hiking" --chat @kate
tg chats folders update "Trips" --title "Travel" --add "Climbing" --remove @kate
tg chats folders delete "Travel" # the chats stayПапка задаётся идентификатором или точным названием. Она видна только вам; изменения всё равно проходят защиту как account.
Чего пока нет в tg
Несколько фотографий в одном сообщении остаются в планах.
Группы и каналы
tg chats inspect https://t.me/+AbCdEf # where an invite or public link leads; does not join
tg chats members list "Hiking" --all # everyone, with their role and when last seen
tg chats events "Hiking" # who joined, left, was added or removed — 7 days
tg chats events "Hiking" --type join,leave --since-time 2026-09-01T00:00
tg topics list "Hiking" # a forum group's topics, newest activity first
tg topics search "Hiking" "gear"
tg review --chat "Hiking" --unanswered # questions nobody answeredЭти команды только читают. events получает служебные сообщения: кто, что и с кем сделал. Типы: join, leave, add, remove, create, title, pin.
Эти команды меняют данные, и участники видят изменения:
Для форума используйте tg topics enable <chat> и tg topics create <chat> <title>. Обычная группа требует --upgrade --yes; сохраните новый идентификатор чата после преобразования. Если результат создания неизвестен, прочитайте topics list вместо повторного создания. Отправляйте в тему по её идентификатору через tg messages send <chat> <text> --topic <id> или tg polls create <chat> <question> <answers> --topic <id>.
tg chats create "Hiking 2027" @olga 12345 # a supergroup; the people added are told
tg chats create "Trail news" --channel # a channel; people join it by its link
tg chats join https://t.me/+AbCdEf # by an invite link, or a public one
tg chats leave "Hiking 2027"
tg chats update "Hiking 2027" --title "Hiking 2028" --description "routes and dates"
tg chats update "Hiking 2027" --all-can-pin off --only-admins-add on
tg chats link show "Hiking 2027" # the invite link, if you may see it
tg chats link reset "Hiking 2027" # a new one; the old one stops working
tg chats members add "Hiking 2027" @kate 67890 # they are told
tg chats members remove "Hiking 2027" @kate # their messages stay
tg chats admins add "Hiking 2027" @kate --can pin,delete
tg chats admins remove "Hiking 2027" @kateСоздаваемая группа всегда супергруппа. Недобавленные из-за приватности участники перечислены в providerMetadata.notAdded; группа всё равно создаётся. Если требуется одобрение вступления, ответ сообщает об отправке заявки. Действия проверяются как chat, каждый добавленный человек входит в часовой лимит.
chats update одновременно меняет название, описание и две настройки Telegram; ответ показывает текущее состояние. chats show выводит те же настройки. Правила chats rules и модерация chats moderate описаны в Управлении группами.
Для скриптов и агентов
В терминале tg выводит таблицу; в канал или с --json — единственное JSON-значение в stdout без индикаторов, галочек и предупреждений. Примечания, предупреждения и ошибки всегда идут в stderr.
tg chats list --json | jq -r '.items[].id'
tg messages list me --jsonl | jq -r .text # one message per line--json: одно значение JSON. Любой список — объект одинаковой формы:{ "items": [...], "page": 1, "limit": 20, "hasMore": true }.--allи--offlineвозвращают тот же объект.- Сообщения чата без номера страницы:
{ "items": [...], "limit": 20, "hasMore": true }. --jsonl: объект на строку без оболочки; наличие продолжения только в stderr.- Ошибка:
{ "error": { "code": "...", "message": "..." } }в stderr, stdout пуст. Отказ не спутать с пустым результатом. - Проверяйте код завершения, не текст. Текст меняется, код стабилен:
0успех,2неверные данные,4нет входа,5запрет профиля,6не найдено,7запрет получателя,8лимит профиля или Telegram,9таймаут,14неизвестный результат отправки. Полная таблица: Справочник команд. - Идентификаторы — строки. Не преобразуйте в числа.
--quietотключает примечания, но не ошибки.-v,-vvдобавляют подробности в таблицы.--timeout 30sограничивает всю команду (500ms,30s,2m).tg commands --jsonвозвращает дерево команд сmutates: trueу изменений Telegram.
if tg messages send "Book club" "See you at 7" --json > /dev/null; then
:
else
send_status=$?
case "$send_status" in
14) echo "it may have gone — repeat only with the same --send-id" ;;
4) echo "run tg session start" ;;
esac
fiАгент с терминалом читает skill, объясняющий нюансы вне справки:
mkdir -p ~/.claude/skills/tg-cli && tg skill show > ~/.claude/skills/tg-cli/SKILL.md # Claude Code
mkdir -p ~/.agents/skills/tg-cli && tg skill show > ~/.agents/skills/tg-cli/SKILL.md # Codex, Gemini CLIДля агента без доступа к терминалу, например Claude Desktop, используйте MCP. В Cursor можно выбрать CLI с доступом к терминалу или подключение через MCP.
Отображение переписки
tg messages list и tg messages search в терминале выводят переписку, а не таблицу:
10:05:12 Anna
Shall we call on Thursday?
10:09:03 Boris
↳ Anna: Shall we call on Thursday?
Thursday works.
📎 photo
edited 10:09:30Время локальное, новый день отмечен строкой. ↳ — исходное сообщение ответа, ↪ — автор пересланного, 📎 — вложение. Управляющие символы показываются текстом и не исполняются. -v добавляет идентификаторы сообщения, автора и чата; -vv — все известные данные.
Новые сообщения в реальном времени
tg watch # new messages, until Ctrl-C or --timeout
tg watch --jsonl # one message per line, as messages list --jsonl
tg watch --jsonl | ./on-message.sh
tg watch --events --jsonl # edits, deletions and reactions too
tg watch --jsonl --timeout 2m # a timeout ends it normally, with exit code 0С --events строки содержат тип: message, edit, delete, reaction. Без параметра — только сообщения. При удалении в личном чате или небольшой группе Telegram не сообщает чат, поэтому он отсутствует.
watch начинает с текущего момента. Пропущенные события не появляются. Для актуальной базы с догрузкой после отключения используйте serve в фоне или как службу (Локальная база):
tg server start # serve in the background; answers once it is connected
tg server status
tg server install # a systemd user unit or a launchd agent; starts nothingЧто сделала команда
tg --trace chats list # show each request on stderr, keep nothing
tg --record chats list # keep it, show nothing
tg runs list # what was kept, newest firstНеудачные запуски сохраняются автоматически. Запись содержит операции, идентификаторы, количества и длительности, но не сообщения, имена, названия, телефоны или ключи. Подробнее: Диагностика.
Локальная база
Все прочитанные tg данные сохраняются на компьютере для работы без сети:
tg chats list --offline # only from the store, never connect
tg store fetch "Project Alpha" --estimate # how much a fetch would take
tg store fetch "Project Alpha" --background # a chat's history, as a job
tg store export "Project Alpha" --format markdown --output alpha.md
tg store backup ~/tg-store.db # a copy of the store, while it is in useОбычная команда всё равно обращается к Telegram. --offline нужен без сети или когда подключение нежелательно; отправка запрещена. Загрузка, экспорт, поиск, копии и служба: Локальная база.
Настройки и разрешения профиля
Настройки хранятся в необязательном config.json. Приоритет: параметр → переменная окружения → профиль в файле → общие значения файла → встроенное значение.
tg config show # every setting, and where it came from
tg config set limit 50
tg work config set permissions.messages readonly # profile "work" changes no messages
tg config set permissions.messages.send ask # a yes or no before each send
tg config set sendsPerHour 10permissions задаёт уровень каждой команды: deny, readonly, ask, allow. По умолчанию разрешено всё, кроме удаления сообщений и завершения сессий с подтверждением. Отказ даёт код 5 и указывает разрешающую команду. Поля для секретов в файле нет. Все настройки: Настройки.
Дальше
- Локальная база — поиск, история, экспорт, копии
- Настройки — значения и разрешения
- Безопасность — хранение и защита отправок
- Сценарии использования — повседневные задачи агента