max-cli

Ваши боты MAX и ваш личный аккаунт — в терминале и в ИИ-агентах. max —
программа для терминала и MCP-сервер: пишите от имени бота через официальный Bot API, а в свои
чаты — сами или руками Claude, Codex, Cursor и других агентов. В группах, которые вы ведёте, —
следите за непрочитанным и сразу реагируйте на проблемы: спам, чужие ссылки, флуд, вопросы без
ответа — по вашим правилам.

max sales bot messages send "Команда продаж" "Сборка готова"   # от имени бота
max messages send "Иван Петров" "Опаздываю на 15 минут"         # от вашего имени

Бот

max bot работает с ботом через официальный Bot API MAX по токену
бота. Ботов может быть несколько: каждый хранится под именем, которое вы выбираете, и это имя —
первое слово команды.

max sales bot auth set                                   # токен — в скрытом вводе, MAX его проверит
max sales bot me                                         # какой это бот
max sales bot api get-updates --limit 10                 # номер группы — в поле chat_id
max sales bot messages send "Команда продаж" "Сборка готова" --file report.pdf
max sales bot recipients add "Команда продаж"            # писать только сюда
max bot list --check                                     # все боты на этом компьютере

Чат называют по номеру или, когда бот его уже видел, по названию; человеку пишут как
user:<номер>. Где взять номер чата — docs/bot.md.

• Сообщения и чаты. Отправка в чат по номеру, человеку как user:<номер> или в чат по
  названию; правка, удаление, чтение, закрепление. chats list — чаты, которые бот видел: списка
  чатов бота у MAX нет.
• Файлы, участники, комментарии, кнопки, меню команд, вебхуки. messages send --file,
  members, admins, comments, callbacks answer, commands, webhooks — у каждой записи тот
  же список получателей и журнал.
• Модерация от имени бота. bot chats check сверяет новое в группе с правилами
  (bot chats rules) и удаляет спам и людей — с запретом вернуться по ссылке. Вступления видит
  bot updates watch, который печатает всё, что происходит в чатах бота.
• Копия переписки на этом компьютере. bot people show <кто> — где человек писал и его личный
  чат с ботом; bot messages search --from <кто> и bot messages between <кто> <кто> — без
  запросов к MAX.
• Бот для агента. max sales bot mcp — MCP-сервер бота: по умолчанию только чтение, запись —
  по флагам --allow-send, --allow-delete, --allow-moderate.
• Любая операция API. Все операции Bot API доступны как max bot api <операция> — с флагами
  для параметров и JSON-телом, которое сверяется со схемой до отправки.
• Бот не напишет лишнего. У каждого бота свой список чатов, куда ему можно писать, и журнал
  всего, что он отправил, — без текста. Профиль только для чтения и allow действуют и на бота.
• Токен не в файле. Токен бота — в системном хранилище паролей, отдельно от вашего.

Бота создают на business.max.ru; MAX выдаёт их подтверждённым
организациям, ИП и самозанятым. Полностью — docs/bot.md.

Личный аккаунт

max без слова bot работает с вашим личным аккаунтом: как ещё одно ваше устройство, со всеми
чатами, историей, группами и контактами.

⚠️ Для личного аккаунта max-cli использует неофициальный внутренний API MAX. API может
измениться без предупреждения, а использование инструмента может нарушать условия сервиса. Вы
используете max-cli на свой риск; авторы и контрибьюторы не несут ответственности за блокировки
аккаунтов, потерю данных или другие последствия. Бот работает через официальный API, и к нему
это не относится.

max chats list --limit 5
max messages list "Иван Петров"
max messages send "Иван Петров" "Опаздываю на 15 минут"

Всё ниже, до раздела «Установка», — про личный аккаунт. Полностью — docs/usage.md.

Как это использовать

Самое полезное — поручить переписку агенту: Claude, Codex или другому. Он читает чаты через max
и делает то, что вы попросили словами.

• Проверка по расписанию. Утром и вечером агент смотрит, что пришло, и присылает короткую
  сводку: кто ждёт ответа, что срочно, что можно не читать.
• Отчёты. Итог недели по рабочему чату: что решили, кто что взял на себя, какие вопросы
  остались без ответа.
