ktalk-cli

CLI ktalk — интерфейс командной строки для тех, кто работает с записями видеовстреч Контур.Толк (KTalk) программно: читает записи, транскрипты и саммари, управляет расписанием, ведёт локальный реестр обработки записей на SQLite. Годится и как самостоятельный инструмент, и как предусловие плагина Claude Code ktalk — подробнее в разделе «Пакет и плагин Claude Code» ниже.

Раньше пакет назывался ktalk-mcp и, помимо CLI, поднимал MCP-сервер для Claude Code (инструменты вида ktalk_list_recordings). Этот слой снят целиком — MCP в пакете больше нет, единственная точка входа — команда ktalk. Пришли по старой ссылке или ищете ktalk-mcp — это тот же проект под новым именем, старый пакет дальше не развивается (о конфликте имени команды при апгрейде — ниже, в «Установке»).

Умеет:

• Список записей конференций и детали одной записи.
• Транскрипты (речь по спикерам с таймкодами, с чанкингом для длинных).
• Саммари и протоколы встреч.
• Полный состав участников записи (обходит лимит в 6 из списковых ответов).
• Скачивание видеофайла записи.
• Историю чата встречи.
• Конфигурацию комнаты и календарь запланированных встреч.
• Предпросмотр и создание новой встречи — создание требует интерактивного терминала и явного подтверждения, см. «Планирование встречи» ниже.
• Диагностику авторизации — жив ли токен и почему запрос не проходит.
• Операционный реестр обработки записей на SQLite — синхронизация, статусы, markdown-зеркало для git, см. «Реестр записей» ниже.

Установка

Требуется Python 3.12+ и uv.

uv tool install ktalk-cli

Или через pip:

pip install ktalk-cli

Если на машине уже стоит старый ktalk-mcp (он тоже владел командой ktalk), uv tool install ktalk-cli откажет: uv не отдаёт занятое имя команды второму пакету молча. Сначала освободите имя:

uv tool uninstall ktalk-mcp
uv tool install ktalk-cli

Проверка версии — после установки или обновления:

ktalk --version    # печатает, например: ktalk-cli 2.1.0

Обновление до последней версии — та же команда install, только upgrade:

uv tool upgrade ktalk-cli

Авторизация

С версии 3.0.0 CLI работает только через session token (кука браузера) — режим персонального API-ключа (KTALK_PERSONAL_API_KEY) снят целиком (ADR-025): он конкурировал с сессией молча (при обеих заданных переменных побеждал ключ без объяснения в тексте отказа) и диагностика auth-status объявляла заведомо невалидный ключ «валидным» на 403.

Цена снятия для тех, кто держал постоянный ключ: персональный ключ не протухал без предупреждения, session token — протухает. Постоянная работа теперь требует ручного обновления токена по мере его протухания (ktalk token set -, см. ниже) — это не восстанавливается автоматически снятием ключа.

Переменная KTALK_PERSONAL_API_KEY, если она всё ещё задана в окружении, не читается как credential ни на одном шаге — CLI печатает об этом одно предупреждение на stderr при каждом вызове и продолжает работу на сессионном токене.

Session token

Session token — токен вашей браузерной сессии Толка. Единственный поддерживаемый источник credential (ADR-025). Живёт недолго и протухает без предупреждения — при регулярной работе повторяйте те же два шага ниже, когда команда начнёт отказывать кодом авторизации.

Два шага. На вкладке, где вы залогинены в https://your-domain.ktalk.ru, откройте DevTools (F12, или Cmd+Option+I на Mac) → Console и выполните:

copy(JSON.parse(localStorage.session).data.token)

Токен — в буфере обмена. Положите его в файл одной командой:

pbpaste | ktalk token set -          # macOS
xclip -o | ktalk token set -         # Linux (X11)

Команда сама создаёт ~/.config/ktalk-mcp/token с правами 0600 (каталог — 0700), отвергает значение, не похожее на токен, и никогда не печатает его в вывод. Проверка:

ktalk token status    # есть ли файл, права, маска значения
ktalk auth-status     # жива ли авторизация — реальный запрос, не имитация

Путь переопределяется переменной KTALK_TOKEN_FILE; каталог уважает XDG_CONFIG_HOME.

Порядок источников — первый непустой выигрывает:

Ни один запрос не несёт заголовок X-Auth-Token — единственный транспорт credential теперь query-параметр sessionToken.

