Перейти к содержанию

CLI

Публикуемая CLI-обёртка @itphx/synth умеет запускать сервер, работать с провайдерами и общаться с моделью прямо из терминала.

Когда удобен CLI

CLI пригодится, чтобы поднять сервер одной командой, быстро спросить модель без открытия браузера или настроить провайдера на машине, где нет доступа к веб-интерфейсу.

Установка

Нужен Node.js 22 или новее.

npm install -g @itphx/synth
synth --version
docker run -p 4300:4300 -e SYNTH_API_KEY=my-secret-key \
  git.itphx.ru/itphx/synth:0.13.10

После запуска откройте http://localhost:4300 и введите тот же ключ.

Запуск сервера: synth serve

Одна команда поднимает ядро и веб-интерфейс:

synth serve --api-key my-secret-key

По умолчанию сервер слушает http://127.0.0.1:4300. Откройте этот адрес в браузере и введите ключ.

Ключ API

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

synth serve --api-key my-secret-key
SYNTH_API_KEY=my-secret-key synth serve

Если ключ не задан, Synth сгенерирует устойчивый локальный ключ, сохранит его в каталоге данных и напечатает при старте. Введите его в интерфейсе при входе.

Ключ — это доступ

Ключ даёт доступ к вашему инстансу Synth и всем инструментам агента. Не передавайте его третьим лицам и не публикуйте в открытых репозиториях.

Основные параметры serve

Параметр Назначение
--port <number> Порт сервера (по умолчанию 4300)
--host <host> Адрес прослушивания (по умолчанию 127.0.0.1)
--api-key <key> Ключ аутентификации
--data-dir <path> Каталог данных (сессии, проекты, настройки)
--home <path> Локальный home-каталог: конфиг и данные в одном месте
--connect <url> Подключиться к корпоративному серверу (гибридный режим)
--restart-mode <mode> Режим перезапуска: disabled (по умолчанию), process (поднимает внешний супервизор), supervisor (локальный dev-запуск)

--restart-mode

Перезапуск из интерфейса (Настройки → Обслуживание) работает, только когда режим не disabled: процесс завершается с кодом 75, а поднимает его супервизор — systemd, Docker, Kubernetes. Флаг командной строки приоритетнее переменной SYNTH_RESTART_MODE. Если сервис поставлен командой synth service install, режим process уже настроен в unit — перезапускать вручную не нужно.

Чат из терминала

Можно общаться с моделью, не открывая браузер.

synth chat "привет" --provider ollama --model qwen3.8:27b
synth chat --provider ollama --model qwen3.8:27b

Введите сообщение и нажмите Enter. Выход — exit или quit.

synth

Команда без аргументов сразу открывает интерактивный чат.

Полезные флаги chat: --provider, --model, --agent, --api-key (ключ провайдера) и --data-dir.

Провайдеры и модели из CLI

Провайдеры хранятся как JSON-файлы в каталоге данных, но управлять ими удобно командой synth config provider.

# Локальные модели через Ollama (рекомендуемая — qwen3.8:27b).
# URL без /v1: type: ollama ходит на нативный /api/chat.
synth config provider add \
  --name ollama --type ollama \
  --url http://localhost:11434 \
  --model qwen3.8:27b

# OpenAI-совместимый API
synth config provider add \
  --name my-openai --type openai \
  --url https://api.openai.com/v1 \
  --model gpt-4o \
  --api-key sk-xxx
synth config provider list
synth config provider delete ollama

Обязательные флаги — --name и --type (openai, anthropic, ollama). Опциональные — --url, --model, --api-key, --num-ctx <n>, --data-dir. Модель по умолчанию задаётся флагом --model; выбрать модель для конкретной сессии и проверить её доступность удобнее в разделе «Провайдеры» веб-интерфейса. Подробнее — Провайдеры и модели.

--num-ctx (контекстное окно Ollama)

