Настройки

Пользоваться tg можно без создания файла настроек. Флаг — параметр после команды, например --limit 5. Значение по умолчанию используется, если параметр не указан. Переменная окружения — именованная настройка, которую терминал или процесс агента передаёт программе. Файл настроек нужен, когда вы хотите повторно использовать одни и те же значения в разных командах.

Все настройки, переменные окружения и порядок их приоритета. Секреты в файле настроек не хранятся: в нём нет полей для сессии, хеша приложения, номера телефона или идентификатора чата.

Приоритет значенийCopy Anchor Link

Для каждой настройки используется первое заданное значение в этом списке:

1. параметр команды (--limit 50, --record, --timeout 30s)
2. переменная окружения (TG_PROFILE, TG_TIMEOUT)
3. настройки конкретного профиля в файле
4. общие для всех профилей defaults в файле
5. встроенное значение по умолчанию

tg chats list --limit 5     # 5: the option
# "limit": 50 in the profile's entry — when there is no option
# "limit": 30 in "defaults" — when the profile has none either
# 20 — when nothing is set

Не у каждой настройки есть все пять источников. Доступные варианты приведены ниже.

Текущие значенияCopy Anchor Link

tg config show
tg work config show

Команда показывает профиль и источник его имени, профили из файла, путь к файлу и его наличие, а также каждую настройку и источник её значения: flag, переменную окружения, config file, config defaults или default. --json возвращает те же данные одним объектом для скриптов.

В конце списка находится commandTimeoutMs: ограничение времени всей команды из --timeout или TG_TIMEOUT. В файле такой настройки нет.

Если заданы TG_CONFIG_DIR, TG_STATE_DIR или TG_CACHE_DIR, это отмечается в stderr: они также влияют на поиск сессии (Вход и сессии).

⚠ Это просмотр настроек, а не проверка работоспособности. Команда только читает файлы: не открывает базу, не обращается к хранилищу ключей и не подключается к Telegram. Проверить сессию можно через tg doctor --online (Решение проблем).

Файл настроекCopy Anchor Link

config.json находится в каталоге настроек (~/.config/tg-cli/config.json в Linux; пути для остальных систем: Установка).

{
  "defaultProfile": "default",
  "defaults": {
    "sendsPerHour": 10,
    "updateCheck": false
  },
  "profiles": {
    "default": { "limit": 50 },
    "work": { "permissions": { "messages": "readonly", "messages.send": "allow" }, "record": true }
  }
}

Поле defaultProfile верхнего уровня задаёт профиль, если он не указан первым словом команды или через TG_PROFILE.

Разрешения профиляCopy Anchor Link

permissions — объект, в котором каждый ключ задаёт путь команды, а значение — уровень разрешения.

{ "profiles": { "work": { "permissions": { "messages": "readonly", "messages.send": "allow" } } } }

Ключ — путь команды: messages, messages.delete, messages.send, reactions, polls.vote, chats.mark-read, chats.members.remove, contacts, account.sessions.end. Он должен начинаться с ресурса: messages, reactions, polls, topics, chats, contacts, account или bot. Самый конкретный ключ имеет приоритет: в примере выше messages.send разрешён, а остальные изменения сообщений запрещены. Подстановочных знаков нет: messages: readonly не влияет на reactions, polls или chats.

inbox, review, watch, serve и store fetch, export, search показывают сообщения и относятся к messages: messages: deny блокирует и их. config, session, doctor, recipients, mcp и обслуживание самой базы не ограничиваются.

По умолчанию разрешено всё, кроме двух необратимых действий: messages.delete и account.sessions.end имеют уровень ask. Встроенные ограничения могут только усиливаться: messages: readonly запрещает удаление, а messages: allow сохраняет запрос подтверждения, пока вы явно не настроите messages.delete.

tg config set permissions.messages.delete allow     # delete without the question
tg config set permissions.messages.send ask         # ask before every send
tg config unset permissions.messages.delete         # back to the default

Чтобы сделать профиль доступным только для чтения (здесь профиль agent), настройте каждый ресурс:

for key in messages reactions polls topics chats contacts account; do
  tg agent config set permissions.$key readonly
done

Подтверждение перед изменениемCopy Anchor Link

При уровне ask команда tg показывает изменение и спрашивает go ahead? [y/N]. Любой ответ кроме y отменяет действие с кодом 130. --allow-dangerous подтверждает удаление, глобальный --yes — остальные изменения. Без терминала, с --json или --jsonl ответить некому: действие отклоняется с кодом 7, ошибкой confirmation_required и указанием нужного параметра.

Совместимость со старыми настройкамиCopy Anchor Link

readOnly: true задаёт readonly для всех ресурсов. Список в allow (send, forward, reaction, edit, pin, read, delete, groups, contacts, profile, folders, sessions) задаёт этим действиям allow, а остальным — readonly; удаление всё равно требует подтверждения. Ключ в permissions имеет приоритет над обоими вариантами.

Изменение через командуCopy Anchor Link

tg config set limit 50                        # this profile
tg work config set permissions.contacts readonly   # profile "work"; one key at a time
tg config set sendsPerHour 10 --defaults      # every profile
tg config set updateCheck false --defaults    # a setting that exists only under defaults
tg config unset sendsPerHour                  # back to the default

config set проверяет значения по тем же правилам, что и чтение настроек, и не записывает файл, который другая команда затем отклонит.

Опечатки вызывают ошибкуCopy Anchor Link

Неизвестная настройка останавливает любую команду с кодом завершения 3:

config.json is not a valid config:
  profiles.default.limt: unknown setting — the known ones are limit, timeoutMs, …

Если бы ошибочные настройки игнорировались, команда незаметно использовала бы значение по умолчанию. Поэтому ошибкой также считается ключ permissions, не начинающийся с ресурса.

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

Временные отдельные настройкиCopy Anchor Link

Укажите другие пути к трём каталогам, чтобы использовать отдельные настройки, сессию и записи запусков. Обычная сессия не будет видна: запись хранилища ключей тоже меняется.

export TG_CONFIG_DIR=/tmp/tg-try/config TG_STATE_DIR=/tmp/tg-try/state TG_CACHE_DIR=/tmp/tg-try/cache
export MESSAGING_STORE=/tmp/tg-try/messages.db
tg setup

Без MESSAGING_STORE прочитанные этой сессией сообщения всё равно попадут в обычную локальную базу.

ДальшеCopy Anchor Link

• Безопасность — защита через permissions, список получателей и sendsPerHour
• Диагностика — record и keepRunsForDays