• Кто кому должен. max review одним вызовом отдаёт всё, что было в переписке с прошлого
  обзора, — ваши сообщения тоже, голосовые — текстом. Агент раскладывает это на «я должен», «жду от
  других» и «нужно уточнить», а прежде чем назвать что-то просроченным, проверяет рабочие группы:
  может, уже сделано.
• Напоминания. Кому вы обещали ответить и не ответили; чей вопрос висит третий день.
• Черновики ответов. Агент предлагает текст, а отправляете вы — или он сам, если вы разрешили
  писать в этот чат.
• Поиск. «Когда мы договорились о встрече с Иваном?» — ответ с датой и самим сообщением.
• Группа, которую вы ведёте. Какие вопросы висят без ответа, кто вступил за неделю и с каким
  аккаунтом, удалить приглашения в чужие чаты — по вашим правилам и с вашим «да»
  (ниже).

Как это выглядит:

Вы:     Что я кому обещал за последние три дня?
Агент:  (вызывает max review: 12 чатов, 3 голосовых расшифровано)
        Я должен
        · Ивану Петрову — прислать счёт до пятницы. «Иван Петров», 24.09
        Жду от других
        · Ольга — макет к 25.09. В группе «Дизайн» его пока нет
        Нужно уточнить
        · «Проект Альфа»: кто везёт образцы — договорились «потом решим», 25.09
        Следующий обзор — с 26.09, 14:05.
Вы:     Напомни Ольге про макет.
Агент:  Черновик: «Ольга, привет! Как там макет?» Отправить?
Вы:     Да.

Отправлять агент может, только если вы это разрешили, — а с --confirm-send каждое сообщение
ждёт вашего «да». Чтение не ставит отметку «прочитано». Как настроить
агента под каждую задачу — готовые запросы, расписание и ограничения:
docs/recipes.md.

Группы, которые вы ведёте

max review --chat "Поход" --unanswered            # вопросы, на которые сутки никто не ответил
max chats events "Поход"                          # кто вступил и вышел за неделю
max chats members list "Поход"                    # все участники: когда заведён аккаунт
max chats rules set "Поход" invites delete        # приглашения в чужие чаты — удалять
max chats check "Поход" --allow-dangerous         # проверить группу и сделать, что разрешено

Проверка сверяет новое в группе с вашими правилами: заблокированные люди, приглашения, ссылки,
пересланное, флуд, совсем новые аккаунты. По умолчанию она только отмечает. Для каждого действия
вы решаете сами: никогда, только с флагом, с вашим подтверждением или сразу. Сценарии с агентом,
все правила и ограничения — docs/groups.md.

Как это работает

max работает от вашего имени, как ещё одно ваше устройство, а не как бот. Вы входите один раз
по QR-коду, и дальше доступно то же, что в приложении: чаты, сообщения, файлы, группы, контакты и
профиль.

Агенту max подключается одним из двух способов:

• Агент с терминалом — Claude Code, Codex, Gemini CLI. Он сам вызывает команды max. Дайте
  ему навык (skill) — инструкцию, как работать с max: одна команда, см.
  ниже.
• Агент без терминала — Claude Desktop, Cursor и другие клиенты MCP. Подключите max mcp:
  готовую запись для их настроек печатает max mcp config. Там же есть команды /catch-up (что
  нового), /review (кто кому должен), /reply (черновик ответа) и /find (поиск). По умолчанию
  агент только читает. Отправку можно разрешить, в том числе с вашим подтверждением каждого
  сообщения.

Что умеет

• Читать. Чаты, история, одно сообщение вместе с соседними, непрочитанное во всех чатах
  сразу (max inbox), вся переписка с прошлого обзора для разбора «кто кому должен» (max review), новые сообщения по мере прихода (max watch), скачивание вложений,
  расшифровка голосовых в текст на вашем компьютере, выгрузка переписки в JSONL или Markdown.
• Искать. Сообщения — по тексту всего прочитанного, без подключения к MAX. Чаты и контакты —
  по части названия или имени.
• Писать. Текст и разметка, ответы, фото, видео, файлы и голосовые, правка, пересылка, закрепление, реакции,
  опросы, отложенная отправка, удаление — у себя или у всех.
