Введение on tgs

Установка

Mon, 01 Jan 0001 00:00:00 +0000

Установка#

tgs поставляется как один статический бинарник без зависимостей. Выберите способ под вашу платформу — установленная команда в любом случае называется tgs.

Homebrew (macOS и Linux)#

Самый быстрый способ на macOS и Linux:

brew install garenal1v3/tap/tgs-cli

Команда устанавливает бинарник tgs и обновляет его через brew upgrade.

Готовые бинарники#

Скачайте архив релиза под вашу платформу со страницы релизов. Архивы называются tgs-cli_<os>_<arch>:

Платформа	OS	Arch
macOS (Apple Silicon)	`darwin`	`arm64`
macOS (Intel)	`darwin`	`amd64`
Linux	`linux`	`amd64` / `arm64`
Windows	`windows`	`amd64` / `arm64`

macOS и Linux#

# Choose your platform: OS = darwin (macOS) or linux; ARCH = arm64 or amd64
OS=darwin
ARCH=arm64

curl -L -o tgs.tar.gz \
 "https://github.com/garenal1v3/tgs-cli/releases/latest/download/tgs-cli_${OS}_${ARCH}.tar.gz"
tar -xzf tgs.tar.gz tgs
sudo mv tgs /usr/local/bin/
tgs version

Windows#

# PowerShell — ARCH = amd64 or arm64
$Arch = "amd64"
Invoke-WebRequest `
 -Uri "https://github.com/garenal1v3/tgs-cli/releases/latest/download/tgs-cli_windows_$Arch.zip" `
 -OutFile tgs.zip
Expand-Archive tgs.zip -DestinationPath .
# Move tgs.exe into a directory on your PATH, then:
.\tgs.exe version

Сборка из исходников#

Требуется Go 1.26 или новее:

Быстрый старт

Mon, 01 Jan 0001 00:00:00 +0000

Быстрый старт#

От нуля до первого поиска за пять команд. Предполагается, что tgs уже установлен — если нет, смотрите Установку.

1. Аутентификация#

Вход по умолчанию импортирует существующую сессию из Telegram Desktop — без номера телефона и кода:

tgs login

Другие методы (телефон + код, QR, неинтерактивный вход для AI-агентов) описаны в разделе Аутентификация.

2. Проверка аккаунта#

tgs whoami

Возвращает активный аккаунт в JSON — ваш ID, имя и username.

3. Список ваших чатов#

Посмотрите все диалоги в аккаунте — каналы, группы, пользователей, ботов:

tgs login

Mon, 01 Jan 0001 00:00:00 +0000

Аутентификация в Telegram. Сессия сохраняется локально и используется всеми последующими командами.

Синопсис#

tgs login [flags]

Флаги#

Flag	Short	Default	Description
`--type`	`-T`	`desktop`	Auth method: `desktop`, `code`, or `qr`
`--desktop-dir`	`-d`	(auto-detect)	Path to Telegram Desktop tdata directory
`--passcode`			Telegram Desktop local passcode
`--phone`			Phone number for `code` method
`--code`			Verification code (for non-interactive login)
`--password`			2FA cloud password
`--profile`	`-p`	(resolved)	Profile name to authenticate into

Порядок определения профиля, если --profile не указан: переменная TGS_PROFILE -> файл .tgs.yaml -> "default".

tgs profile

Mon, 01 Jan 0001 00:00:00 +0000

tgs profile#

Управление профилями аккаунтов.

Синопсис#

tgs profile <subcommand> [flags]

Подкоманды#

tgs profile list#

Список всех профилей с информацией об аккаунтах.

tgs profile list [flags]

Flag	Short	Default	Description
`--output`	`-o`	`json`	Output format: `json`, `text`

tgs profile list
tgs profile list --output text

* default (@myuser)
 work (@workuser)

JSON (по умолчанию):

[
 {"name":"default","phone":"+79001234567","username":"alice","id":261054642,"active":true},
 {"name":"work","phone":"+79001230000","username":"alice_work","id":342178890,"active":false}
]

Текст (--output text):

* default (@alice)
 work (@alice_work)

Активный профиль отмечен * в текстовом виде и "active": true в JSON. Если ни username, ни телефон не закешированы, выводится только имя профиля.

tgs search messages