--num-ctx <n> (целое > 0) задаёт num_ctx провайдера и есть только у synth config provider add — подкоманды edit нет. То же значение задаётся переменной SYNTH_PROVIDER_OLLAMA_NUM_CTX (имя провайдера в env-форме: OLLAMA → ollama, _ → -) или полем num_ctx/numCtx в POST/PATCH/api/v2/providers(null/''— сброс). Приоритет: явныйnumCtxпровайдера >contextWindow` модели.

num_ctx передаётся в теле запроса к нативному /api/chat, где он применяется (провайдер type: ollama всегда нормализует URL туда). Базовый URL указывайте без суффикса /v1: старый URL с /v1 будет приведён к /api/chat (с предупреждением в лог), а для OpenAI-совместимого пути нужен отдельный провайдер type: openai/generic. Чтобы применить окно на стороне Ollama, задайте его там (OLLAMA_CONTEXT_LENGTH=262144 ollama serve или PARAMETER num_ctx в Modelfile).

Память: synth memory

Команда synth memory управляет индексами памяти (поиск по документам проекта и по фактам). Это тонкий клиент: он обращается к работающему инстансу, поэтому нужен ключ доступа.

synth memory status                      # готовность, провайдер, счётчики
synth memory list --scope instance       # список индексов
synth memory index prj_42 --name docs --source files --filter '**/*.md' --wait
synth memory rebuild idx_7f3a --wait     # пересобрать индекс
synth memory drop idx_7f3a --yes         # удалить индекс

Подробнее — Память агентов.

Сервис инстанса: synth service

Команда synth service ставит инстанс как сервис systemd пользователя (--user): сервис поднимается при старте машины, переживает выход из сессии и поднимается заново после перезапуска.

synth service install          # поставить сервис, включить автозапуск, запустить
synth service status           # unit, автозапуск, PID, состояние health
synth service start            # запустить
synth service stop             # остановить
synth service restart          # перезапустить
synth service enable           # включить автозапуск
synth service disable          # выключить автозапуск
synth service logs -f          # журнал сервиса (journalctl --user -u synth)
synth service uninstall        # снять unit; данные инстанса остаются
Флаг (для install) Назначение
--port <n> / --host <addr> Адрес и порт инстанса
--home <dir> / --data-dir <dir> Локальный home и каталог данных
--config <path> Путь к config.yaml (значения по умолчанию; в unit не пишется)
--connect <url> Адрес удалённого сервера (гибридный режим)
--no-autostart / --no-start / --no-linger Не включать автозапуск / не запускать / не оставлять сеанс живым
--force Перезаписать unit, созданный не этой командой
--print-unit / --dry-run Показать unit и план, ничего не записывая
--json Машиночитаемый вывод

Только Linux + systemd

На других платформах команда сообщает о неподдерживаемости. Секреты в unit и env-файл не попадают: ключ доступа создаёт сам сервер, команда печатает путь к нему.

Подробнее — Обслуживание.

Обновление версии: synth update

Команда проверяет доступные версии и, по требованию, устанавливает их.

synth update --check                  # только проверка: что доступно
synth update --apply                  # установить найденную версию
synth update --channel stable         # канал: auto | stable | beta
synth update --channel beta --check   # что доступно в бета-канале
synth update --to 0.13.10 --apply     # конкретная версия (в т.ч. откат)
synth update --registry <url>         # свой реестр пакетов
synth update --dry-run                # показать план без установки
Флаг Назначение
--check Только проверка, ничего не устанавливать; кэш проверки игнорируется
--apply Установить целевую версию
--channel <auto\|stable\|beta> Канал обновлений (auto — по установленной версии)
--to <version> Точная версия X.Y.Z — обновление или откат
--registry <url> Реестр, переопределяющий реестр канала
--dry-run / --json / -y, --yes План без установки / вывод JSON / без подтверждения

Понижение версии

Переход с бета-канала на стабильный — это понижение версии, и он требует подтверждения. Данные при этом не откатываются: откат пакета и откат данных — разные операции.

Подробнее — Обслуживание.

Реестр MCP: synth mcp

Тонкий клиент к реестру MCP-серверов локального инстанса. Ключ доступа читается внутри процесса и не печатается.

synth mcp list                                   # серверы в реестре
synth mcp add --name playwright --type http \
  --url http://127.0.0.1:8931/mcp               # добавить HTTP-сервер
synth mcp test playwright                       # проверить подключение
synth mcp reconnect playwright                  # переподключить после сбоя
synth mcp remove playwright                     # убрать из реестра

Подробнее — MCP-инструменты.

Гибридный режим

Чтобы работать с локальными и корпоративными проектами в одном интерфейсе, подключите локальное ядро к серверу:

synth serve --connect https://synth.example.com

После запуска войдите в интерфейс логином и паролем (или API-ключом сервера). Подробнее — Гибридный режим.

Что дальше