• Вести группы и каналы. Создать группу, вступить по ссылке, выйти, участники и админы,
  название и настройки, ссылка-приглашение, папки. Для админа — вопросы без
  ответа, кто вступил и вышел, все участники с возрастом аккаунта, правила и проверка группы по ним
  (docs/groups.md).
• Контакты и аккаунт. Найти человека по номеру, добавить, удалить, переименовать для себя,
  заблокировать, импортировать из файла; изменить профиль и фото; посмотреть и завершить другие
  сеансы.
• Входить удобным способом. QR-код прямо в терминале, QR-код или SMS через web.max.ru в
  браузере, или готовый токен.

Чем он хорош

• Читает незаметно. Чтение не ставит отметку «прочитано»: собеседник не видит, что вы открыли
  чат. Отметить прочитанным можно, когда нужно: max chats read или --mark-read.
• Агент не напишет лишнего. Есть профиль только для чтения, список чатов, в которые можно
  писать, и лимит сообщений в час. MCP-сервер может показывать вам каждое действие до того, как его выполнить.
  Если имя подходит к двум чатам, max не выбирает сам, а показывает оба.
• Модерация по вашим правилам, а не по чужим. Проверка группы по умолчанию только отмечает.
  Удалить сообщение или человека она может, только если вы разрешили: для каждого действия —
  никогда, с флагом, с вашим подтверждением или сразу. Не больше 10 действий за раз, и ничего не
  следит за группой в фоне.
• Сообщение не уйдёт дважды. Если связь оборвалась во время отправки, max прямо говорит, что
  не знает, дошло ли сообщение, и даёт команду для повтора. MAX узнаёт повтор и второго сообщения не
  создаёт.
• Своя копия переписки. Всё прочитанное сохраняется на вашем компьютере. По ней работает
  быстрый поиск по тексту сообщений, и её можно читать без интернета (--offline). При входе MAX
  присылает только то, что изменилось. Стереть копию — max cache clear.
• Чужой текст не управляет вашим терминалом. Имена, названия чатов, имена файлов и сообщения
  пишут другие люди. Управляющие символы из них показываются как текст, имя всегда печатается в одну
  строку, а автодополнение подставляет только номер чата — поддельную строку переписки или команду в
  оболочке так не подсунуть.
• Пароль от аккаунта не лежит в файле. Токен входа хранится в системном хранилище паролей:
  Keychain в macOS, Secret Service (GNOME Keyring, KWallet) в Linux, диспетчер учётных данных в
  Windows. В историю команд он не попадает.
• Скрипту и агенту легко разобрать ответ. С --json команда отдаёт только данные, в одной и
  той же форме, без текста для человека вокруг. Ошибка приходит отдельно и с номером, поэтому
  скрипт сразу понимает, что случилось: нет входа, чат не найден или MAX не ответил вовремя.
• Разбор проблем без вашей переписки. --trace показывает каждый запрос к MAX, чтобы понять,
  почему команда не сработала. В этой записи нет текстов, имён, телефонов и токена, поэтому её
  можно приложить к сообщению об ошибке. Удачный запуск без флага не записывается, неудачный — всегда, тоже без текстов.

Под заказ

Делаем автоматизацию процессов и инструменты под вашу задачу: интеграции с MAX и другими
мессенджерами, ИИ-агентов, внутренние сервисы. Пишите на [email protected].

Чем отличается от других

Для MAX уже есть хорошие проекты, и max-cli многому у них научился.
PyMax — самая полная библиотека для личного аккаунта; её код
помог разобрать многие операции протокола. Выбирайте то, что подходит под задачу.

Для бота есть max bot — через официальный Bot API, отдельно от личного аккаунта
(docs/bot.md). Таблица выше — про личный аккаунт.

Содержание

• Бот
• Личный аккаунт
• Группы, которые вы ведёте
• Установка
• Вход
• Использование
• Для скриптов и агентов
• Безопасность
• Документация
• Разработка
• Дорожная карта
• Лицензия
• Участие

Установка

Пакет — @leemour/max-cli, команда, которую он ставит, — max.

Запустить, ничего не устанавливая:

npx @leemour/max-cli --help