Mon, 01 Jan 0001 00:00:00 +0000

tgs search messages#

Поиск сообщений в одном или нескольких чатах, каналах или группах.

Использование#

tgs search messages [query] [flags]

Аргумент query обязателен и задает текст для поиска.

Флаги#

Флаг	Сокр.	Тип	По умолчанию	Описание
`--chat`	`-c`	string[]		Чат для поиска (username, телефон, ID; можно указывать несколько раз или через запятую). Обязателен, если не задан `--folder`.
`--folder`		string	`""`	Искать во всех чатах этой папки (id или имя); пиры папки суммируются с `--chat`
`--from`	`-f`	string		Фильтр по отправителю (username, телефон или ID)
`--filter`		string		Фильтр по типу сообщения (см. допустимые значения)
`--after`		string		Только сообщения после даты (YYYY-MM-DD или unix timestamp)
`--before`		string		Только сообщения до даты (YYYY-MM-DD или unix timestamp)
`--topic`		int	`0`	ID темы форума
`--limit`	`-l`	int	`50`	Максимум сообщений в ответе (1-100)
`--cursor`		string		Курсор пагинации из предыдущего ответа
`--max-wait`		int	`60`	Максимум секунд ожидания при FLOOD_WAIT
`--no-cache`		bool	`false`	Отключить кеш разрешения пиров
`--include-comments`		bool	`false`	Также искать в дискуссионной группе каждого канала
`--profile`	`-p`	string		Имя профиля аккаунта

Порядок определения профиля, если --profile не указан: переменная TGS_PROFILE -> файл .tgs.yaml -> "default".

tgs sources list

Mon, 01 Jan 0001 00:00:00 +0000

tgs sources list#

Перечислить все диалоги Telegram в вашем аккаунте: каналы, супергруппы, группы, пользователей и ботов.

Использование#

tgs sources list [flags]

Флаги#

Флаг	Сокр.	Тип	По умолчанию	Описание
`--type`		string[]	(все)	Фильтр по типу: `channel`, `supergroup`, `group`, `user`, `bot` (повторяемый или через запятую)
`--with-stats`		bool	`false`	Запросить расширенную статистику (всего/за 24ч/первое сообщение + полная информация) для каждого источника
`--limit`	`-l`	int	`0`	Максимум записей в ответе (1-500, 0=все)
`--cursor`		string		Курсор пагинации из предыдущего ответа
`--folder`		string	`""`	Ограничить выдачу чатами внутри этой папки (id или имя), включая архивные; несовместим с `--cursor`
`--archived`		bool	`false`	Включить архивированные диалоги (игнорируется при `--folder` — папка и так содержит свои архивные чаты)
`--max-wait`		int	`60`	Максимум секунд ожидания при FLOOD_WAIT
`--no-cache`		bool	`false`	Отключить кеш пиров и статистики
`--profile`	`-p`	string		Имя профиля аккаунта

Порядок определения профиля, если --profile не указан: переменная TGS_PROFILE -> файл .tgs.yaml -> "default".

Аутентификация

Mon, 01 Jan 0001 00:00:00 +0000

Аутентификация#

tgs подключается к Telegram через ваш реальный аккаунт по протоколу MTProto. Аутентификация нужна один раз для каждого профиля — сессия сохраняется локально и используется повторно при последующих командах.

Быстрый старт#

Метод по умолчанию импортирует существующую сессию из Telegram Desktop:

tgs login

Или выберите другой метод:

tgs login --type code # Phone number + SMS/Telegram code
tgs login --type qr # Scan QR code from another device

Методы входа#

Импорт из Desktop (по умолчанию)#

Импортирует существующую сессию из Telegram Desktop. tgs автоматически определяет директорию tdata на macOS, Linux и Windows.

tgs logout

Mon, 01 Jan 0001 00:00:00 +0000

tgs logout#

Отзывает текущую сессию на серверах Telegram и удаляет локальные данные сессии.

Синопсис#

tgs logout [flags]

Флаги#

Flag	Short	Default	Description
`--profile`	`-p`	(resolved)	Profile to log out from

Порядок определения профиля, если --profile не указан: переменная TGS_PROFILE -> файл .tgs.yaml -> "default".

Примеры#

# Logout the current profile
tgs logout

# Logout a specific profile
tgs logout --profile work

