installation

Установка

Прочитайте эту страницу перед первым запуском max, при переезде на другой компьютер, при обновлении или удалении. В конце max установлен, вы проверили, что он запускается, и знаете, где он хранит свои файлы. Вход в MAX — следующий шаг, на отдельной странице.

Слова, которые здесь встречаются:

• Пакет npm — способ, которым распространяется max. npm (или pnpm, или Bun) скачивает его и ставит на компьютер команду max. Пакет называется @wirecat/max-cli, а команда, которую он ставит, — max.
• Node или Bun — программа, которая запускает max. Поставьте одну из них заранее.
• PATH — список папок, в которых терминал ищет команду по имени. max запускается просто по имени, только если его папка есть в PATH.
• Ключница (keyring) — хранилище паролей операционной системы. max держит там токен аккаунта.
• Навык (skill) — короткая инструкция для ИИ-агента о том, как работать с max.

Установка ничего не компилирует: для доступа к ключнице используется готовый бинарник. Она не запускает фоновый сервис, не входит в аккаунт и не читает чаты. Фоновый max personal serve появляется позже: его запускает первая обычная команда, которой нужен MAX (setup его не запускает; это настройка serve в настройках).

Что нужно

• Node 22.16+ (ветка 22.x) или 24+ с npm
• или Bun 1.3+ для запуска команды
• Linux, macOS или Windows

Если ключницы на машине нет, токен ложится в файл рядом с настройками, и команда скажет об этом одной строкой.

Установить

npm install -g @wirecat/max-cli
pnpm add -g @wirecat/max-cli
bun add -g @wirecat/max-cli

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

npx @wirecat/max-cli --help
pnpm dlx @wirecat/max-cli --help
bunx @wirecat/max-cli --help

Проверить, что всё встало:

max --version
max --help              # список команд
max personal doctor              # где лежат файлы и есть ли вход; к MAX не подключается

Если установка прошла, а max не находится, npx @wirecat/max-cli doctor скажет почему и какую команду выполнить (max не находится после установки).

Первый запуск

max --help и max personal setup --help работают сразу после установки. max skill show показывает навык и работает до входа. max commands --json перечисляет команды и опции.

Запустите настройку в локальном терминале:

max personal setup --agent codex            # QR-вход и навык агента
max personal setup --help                   # примеры и способы входа

--agent выбирает, какому агенту поставить навык: codex, cursor, claude, gemini, all или none. Выделите около пяти минут: setup проводит через вход, проверяет аккаунт и до пяти чатов. История скачивается отдельно, после выбора чата и объёма. Команда не запускает фоновый сервис. Повторный запуск использует существующую сессию. Поставить навык отдельно: max skill install --for all. Способы входа и что делать, если вход прервался, — в инструкции входа.

Глобальная установка через npm тоже ставит навык агента. По умолчанию — для всех поддерживаемых агентов; MAX_INSTALL_AGENT=codex|cursor|claude|gemini|all|none выбирает агента или отключает установку навыка. В Windows она же сохраняет PATH для новых терминалов. Агенту в уже открытом терминале нужно обновить окружение и прочитать max skill show перед входом. Локальная установка пакета и npx не меняют PATH и не ставят навык.

Windows: одна команда установки

Выполните в PowerShell, когда Node.js 22.16+ или 24+ уже стоит:

& ([scriptblock]::Create((Invoke-RestMethod 'https://wirecat.dev/install.ps1'))) -Tool max -Agent all

Установщик ставит пакет npm, сохраняет записи PATH пользователя, один раз добавляет папку команд npm, обновляет PATH текущего PowerShell и ставит навык. Он проверяет, что max запускается по имени. -Agent codex|cursor|claude|gemini|all|none выбирает, куда ставить навык. Повторный запуск обновляет навык и не дублирует PATH. Политику выполнения PowerShell он не меняет.

Через npm используйте npm.cmd install -g @wirecat/max-cli. Если npm разрешает сценарии установки, пакет добавляет свою папку в PATH пользователя, сохраняя существующие записи, и оставляет рабочий запуск через .cmd. Новый терминал найдёт max по имени. Уже открытый терминал этого не увидит: npm не может изменить PATH терминала, из которого его запустили, — откройте новый.

Если npm пропустил сценарий установки, выполните восстановление из установленного пакета:

$maxNpmPrefix = (npm.cmd prefix -g).Trim()
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$maxNpmPrefix\node_modules\@wirecat\max-cli\install\windows.ps1" -RepairOnly -Prefix $maxNpmPrefix
$env:Path = "$maxNpmPrefix;$env:Path"
max skill install --for all
max --version

Восстановление сохраняет остальные записи PATH и не меняет постоянную политику PowerShell. Повторный запуск не создаёт дубликатов. Диагностика — max personal doctor; другие способы — в разделе max не находится после установки.

Первые команды для чтения чатов — в разделе вход и первые команды.

Из исходников

Нужно, если вы правите код или хотите версию, которая ещё не выпущена.

git clone git@github.com:WireCatLabs/max-cli.git
cd max-cli
pnpm install
pnpm build

Дальше — либо положить команду в PATH:

pnpm link --global      # теперь работает просто `max`

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

node dist/bin/max.js --help

Пакет называется с областью @wirecat/: имя max-cli без области занято чужим пакетом.

Куда всё ложится

Три каталога следуют соглашениям операционной системы, ещё два общие с другими инструментами:

