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 из списковых ответов).

• Скачивание видеофайла записи.

• Архив встреч и историю чата (только с персональным API-ключом).

• Конфигурацию комнаты и календарь запланированных встреч (только с session token).

• Предпросмотр и создание новой встречи — создание требует интерактивного терминала и явного подтверждения, см. «Планирование встречи» ниже.

• Диагностику авторизации — какой ключ/токен активен и почему запрос не проходит.

• Операционный реестр обработки записей на 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

Авторизация

CLI поддерживает два способа авторизации: session token (кука браузера) и персональный API-ключ. Способы исключают друг друга: если задать обе переменные, побеждает KTALK_PERSONAL_API_KEY — KTALK_SESSION_TOKEN в этом случае вообще не читается. Не задать ни один — команда завершится понятной ошибкой.

Персональный API-ключ не привязан к браузерной сессии и не протухает без предупреждения, в отличие от session token. Берите его, если нужна стабильная работа без ручного обновления, а не только разовый запрос.

Session token

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

Два шага. На вкладке, где вы залогинены в 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.

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

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

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

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

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

Персональный API-ключ

Персональный API-ключ выдаётся в админке Толка на конкретного пользователя на настраиваемый срок и не зависит от того, открыт ли браузер. Передаётся заголовком X-Auth-Token, а не в URL — секрет не попадает в query-параметры и логи веб-сервера.

Выпускается и ротируется в разделе Управление → API-ключи админки Толка (UI-шаг, CLI-эквивалента нет; экранные шаги здесь не расписываем — актуальный порядок действий смотрите в справке Контура: «Персональный API-ключ доступа в Толке»). Значение ключа показывается один раз в течение часа после создания — не скопировали вовремя, придётся выпускать новый.

Не путайте с ключом пространства. В Толке есть второй, отдельный ключ — пространственный, с заголовком X-API-Key, выдаётся не на пользователя, а на всё пространство целиком. ktalk-cli работает только с персональным ключом (X-Auth-Token); ключ пространства не поддерживается — переменная называется KTALK_PERSONAL_API_KEY, а не KTALK_API_KEY, намеренно, чтобы их не перепутать.

При выпуске ключа в админке выбираются права (scope). Не хватает прав — запрос вернёт 403, и по виду это неотличимо от «ключ невалиден», хотя ключ рабочий (подробнее — «Диагностика авторизации» ниже).

Если реестр ktalk уже накопил записи в session-режиме, перед первым ktalk sync после переключения на персональный ключ обязательно выполните ktalk sync --dry-run. Внутренний и официальный контуры API отдают идентификаторы записей по-разному, и без сверки первый боевой sync под ключом рискует задвоить весь реестр. Команда только сверяет id и ничего не пишет — см. таблицу команд реестра ниже.

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

export KTALK_PERSONAL_API_KEY="ваш_персональный_api_ключ"
# или
export KTALK_SESSION_TOKEN="ваш_session_token"
export KTALK_BASE_URL="https://your-domain.ktalk.ru"

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

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

KTALK_PERSONAL_API_KEY=ваш_персональный_api_ключ
KTALK_BASE_URL=https://your-domain.ktalk.ru

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

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

ktalk auth-status

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

• 401 — ключ или токен невалиден либо истёк. Перевыпустите его.

• 403 — ключ рабочий, но конкретному запросу не хватает прав (scope). Отредактируйте права ключа в админке Толка (см. таблицу в разделе «Персональный API-ключ» выше) — перевыпускать ключ не нужно.

У session token понятия scope нет — диагностика в этом режиме пробным запросом списка записей сообщает только «токен работает / не работает», без прав и срока действия.

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

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

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

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

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

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

• Создание — команда ktalk create-meeting-confirm. Она работает только в интерактивном терминале (проверяет, что и ввод, и вывод — реальный TTY) и перед отправкой печатает предпросмотр и требует набрать слово да.

• Предпросмотр без создания — ktalk create-meeting-preview, не делает ни одного сетевого запроса.

• Обе команды работают только в режиме session token — в режиме персонального ключа создание встречи не подтверждено ни разу и потому отключено.

Ни одно поле не имеет значения по умолчанию (кроме описания встречи — пустая строка, если не задано). Тема, начало, конец, часовой пояс, комната, участники, анонимный доступ, 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-режим — авторизация query-параметром sessionToken, используется внутренний контур API.

• Режим персонального ключа — авторизация заголовком X-Auth-Token, используются официальные пути интеграторского API (talk.public.api-api-2.json).

Транскрипт и саммари используют один и тот же путь в обоих режимах:

Список записей и детали записи используют разные пути в session- и api-key-режимах. Архив встреч, чат, полный состав участников, скачивание файла и диагностика ключа доступны только в режиме персонального ключа (нужные права — в таблице раздела «Персональный API-ключ» выше).

Комната, календарь и создание встречи работают только в режиме session token — в режиме персонального ключа эти операции отказывают осознанно, а не по случайному пробелу: путь на api-key либо не подтверждён вовсе, либо ведёт себя необъяснимо непоследовательно при проверке.

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

Реестр записей (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_PERSONAL_API_KEY — см. «Авторизация»)
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