Вывод#

JSON (по умолчанию):

{"profile":"default","status":"logged_out"}

Текст (--output text):

Logged out (profile: default)

Если профиль не залогинен, команда завершается ненулевым кодом и пишет ошибку в stderr.

tgs search global

Mon, 01 Jan 0001 00:00:00 +0000

tgs search global#

Глобальный поиск сообщений по всем чатам, каналам и группам.

Использование#

tgs search global [query] [flags]

Аргумент query обязателен и задает текст для поиска.

Флаги#

Флаг	Сокр.	Тип	По умолчанию	Описание
`--channels-only`		bool	`false`	Искать только в каналах; несовместим с `--folder`
`--groups-only`		bool	`false`	Искать только в группах; несовместим с `--folder`
`--users-only`		bool	`false`	Искать только в личных чатах; несовместим с `--folder`
`--archived`		bool	`false`	Искать в архиве (папка ID 1); игнорируется при `--folder`
`--folder`		string	`""`	Искать только в этой папке (id или имя), включая архивные чаты; несовместим с `--channels-only`, `--groups-only`, `--users-only`
`--filter`		string		Фильтр по типу сообщения (см. допустимые значения)
`--after`		string		Только сообщения после даты (YYYY-MM-DD или unix timestamp)
`--before`		string		Только сообщения до даты (YYYY-MM-DD или unix timestamp)
`--limit`	`-l`	int	`50`	Максимум сообщений в ответе (1-100)
`--cursor`		string		Курсор пагинации из предыдущего ответа
`--max-wait`		int	`60`	Максимум секунд ожидания при FLOOD_WAIT
`--profile`	`-p`	string		Имя профиля аккаунта

Порядок определения профиля, если --profile не указан: переменная TGS_PROFILE -> файл .tgs.yaml -> "default".

tgs sources inspect

Mon, 01 Jan 0001 00:00:00 +0000

tgs sources inspect#

Получить подробную информацию об одном источнике Telegram. Работает как для подписанных, так и для публичных каналов, на которые вы не подписаны.

Использование#

tgs sources inspect <ref> [flags]

Аргумент ref идентифицирует целевой источник. Поддерживаемые форматы:

Формат	Пример	Описание
`@username`	`@durov`	Публичный username с префиксом `@`
`username`	`durov`	Публичный username без префикса
`id:<n>`	`id:-1001234567890`	Telegram peer ID (рекомендуется для отрицательных ID — pflag воспринимает голый `-N` как флаг)
Числовой ID	`12345`	Положительный peer ID. Для отрицательных используйте форму `id:` выше или вставьте `--` (например `inspect -- -1001234567890`)
Номер телефона	`+79001234567`	Для контактов и собственного аккаунта
`-` или `@me`	`-`	«Избранное» (“Saved Messages”)

Флаги#

Флаг	Сокр.	Тип	По умолчанию	Описание
`--no-stats`		bool	`false`	Пропустить расширенную статистику (всего/за 24ч/первое сообщение)
`--no-cache`		bool	`false`	Отключить кеш пиров и статистики
`--max-wait`		int	`60`	Максимум секунд ожидания при FLOOD_WAIT
`--profile`	`-p`	string		Имя профиля аккаунта

Порядок определения профиля, если --profile не указан: переменная TGS_PROFILE -> файл .tgs.yaml -> "default".

tgs whoami

Mon, 01 Jan 0001 00:00:00 +0000

tgs whoami#

Показывает текущий профиль и информацию об аккаунте. Читает данные из локального хранилища — подключение к Telegram не требуется.

Синопсис#

tgs whoami [flags]

Флаги#

Flag	Short	Default	Description
`--profile`	`-p`	(resolved)	Profile to inspect
`--output`	`-o`	`json`	Output format: `json`, `text`

Порядок определения профиля, если --profile не указан: переменная TGS_PROFILE -> файл .tgs.yaml -> "default".

Примеры#

# Show current profile (JSON output)
tgs whoami

# Human-readable output
tgs whoami --output text

# Inspect a specific profile
tgs whoami --profile work

# Inspect a profile with text output
tgs whoami --profile work --output text

Вывод#

Profile: work
User: John Doe (id: 123456789)
Handle: @johndoe
Phone: +1234567890