Что	Linux и macOS	Windows
настройки	~/.config/max-cli/	%APPDATA%\max-cli\Config\
состояние	~/.local/share/max-cli/	%LOCALAPPDATA%\max-cli\Data\
кэш	~/.cache/max-cli/	%LOCALAPPDATA%\max-cli\Cache\
общая копия сообщений	~/.local/share/WireCat/wirecat.db	%LOCALAPPDATA%\WireCat\Data\wirecat.db
модели распознавания речи	~/.local/share/WireCat/models/audio/	%LOCALAPPDATA%\WireCat\Data\models\audio\

• настройки — config.json, и credentials.json с токеном, только если на машине нет ключницы.
• состояние — profiles/<имя>.json (устройство и счётчик входов), bots/ (чаты, которые видели боты, и их журнал отправок), записи запусков (runs/) и точка отсчёта inbox --new (inbox/).
• общая копия сообщений — общая с другими инструментами на той же библиотеке, например tg-cli. Её описывает страница Локальная копия.
• модели распознавания речи скачиваются только по вашей команде (max personal models audio download), для распознавания голосовых.

Точные пути на этой машине показывает max personal doctor.

Токен хранится в ключнице операционной системы, а не в файле. В config.json для него нет поля, и схема настроек его не примет.

Каждый каталог можно перенести переменной: MAX_CONFIG_DIR, MAX_STATE_DIR, MAX_CACHE_DIR, MESSAGING_STORE (сам файл общей копии) и WIRECAT_STATE_DIR (папка WireCat: общая копия и модели).

В macOS версии до 0.47.0 держали три первых каталога в ~/Library; первый запуск новой версии один раз переносит их на места из таблицы.

Первый запуск после обновления со старого max один раз переносит общую копию и модели в папку WireCat из ~/.local/share/cli-messaging/ и ~/.cache/cli-common/models/. Если в обоих местах лежат разные копии, max останавливается и называет оба файла; оставьте один и запустите снова (две разные копии).

⚠ Переменные переносят и запись в ключнице. Сессия, сохранённая с MAX_CONFIG_DIR, MAX_STATE_DIR или MAX_CACHE_DIR, не видна команде, запущенной без них: меняется имя службы, под которым лежит токен. Команда ответит «нет сессии», хотя вход выполнен. Это нужно для временного профиля и для тестов. Либо ставьте переменные всегда, либо не ставьте никогда.

Автодополнение

По Tab дополняются команды, действия, флаги и их значения, а на месте чата или человека — номер из общего хранилища выбранного аккаунта, с названием чата или именем рядом. Добавьте одну строку в файл настроек оболочки:

echo 'source <(max complete zsh)' >> ~/.zshrc      # zsh
echo 'source <(max complete bash)' >> ~/.bashrc    # bash
max complete fish | source                         # fish, в config.fish

PowerShell — max complete powershell | Out-String | Invoke-Expression в профиле.

Tab никогда не подключается к MAX: подключение на каждое нажатие — это вход в аккаунт сотни раз подряд. Названия чатов и людей берутся из общего хранилища wirecat.db для аккаунта выбранного профиля. Пока аккаунт не известен или хранилища нет, дополняются только команды и флаги. В командах бота предлагаются чаты из его локального списка. Чат предлагается по id, а название стоит рядом: название с пробелом дошло бы до max двумя словами.

Обновление

При обновлении со старого messages.db сначала сохраните нужные локальные данные. Новая копия — wirecat.db; старый messages.db и его -wal/-shm удаляются при открытии копии по умолчанию. До запуска новой версии остановите старые программы и скопируйте нужный файл со служебными файлами в другую папку. max personal messages sync --all вернёт сообщения с сервера, но не старые локальные заметки или метки. Вход сохраняется (копия и другие версии).

max upgrade           # тем же менеджером пакетов, которым max поставлен: pnpm, npm или bun
max upgrade --check   # только сказать, есть ли новее; ничего не ставит

max upgrade сам не перезапускает фоновый max personal serve. Сервер, который запустила обычная команда, уступает место сам: первая команда новой версии останавливает старый сервер и запускает новый. Сервер, запущенный вручную, продолжает работать на старом коде — перезапустите его сами: max personal server restart. Сам себя max не обновляет никогда.

JSON-ответ обновления

max upgrade --check --json сообщает текущую и доступную версии без установки. Ответ содержит current, latest, newer, installer, command, updated и restarted. restarted — список профилей, серверы которых перезапущены после обновления; у max он всегда пустой.

Раз в сутки max сам спрашивает npm о новой версии и, если она есть, пишет после команды одну строку в stderr — только человеку в терминале: не в --json, не в трубу, не с --quiet, не в CI. Выключается max config set update_check false --defaults.

Из исходников — git pull && pnpm install && pnpm build.

Удаление

Удаление уносит команду, но не данные. Сначала выйдите, пока max ещё стоит. sales ниже — пример имени профиля бота; повторите эту строку для каждого подключённого бота.

max personal server uninstall                   # если ставили фоновую службу
max personal session end                        # выйти и забыть токен ДО удаления команды
max sales bot auth remove              # забыть токен бота из профиля sales
npm uninstall -g @wirecat/max-cli
rm -rf ~/.config/max-cli ~/.local/share/max-cli ~/.cache/max-cli

max personal session end и bot auth remove стирают токены из ключницы. Если сначала удалить команду, запись в ключнице останется — безвредно, но лежать будет.

Общая копия сообщений нужна и другим инструментам. Удаляйте ~/.local/share/WireCat/, только если ею больше ничто не пользуется: там сообщения, которые прочитал каждый из них.

Дальше

Войдите в аккаунт и выполните первые команды.