Поставить насовсем:

npm install -g @leemour/max-cli
max --version

Нужен Node 22 или новее, либо Bun 1.3+. Работает на macOS, Linux и Windows. Подробности,
переменные окружения и то, куда ложатся файлы, — docs/installation.md.

Если после установки команда max не находится, npx @leemour/max-cli doctor скажет почему и
напечатает команду, которая это исправит.

Вход

max session start qr рисует QR-код в терминале: вы сканируете его приложением MAX, и токен входа
сохраняется в системном хранилище паролей. Ещё способы — qr-chrome, sms (оба через web.max.ru в браузере) и token
(docs/sessions.md).

max session start qr                   # QR-код в терминале
max session start                      # или спросит токен, не отображая ввод
pass show max/token | max session start # или из трубы
max account show                       # кто вы

Несколько аккаунтов — несколько профилей, и профиль называется первым словом, а не флагом:

max chats list              # профиль default
max personal chats list     # профиль personal
export MAX_PROFILE=personal # или на всю сессию оболочки

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

Бот пишет в группу, закрепляет объявление и следит за порядком:

max sales bot messages send "Команда продаж" "**Сборка готова**" --format markdown --file report.pdf
max sales bot chats pin "Команда продаж" <mid>          # id сообщения — из ответа на send
max sales bot updates watch                              # всё, что происходит в чатах бота, по мере прихода
max sales bot chats rules set "Команда продаж" links delete
max sales bot chats check "Команда продаж" --dry-run     # что нарушает правила — без действий
max sales bot people show "Иван"                         # где человек писал и его личный чат с ботом

Разговор от своего имени:

max inbox                                         # непрочитанное во всех чатах, ничего не отмечая
max messages list "Иван Петров" --limit 20
max messages send "Иван Петров" "Созвонимся в 15:00?" --reply-to <id>
max reactions add "Иван Петров" <id> 👍
max messages send 0 "Позвонить маме" --at 2h      # напоминание себе в «Избранное» через два часа
max review --since 1d                             # вся переписка за сутки: кто кому что обещал

Группа, которую вы ведёте:

max chats create "Поход" "Аня" "Борис"            # создать и позвать людей
max chats admins add "Поход" "Аня" --can pin,members
max chats link reset "Поход"                      # старая ссылка-приглашение перестаёт работать
max polls create "Поход" "Когда едем?" "Суббота" "Воскресенье"
max review --chat "Поход" --unanswered            # вопросы, на которые сутки никто не ответил
max chats check "Поход" --dry-run                 # спам, чужие ссылки, флуд — по вашим правилам

Найти и сохранить:

max messages search "договор"                     # по всему прочитанному, без сети
max backup messages "Проект Альфа" --last 500 --run
max export messages "Проект Альфа" --format md --output alfa.md

Каждая команда отвечает JSON с --json и пишет в журнал, что отправила, — без текстов.

Полностью: docs/usage.md. Каждая команда и каждая опция:
docs/commands.md — эта страница собирается из самой программы, поэтому описать
версию, которой не существует, она не может.

Для скриптов и агентов

Навык для агентов с терминалом

Навык (skill) — файл с инструкцией, который агент читает перед работой. В навыке max описано,
какие команды есть, что агент делает только по вашей просьбе и как безопасно повторить отправку.
Его понимают Claude Code, Codex и Gemini CLI. Навык ставится одной командой и всегда
той же версии, что и max:

# Claude Code
mkdir -p ~/.claude/skills/max-cli && max skill show > ~/.claude/skills/max-cli/SKILL.md
# Codex и Gemini CLI — общая папка ~/.agents/skills
mkdir -p ~/.agents/skills/max-cli && max skill show > ~/.agents/skills/max-cli/SKILL.md

Как эти агенты находят навыки: Codex,
Gemini CLI.

MCP-сервер для агентов без терминала

Claude Desktop, Cursor и другие клиенты MCP подключаются к max mcp и работают с тем же
аккаунтом. Без --allow-send агент только читает. С --confirm-send перед каждой отправкой вы
видите чат и текст и отвечаете «да» или «нет». Подробно — docs/mcp.md.