{
 "profile": "work",
 "user": {
 "id": 123456789,
 "phone": "+1234567890",
 "username": "johndoe",
 "first_name": "John",
 "last_name": "Doe"
 }
}

Если профиль существует, но вход не выполнен, поле user будет null (JSON) или "Not logged in" (текст).

Профили

Mon, 01 Jan 0001 00:00:00 +0000

Профили#

tgs поддерживает несколько аккаунтов Telegram через профили — по аналогии с профилями AWS CLI. У каждого профиля своя независимая сессия, хранящаяся в отдельном файле базы данных.

Порядок определения профиля#

При запуске любой команды tgs активный профиль определяется по следующему приоритету (от высшего к низшему):

Флаг --profile, переданный команде
Переменная окружения TGS_PROFILE
Файл .tgs.yaml в текущей или родительской директории
"default" (значение по умолчанию)

Профили для отдельных директорий#

Вы можете привязать профиль к директории, создав файл .tgs.yaml. Используйте tgs profile switch для автоматического создания:

tgs search counters

Mon, 01 Jan 0001 00:00:00 +0000

tgs search counters#

Получение количества сообщений по типам (фото, видео, документы и т.д.) для одного или нескольких чатов.

Использование#

tgs search counters [flags]

Команда не принимает позиционных аргументов.

Флаги#

Флаг	Сокр.	Тип	По умолчанию	Описание
`--chat`	`-c`	string		Чат для запроса (username, телефон или ID). Обязателен, если не задан `--folder`.
`--folder`		string	`""`	Запросить все чаты в этой папке (id или имя); вывод включает разбивку по чатам и агрегированные итоги
`--topic`		int	`0`	ID темы форума
`--filters`		string[]		Типы фильтров для подсчета (через запятую; по умолчанию: все). См. допустимые значения
`--max-wait`		int	`60`	Максимум секунд ожидания при FLOOD_WAIT
`--no-cache`		bool	`false`	Отключить кеш разрешения пиров
`--profile`	`-p`	string		Имя профиля аккаунта

Порядок определения профиля, если --profile не указан: переменная TGS_PROFILE -> файл .tgs.yaml -> "default".

tgs sources folders

Mon, 01 Jan 0001 00:00:00 +0000

tgs sources folders#

Перечисляет папки Telegram пользователя (диалоговые фильтры из интерфейса) и раскрывает содержимое каждой из них так, как это делает клиент Telegram — применяя закреплённые / включённые / исключённые пиры и автоматические правила (контакты, группы и т.д.) к полному списку диалогов.

Папка «Все чаты» по умолчанию исключается из вывода; отображаются только пользовательские папки и чат-листы.

Использование#

tgs sources folders [flags]

Флаги#

Flag	Short	Type	Default	Description
`--max-wait`		int	`60`	Max seconds to wait on FLOOD_WAIT
`--no-cache`		bool	`false`	Disable peer cache
`--profile`	`-p`	string		Account profile name

Порядок определения профиля, если --profile не указан: переменная TGS_PROFILE -> файл .tgs.yaml -> "default".

Поиск

Mon, 01 Jan 0001 00:00:00 +0000

Поиск#

tgs предоставляет четыре подкоманды поиска, которые напрямую отображаются на методы поиска MTProto в Telegram. Весь вывод — это JSON, что упрощает передачу в jq, скармливание AI-агенту или программную обработку.

Поиск в чате#

Самая частая операция: поиск сообщений в конкретном чате.

tgs search messages "docker compose" -c @devops_notes

Аргумент запроса обязателен. Флаг -c / --chat указывает, в каком чате искать. Все поддерживаемые форматы см. в разделе Резолв чатов ниже.

Несколько чатов#

Передайте несколько чатов, повторив флаг или указав значения через запятую:

tgs search calendar

Mon, 01 Jan 0001 00:00:00 +0000

tgs search calendar#

Получение результатов поиска сообщений, сгруппированных по дате, для одного или нескольких чатов и типа фильтра.

Использование#

tgs search calendar [flags]

Команда не принимает позиционных аргументов.

Флаги#