Путь ~/.config/ktalk-mcp/token не переименован вместе с пакетом и остаётся таким намеренно: он выбран независимо от имени дистрибутива (каталог ktalk/ уже занят другим — санкцией на запись, у неё свой жизненный цикл), а смена пути молча лишила бы уже настроенные машины третьего источника авторизации.

Токен из файла обслуживает и чтение, и запись: создание и отмена встречи шлют то же значение другим транспортом (заголовок Authorization: Session, а не query-параметр) — источник значения транспорт не меняет. Санкция на запись при этом остаётся обязательной, она к токену отношения не имеет.

Файл с правами шире 0600 читается так, будто его нет (ktalk token status покажет usable: False) — секрет не должен молча читаться с диска, доступного другим пользователям машины.

Важно: session token имеет ограниченный срок жизни. Если команда возвращает ошибку авторизации, повторите те же два шага — ktalk token set - перезаписывает файл, права переставлять не нужно.

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

export KTALK_SESSION_TOKEN="ваш_session_token"
export KTALK_BASE_URL="https://your-domain.ktalk.ru"

Переменная не обязательна: без неё читается файл ~/.config/ktalk-mcp/token (см. «Session token»).

Также поддерживается файл .env в рабочей директории:

KTALK_SESSION_TOKEN=ваш_session_token
KTALK_BASE_URL=https://your-domain.ktalk.ru

Диагностика авторизации

Проверьте авторизацию без запроса записей:

ktalk auth-status

Диагностика различает два случая, которые снаружи выглядят одинаково — просто ошибка, — но чинятся по-разному:

• 401 — токен невалиден либо истёк. Обновите его: ktalk token set - (или переменную KTALK_SESSION_TOKEN, если она задана).
• 403 — токен рабочий, но у текущей сессии нет прав на эту операцию. Перевыпускать токен не нужно.

У session token понятия scope и срока действия нет — диагностика выполняет реальный пробный запрос (список записей), а не имитацию без сети.

--json-ответ — {"alive": bool, "note": str | None}. Отказ пробного запроса виден по обоим каналам сразу: поле alive: false в теле ответа И ненулевой код возврата процесса — полагаться только на один из двух нельзя.

Команды чтения записей и справочников

Все команды поддерживают --json (валидный JSON в stdout; ошибки — в stderr с ненулевым кодом возврата).

Коды возврата

Планирование встречи

Создание встречи — единственная операция пакета, которая что-то меняет вне вашего компьютера: она рассылает приглашения реальным людям. Удаление созданного события эти письма не отзывает. Из-за этого создание устроено умышленно неудобно:

• Создание — команда ktalk create-meeting-confirm. Она работает только в интерактивном терминале (проверяет, что и ввод, и вывод — реальный TTY) и перед отправкой печатает предпросмотр и требует набрать слово да.
• Предпросмотр без создания — ktalk create-meeting-preview, не делает ни одного сетевого запроса.
• Обе команды используют session token — единственный оставшийся режим авторизации (ADR-025).

Ни одно поле не имеет значения по умолчанию (кроме описания встречи — пустая строка, если не задано). Тема, начало, конец, часовой пояс, комната, участники, анонимный доступ, PIN — каждое нужно передать явно; иначе команда откажет и назовёт, какого поля не хватает. Так сделано намеренно: молчаливый часовой пояс сдвинет встречу в календаре участников на другое время, а молчаливая автозапись незаметно для организатора изменит, записывается ли встреча.

Из этого вытекают практические следствия:

• Часовой пояс принимает только форму GMT±N (пример GMT+3) — IANA-имена вида Europe/Moscow, смещения ISO и аббревиатуры сервер не распознаёт.
• --enable-auto-recording и --allow-anonymous принимают только явные true или false — «флаг просто не указан» не считается ответом.
• «Встреча без обязательных участников» — это отдельный флаг --no-required-attendees, а не просто отсутствие --required-attendee-key. Значение --required-attendee-key — числовой id участника, не логин.
• «Без PIN» — отдельный флаг --no-pin-code, а не пустая строка в --pin-code.
• --anonymous-access-expiration обязателен, только если --allow-anonymous true.

Повторяющиеся встречи в этой версии не поддерживаются — можно создать только разовое событие.

