express-cli

express-cli

Неофициальный клиент корпоративного мессенджера eXpress с тремя интерфейсами:

• CLI — команды для скриптов и агентов (express-cli chats, send, messages, …);
• TUI — интерактивный терминальный интерфейс (список чатов, треды, отправка);
• MCP-сервер — инструменты для AI-агентов (любой MCP-совместимый клиент).

Всё общение сквозным шифрованием (E2E): nacl.box для ключей + XChaCha20-Poly1305 для тела.

⚠️ Внутренний инструмент. HAR-файлы, дампы трафика и токены не коммитятся (см. .gitignore).

Требования

• Node.js ≥ 22 (используется глобальный WebSocket).
• Аккаунт eXpress и мобильное приложение для входа по QR.

Установка

npm install
npm run setup      # собирает и делает команду express-cli глобальной (build + npm link)

После этого доступна команда express-cli:

express-cli --help
express-cli auth qr

Отдельные шаги, если нужно: npm run build (только сборка, tsup → dist/index.js),затем npm link (глобальная команда) или запуск напрямую — node ./dist/index.js <команда>.

Ниже примеры используют глобальную команду express-cli. Без глобальной установкизамените её на node ./dist/index.js.

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

Вход — по QR-коду (сканируется мобильным приложением eXpress):

express-cli auth qr        # показывает QR, ждёт скан
express-cli auth status    # статус токена
express-cli auth refresh   # обновить токен (ключи не трогает)

При QR-логине CLI получает общий cts-ключ аккаунта прямо из QR-обмена (как телефон/десктоп), поэтому расшифровка работает сразу — без ручного импорта.

Важно: не запускайте auth qr без нужды на разных устройствах бесконтрольно — модель ключей рассчитана на один общий cts-ключ на аккаунт. Подробности и все нюансы E2E — в AGENTS.md.

CLI

express-cli chats list [--type dm|group|channel]   # список чатов (ФИО для личек)
express-cli chats find "Иванов"                     # найти чат → полный UUID
express-cli messages list <chat-id> [--limit N]     # прочитать и расшифровать
express-cli send message "Иванов" "Привет!"         # отправить (по имени или UUID)
express-cli send file "Иванов" ./report.pdf         # отправить файл
express-cli contacts search "Петров"                # глобальный поиск сотрудников
express-cli contacts self                           # свой профиль

Большинство команд поддерживают --output json для пайплайнов.

TUI

express-cli tui

• слева — список чатов (непрочитанные, ФИО в личках), справа — тред, снизу — ввод;
• ↑/↓ — чаты, → — войти в тред, Enter — писать, q — выход;
• t — панель обсуждений (тредов) чата; Enter — открыть обсуждение;
• mentions рендерятся как @Имя, картинки — как 🖼 file + блок-арт превью под курсором.

MCP-сервер

Запускается по stdio, переиспользует тот же E2E-код, что CLI/TUI.

Команда запуска для любого MCP-клиента (stdio transport):

express-cli mcp
# или без глобальной установки:
node /абсолютный/путь/dist/index.js mcp

Инструменты: chats_list, chats_find, messages_list, send_message,contacts_search, contacts_self, wait_for_messages, status.wait_for_messages блокируется до новых входящих (для реакции без поллинга).

Архитектура

src/
  api/        HTTP + WebSocket клиенты, E2E крипта (decrypt.ts), резолв имён
  auth/       QR-логин, обновление токена, ключи
  session/    персистентная WS-сессия (чаты, треды, live-пуши) — для TUI/MCP
  cli/        команды (commander)
  tui/        интерфейс на Ink + React
  mcp/        MCP-сервер над api-слоем
  config/     хранение токенов/ключей (conf), настройки

Токены и ключи хранятся локально через conf (вне репозитория, в конфиге ОС),в код и git не попадают.

Разработка

npm run build      # сборка (tsup)
npm run dev        # watch-сборка
npm run lint       # tsc --noEmit (есть остаточные предупреждения типов)

Глубокая техническая документация по протоколу eXpress, модели ключей и E2E —в AGENTS.md.

Безопасность

• E2E: приватные ключи и токены — только локально (conf), никогда в git.
• HAR-файлы и дампы трафика содержат токены/ключи/личные данные — они в .gitignore.
• Один активный cts-ключ на аккаунт; свежий auth qr/логин на новом устройствезабирает общий ключ через QR-обмен (детали — в AGENTS.md).