Флаг	Сокр.	Тип	По умолчанию	Описание
`--chat`	`-c`	string		Чат для запроса (username, телефон или ID). Обязателен, если не задан `--folder`.
`--folder`		string	`""`	Запросить все чаты в этой папке (id или имя); вывод включает массивы по каждому чату и агрегированные итоги
`--filter`		string		Фильтр по типу сообщения (см. допустимые значения). Обязательный.
`--max-wait`		int	`60`	Максимум секунд ожидания при FLOOD_WAIT
`--no-cache`		bool	`false`	Отключить кеш разрешения пиров
`--profile`	`-p`	string		Имя профиля аккаунта

Порядок определения профиля, если --profile не указан: переменная TGS_PROFILE -> файл .tgs.yaml -> "default".

Источники

Mon, 01 Jan 0001 00:00:00 +0000

Источники#

tgs sources позволяет перечислить и изучить диалоги Telegram в вашем аккаунте — каналы, супергруппы, группы, пользователей и ботов. Весь вывод в формате JSON, удобном для обработки через jq или AI-агентов.

Пайп в jq: диагностические логи ([tgs] retry: …, [tgs] FLOOD_WAIT: …) пишутся в stderr, а JSON — в stdout. При пайпе в jq глушите stderr, чтобы парсер не подавился:
tgs sources list --with-stats 2>/dev/null | jq '.sources[].title'
Избегайте 2>&1 | jq … — это смешает логи со stdout и сломает разбор JSON.

Переменные окружения

Mon, 01 Jan 0001 00:00:00 +0000

Переменные окружения#

Все переменные окружения tgs опциональны. Они переопределяют значения, вкомпилированные в бинарник, или значения из конфигурационных файлов.

Переменные#

Variable	Description
`TGS_PROFILE`	Active profile name. Overrides `.tgs.yaml` but is overridden by `--profile` flag.
`TGS_API_ID`	Telegram API ID. Overrides the value compiled into the binary.
`TGS_API_HASH`	Telegram API Hash. Overrides the value compiled into the binary.
`TGS_CONFIG_DIR`	Config directory. Takes precedence over `XDG_CONFIG_HOME`. Default: `$XDG_CONFIG_HOME/tgs`, falling back to `~/.config/tgs`.
`TGS_DATA_DIR`	Data directory for session databases. Takes precedence over `XDG_DATA_HOME`. Default: `$XDG_DATA_HOME/tgs`, falling back to `~/.local/share/tgs`.
`XDG_CONFIG_HOME`	Base config directory (XDG spec). Used as `$XDG_CONFIG_HOME/tgs` when `TGS_CONFIG_DIR` is unset.
`XDG_DATA_HOME`	Base data directory (XDG spec). Used as `$XDG_DATA_HOME/tgs` when `TGS_DATA_DIR` is unset.

Выбор профиля#

# Use the "work" profile for one command
TGS_PROFILE=work tgs whoami

# Use the "work" profile for the whole shell session
export TGS_PROFILE=work

Подробнее см. Порядок определения профиля.

Введение on tgs

Установка

Установка#

Homebrew (macOS и Linux)#

Готовые бинарники#

macOS и Linux#

Windows#

Сборка из исходников#

Быстрый старт

Быстрый старт#

1. Аутентификация#

2. Проверка аккаунта#

3. Список ваших чатов#

tgs login

tgs login#

Синопсис#

Флаги#

tgs profile

tgs profile#

Синопсис#

Подкоманды#

tgs profile list#

tgs search messages

tgs search messages#

Использование#

Флаги#

tgs sources list

tgs sources list#

Использование#

Флаги#

Аутентификация

Аутентификация#

Быстрый старт#

Методы входа#

Импорт из Desktop (по умолчанию)#

tgs logout

tgs logout#

Синопсис#

Флаги#

Примеры#

Вывод#

tgs search global

tgs search global#

Использование#

Флаги#

tgs sources inspect

tgs sources inspect#

Использование#

Флаги#

tgs whoami

tgs whoami#

Синопсис#

Флаги#

Примеры#

Вывод#

Профили

Профили#

Порядок определения профиля#

Профили для отдельных директорий#

tgs search counters

tgs search counters#

Использование#

Флаги#

tgs sources folders

tgs sources folders#

Использование#

Флаги#

Поиск

Поиск#

Поиск в чате#

Несколько чатов#

tgs search calendar

tgs search calendar#

Использование#

Флаги#

Источники

Источники#

Переменные окружения

Переменные окружения#

Переменные#