При сетевом сбое во время создания команда не повторяет запрос сама: если сеть оборвалась, неизвестно, ушло приглашение или нет, и автоматический повтор рискует создать дубль. Решение о повторной попытке — за вами; перед ней стоит проверить ktalk list-calendar, не появилась ли встреча уже.

Создание встречи ещё ни разу не выполнялось на боевом окружении — команда реализует задуманное поведение, но не проверена живым вызовом.

# Предпросмотр — без сети, без побочных эффектов
ktalk create-meeting-preview \
  --subject "Синк по проекту" \
  --start 2026-08-20T10:00:00 --end 2026-08-20T10:30:00 --timezone GMT+3 \
  --room-name "Переговорная 1" \
  --no-required-attendees \
  --enable-auto-recording false --allow-anonymous false \
  --no-pin-code

# Создание — только в интерактивном терминале, требует ввода "да"
ktalk create-meeting-confirm \
  --subject "Синк по проекту" \
  --start 2026-08-20T10:00:00 --end 2026-08-20T10:30:00 --timezone GMT+3 \
  --room-name "Переговорная 1" \
  --required-attendee-key 123 --required-attendee-key 456 \
  --enable-auto-recording false --allow-anonymous false \
  --no-pin-code

API

CLI работает с KTalk Web API через единственный (session token) режим авторизации (см. «Авторизация» выше) — query-параметр sessionToken, внутренний недокументированный контур API:

Архив встреч (list-archive) недоступен: под session token у него нет и никогда не было рабочего пути (ADR-025) — команда отказывает до сети с явным сообщением.

OpenAPI спецификация talk.public.api-api-2.json включена как справочник, но содержит расхождения с реальным API (пути, формат авторизации, структура ответов). Пути, достижимые только под снятым режимом персонального ключа (X-Auth-Token), больше не применимы к этому CLI.

Реестр записей (ktalk)

Та же команда ktalk ведёт операционный реестр обработки записей на SQLite. Вся детерминированная механика (синхронизация списка записей, дедуп, экспирация, смена статусов, рендер дашборда и markdown-зеркала, разовая миграция) живёт в коде, а не в рассуждениях модели.

SQLite — операционный source of truth. Markdown-файл registry.md — генерируемое read-only зеркало для git (ktalk export), руками не редактируется.

Путь к базе: флаг --db PATH > переменная KTALK_REGISTRY_DB > дефолт 95_TRANSCRIPTS/.registry.db (относительно текущего каталога). Бинарную БД нужно добавить в .gitignore (.registry.db, .registry.db-wal, .registry.db-shm).

ktalk auth-status, ktalk create-meeting-preview и ktalk create-meeting-confirm реестр не открывают вовсе — им он не нужен. В частности, auth-status работает даже если файла базы данных нет или он недоступен. Планирование встречи — отдельный раздел «Планирование встречи» выше.

Несколько фоновых агентов могут безопасно писать параллельно (WAL + busy_timeout

• транзакция на операцию).

Разработка

git clone https://github.com/mdemyanov/ktalk-cli.git
cd ktalk-cli
uv sync

# Запуск тестов
uv run pytest -v

# Линтинг
uv run ruff check .

# Локальный запуск CLI (session token — см. «Авторизация»)
KTALK_SESSION_TOKEN=... KTALK_BASE_URL=... uv run ktalk auth-status

Пакет и плагин Claude Code

ktalk-cli работает и сам по себе, и как предусловие плагина Claude Code ktalk. Плагин не обращается к KTalk напрямую и не поднимает MCP-сервер — он вызывает эту же команду ktalk как единственную точку входа в контур.

Плагин пинует точную версию пакета (не нижний порог: «ровно эта версия», не «эта или новее») в собственном файле совместимости. Если что-то в интеграции с плагином ведёт себя не так, как описано в его документации, — первым делом сверьте версию:

ktalk --version    # см. «Проверка версии» в разделе «Установка»

Версия не совпадает с той, что требует плагин, — обновите пакет тем же способом, что при установке (uv tool upgrade ktalk-cli, см. «Установка»); не совпадает в другую сторону (пакет новее, чем ожидает плагин) — не откатывайте его самостоятельно, сверьтесь с тем, кто настраивал плагин.

Проблемы и вопросы

Нашли баг, некорректное поведение или неточность в документации — заведите issue в этом репозитории: https://github.com/mdemyanov/ktalk-cli/issues.

Лицензия

MIT