claude mcp add max -- max mcp       # Claude Code
max mcp config                      # запись для Claude Desktop, Cursor и других — с полными путями

Команды сервера — /catch-up, /review, /reply, /find — готовые просьбы: агент знает, какие
инструменты вызвать и чего не делать.

Ответы в JSON

max chats list --json

С --json команда печатает только данные в JSON, без таблиц, цвета и подсказок. Так же она
работает, когда её вывод читает другая программа, — например, в конвейере max … | jq. Любой
список — чаты, сообщения, участники, всё у бота — приходит в одной форме:

{ "items": [ … ], "page": 1, "limit": 20, "hasMore": true }

Ошибка приходит отдельно от данных — одной строкой в stderr, а stdout остаётся пустым, поэтому её
нельзя принять за пустой результат:

{"error":{"code":"authentication_error","message":"no session for profile \"default\" — run `max session start`"}}

У каждой ошибки есть номер — код завершения программы. По нему скрипт решает, что делать дальше:
4 — нужно войти, 6 — чат или сообщение не найдены, 9 — MAX не ответил вовремя, 14 —
неизвестно, ушло ли сообщение. Все коды — в docs/commands.md.

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

• Токен входа — в системном хранилище паролей, не в файле и не в строке команды.
• Локальная копия переписки и все служебные файлы доступны только вашему пользователю; от кражи
  диска защищает шифрование диска целиком.
• Перед каждой отправкой, в том числе через фоновый сервер и MCP, max проверяет ограничения
  профиля и пишет строку в журнал — без текста сообщения.
• MCP-сервер с --confirm-send показывает вам каждое действие, которое увидят другие, до того как
  его выполнить; --file не отправляет ключи и скрытые файлы без --allow-any-file.
• Ограничения защищают от агента, которого уговорило прочитанное сообщение, но не от агента,
  который хочет их обойти: против такого нужна граница снаружи — песочница или отдельный
  пользователь.

Подробно — что пишется на диск, что уходит в сеть и чего инструмент не делает никогда:
docs/security.md.

Документация

• docs/installation.md — установка, обновление, куда что ложится
• docs/bot.md — бот: токен, несколько ботов, сообщения, чаты, список получателей, любая операция API
• docs/usage.md — личный аккаунт: вход, чтение, отправка, машинный режим
• docs/sessions.md — токен, хранилище паролей, профили
• docs/configuration.md — настройки, переменные, порядок разрешения
• docs/mcp.md — MCP-сервер: подключение, отправка, соединение с MAX
• docs/groups.md — группы, которые вы ведёте: сценарии с агентом, правила, проверка
• docs/recipes.md — рецепты для агентов: сводки, отчёты, долги, напоминания, расписание
• docs/diagnostics.md — --trace, --record, max runs
• docs/ROADMAP.md — что планируется
• docs/security.md — что пишется на диск, а что никогда
• docs/troubleshooting.md — по симптому: что делать, когда не работает
• docs/commands.md — каждая команда и опция — генерируется из программы
• docs/protocol.md — каждый опкод и откуда известна его форма — генерируется
• docs/dev/ARCHITECTURE.md — как это устроено и какие швы нельзя пересекать
• docs/dev/BACKLOG.md — что осталось

Оглавление целиком — docs/README.md.

Разработка

pnpm install
pnpm lint && pnpm typecheck && pnpm test
pnpm build && pnpm smoke:bun          # собранная команда под вторым рантаймом
pnpm generate                         # переписать сгенерированные файлы

Протокол MAX неофициальный и разобран обратной инженерией: это не Bot API. Каждый опкод и форма
каждого сообщения объявлены один раз в src/spec/, а реестр, типизированный клиент и
docs/protocol.md из них генерируются — и CI падает, если дерево устарело.

Половина, не имеющая отношения к MAX — потоки вывода, рендерер, коды ошибок, хранилище паролей, часы, —
вынесена в @leemour/cli-core и общая с braze-cli.

Дорожная карта

docs/ROADMAP.md.

Лицензия

MIT — см. LICENSE.

Участие

Пулл-реквесты, сообщения об ошибках и предложения приветствуются —
issues. Как устроен код и как его проверять —
docs/dev/ARCHITECTURE.md и docs/dev/TESTING.md.