CLI

ush — командная утилита UniShift: терминал этой машины в веб-клиенте, управление prod-стеком платформы и раннерами на хосте.

Бинарники публикуются на storage.unishift.ru/cli.

Быстрая установка

Linux / macOS:

bash

curl -fsSL https://storage.unishift.ru/cli/install.sh | bash

Скрипт определит ОС и архитектуру, скачает нужный бинарник и установит его в /usr/local/bin/ush (при необходимости через sudo).

Проверка:

bash

ush --help
ush platform --help

Стек платформы ставится командами ush platform — см. также Установка сервисов.

Подключить компьютер как терминал

ush connect поднимает на этой машине CLI-агент. В веб-клиенте он открывается как интерактивный терминал: то, что вы печатаете в браузере, выполняется в PTY на хосте агента.

Установите ush (раздел выше).
В веб-клиенте: меню пользователя → API ключи → создайте ключ.
На машине, которую нужно видеть в браузере:

bash

ush connect
# или без вопросов
ush connect http://localhost:8090 --token YOUR_API_KEY --name my-host

URL — адрес gateway, не веб-клиента.

Среда	URL
PM2, локально	`http://localhost:8090`
Docker на хосте	`http://HOST:18090`
HTTPS за reverse proxy	`https://app.example.com`

Порт UI (4200, 18080) для агента не подходит.

Без флагов команда по шагам спрашивает URL, токен и имя. В обычном терминале после handshake процесс уходит в фон (лог ~/.ush/agent.log, pid ~/.ush/agent.pid). Повторный ush connect останавливает предыдущий агент. --foreground оставляет процесс в этом окне.

В веб-клиенте откройте Настройки (/settings/info), секцию CLI Агенты, и нажмите карточку агента. Откроется страница «Интерактивный терминал» (/settings/cli-agent/<id>). В списке агент есть только у пользователя, чей API-ключ передан в ush connect, и только пока процесс онлайн.

Флаги и сохранённые профили — в ush connect и ush connects.

Параметры установки

Переменные нужно передавать в bash, который выполняет скрипт (не в curl):

bash

# Каталог без sudo
curl -fsSL https://storage.unishift.ru/cli/install.sh \
  | INSTALL_DIR="$HOME/.local/bin" bash

# Другой источник бинарников
curl -fsSL https://storage.unishift.ru/cli/install.sh \
  | BASE_URL=https://storage.unishift.ru/cli bash

Переменная	Назначение	По умолчанию
`BASE_URL`	Откуда качать бинарники и `SHA256SUMS`	`https://storage.unishift.ru/cli`
`INSTALL_DIR`	Куда положить бинарник	`/usr/local/bin`
`BIN_NAME`	Имя файла в `INSTALL_DIR`	`ush`

Если INSTALL_DIR не в PATH, добавьте его или перелогиньтесь.

Ручная установка

Скачайте бинарник под свою платформу и положите в PATH:

Платформа	Файл
Linux amd64	https://storage.unishift.ru/cli/ush-linux-amd64
Linux arm64	https://storage.unishift.ru/cli/ush-linux-arm64
macOS amd64	https://storage.unishift.ru/cli/ush-darwin-amd64
macOS arm64	https://storage.unishift.ru/cli/ush-darwin-arm64
Windows amd64	https://storage.unishift.ru/cli/ush-windows-amd64.exe

Пример (Linux amd64):

bash

curl -fsSL -o ush https://storage.unishift.ru/cli/ush-linux-amd64
chmod +x ush
sudo mv ush /usr/local/bin/ush

Windows

На Windows install.sh не используется — скачайте .exe вручную из таблицы выше.

Обновление CLI

Повторный запуск установщика перезапишет бинарник:

bash

curl -fsSL https://storage.unishift.ru/cli/install.sh | bash

URL платформы (важно)

Раннер подключается к платформе по gRPC (/api/v1/runner-stream). В конфиге нужен адрес gateway, а не веб-клиента.

Порт (prod по умолчанию)	Сервис	Для раннера
`18080`	Веб-клиент (nginx, HTTP/1.1)	нет
`18090`	Gateway (HTTP + gRPC/h2c)	да

Типичная ошибка при URL на UI (:18080):

text

http2: frame too large … looked like an HTTP/1.1 header

Примеры корректного url:

bash

# Self-hosted (HTTP) — нужен insecure
url=http://62.109.4.210:18090
insecure=true

# HTTPS / облако
url=https://app.example.com

Порт 18090 должен быть доступен с хоста раннера (firewall / security group).

Подробнее про общие параметры раннера — в Базовые настройки.

Быстрый старт

bash

# Скачать плагин и сразу запустить (интерактивный опрос url/token/…)
ush install shell --start

# Или без вопросов
ush install shell --start --non-interactive \
  --set url=http://HOST:18090 \
  --set token=YOUR_TOKEN \
  --set insecure=true

ush status

Обязательные поля при старте: url, token (для sql ещё dsn).

Команды

Глобальный флаг: --json — машиночитаемый вывод (где поддерживается).

Платформа

Команда	Кратко
`ush platform install`	Файлы, секреты, миграции, `up -d`
`ush platform update`	Обновить файлы и (опционально) публичные URL
`ush platform upgrade`	Обновить образы установленных сервисов
`ush platform services`	Состояние сервисов (направление, статус, образ)
`ush platform collect`	Собрать логи и диагностику в архив для расследования инцидентов
`ush platform enable` / `disable`	Включить / выключить сервис
`ush platform config`	Просмотр и правка `.env` (секреты маскируются)
`ush platform migrate`	Миграции БД и бакет MinIO
`ush platform ps` / `logs` / `up` / `down`	Статус, логи, старт, стоп

Каталог по умолчанию — /opt/unishift (--dir). Полный сценарий — Установка сервисов.

Терминал

Подключение этой машины к веб-терминалу. Сценарий — Подключить компьютер как терминал.

Команда	Кратко
`ush connect`	Поднять CLI-агент и отпустить терминал
`ush connects`	Список сохранённых подключений

Раннеры

<id> / instance_id — идентификатор инстанса вида shell-eedb1b0f (см. ush status). Это не веб-терминал: раннер выполняет задачи Command Manager.

Команда	Кратко
`ush install`	Скачать плагин и создать инстанс
`ush start`	Запустить инстанс или создать новый
`ush stop`	Остановить инстанс
`ush restart`	Перезапустить инстанс
`ush status`	Список инстансов и ресурсы
`ush logs`	Показать / стримить логи
`ush config get` / `set`	Просмотр и изменение конфига
`ush update`	Обновить бинарник плагина
`ush remove`	Удалить инстанс

connect

Подключает этот компьютер как CLI-агент и даёт веб-терминал в настройках. Как открыть его в браузере — Подключить компьютер как терминал. В интерактивном терминале после handshake процесс уходит в фон. Под PM2 и в других супервизорах процесс остаётся на переднем плане — его держит супервизор.

Без аргументов параметры спрашиваются по шагам: URL gateway, токен, имя.

bash

ush connect
ush connect http://localhost:8090 --token MY_TOKEN --name my-server-agent

Шаг	Параметр	Описание
1	URL	Адрес gateway, не веб-клиента. Локально `http://localhost:8090`, Docker `http://HOST:18090`
2	`--token`, `-t`	API-ключ (меню пользователя → API ключи). В интерактивном опросе обязателен. Под PM2 можно не передавать
3	`--name`, `-n`	Имя в интерфейсе. Enter оставляет `ush-<hostname>`

Токен в фоне не попадает в аргументы процесса. Лог: ~/.ush/agent.log, pid: ~/.ush/agent.pid. Повторный ush connect останавливает предыдущий агент. --foreground оставляет процесс в этом терминале.

В интерфейсе: Настройки → CLI Агенты → Терминал. Параметры также пишутся в ~/.ush/connections.json.

connects

Управление сохранёнными подключениями к платформам Unishift.

bash

ush connects list
ush connects add http://app.example.com --name agent-prod
ush connects remove http://app.example.com

Подкоманда	Описание
`list`	Показать список сохранённых профилей подключений
`add <app_url>`	Добавить профиль подключения в конфигурационный файл
`remove <app_url>`	Удалить профиль подключения из конфигурационного файла

install

Скачивает бинарник плагина с storage под текущую ОС/архитектуру, кладёт его в локальный кэш и регистрирует новый инстанс. Сам по себе процесс раннера не запускает — только готовит инстанс (если не указан --start).

bash

ush install shell
ush install shell --start
ush install shell --set url=http://HOST:18090 --set token=SECRET --set insecure=true --start
ush install shell --start --non-interactive --set url=... --set token=...

Флаг	Описание
`--set key=value`	Параметр конфига (можно несколько раз)
`--start`	Сразу запустить инстанс после установки
`--non-interactive`	Не спрашивать значения в терминале

После первой установки дополнительные инстансы того же плагина создаются без повторного скачивания через ush start shell.

start

Запускает раннер. Аргумент — либо instance_id существующего инстанса, либо имя плагина: тогда создаётся новый инстанс из уже скачанного бинарника.

В интерактивном терминале перед стартом опрашивает конфиг (Enter оставляет значение в [скобках]). Обязательны url и token (для sql ещё dsn).

bash

ush start shell-eedb1b0f
ush start shell --set url=http://HOST:18090 --set token=SECRET
ush start shell --non-interactive --set url=... --set token=...

Флаг	Описание
`--set key=value`	Параметр конфига (можно несколько раз)
`--non-interactive`	Без опроса — только `--set` и сохранённый конфиг

Если инстанс уже running и --set не передан, команда ничего не делает и подскажет сделать restart.

stop

Останавливает работающий инстанс (graceful shutdown процесса раннера). Инстанс остаётся в реестре — его можно снова запустить через start.

bash

ush stop shell-eedb1b0f

restart

Останавливает и сразу запускает инстанс заново. Удобно после смены конфига или чтобы заново пройти опрос параметров. Флаги те же, что у start: --set, --non-interactive.

bash

ush restart shell-eedb1b0f
ush restart shell-eedb1b0f --set insecure=true

status

Показывает все зарегистрированные инстансы: id, плагин, состояние (running / stopped), CPU и память для запущенных процессов.

bash

ush status
ush status --json

logs

Читает лог-файл инстанса (~/.ush/runners/<plugin>/<id>/logs/runner.log).

bash

ush logs shell-eedb1b0f          # последние 50 строк
ush logs shell-eedb1b0f -n 200   # последние 200 строк
ush logs shell-eedb1b0f -f       # стримить новые строки (Ctrl+C — выход)

Флаг	Описание
`-n`, `--lines`	Сколько последних строк показать (по умолчанию 50)
`-f`, `--follow`	Следить за файлом в реальном времени

config

Управление конфигурацией инстанса без правки файлов вручную.

ush config get <id> — показать все ключи: пользовательские и значения по умолчанию (помечены (default)).
ush config set <id> <key> <value> — записать параметр. Если инстанс запущен, изменения применятся только после ush restart <id>.

bash

ush config get shell-eedb1b0f
ush config set shell-eedb1b0f url http://HOST:18090
ush config set shell-eedb1b0f insecure true

Общие ключи: url, token, name, insecure, untagged, temporary, session-timeout, task-timeout, concurrency, tags, description, artifact-tmp. Специфичные для плагина — в Базовые настройки и страницах отдельных раннеров.

update

Скачивает свежую версию бинарника плагина для этого инстанса и подменяет локальный файл. Конфиг и instance_id сохраняются. Если инстанс был запущен, его нужно перезапустить, чтобы подхватить новый бинарник.

bash

ush update shell-eedb1b0f

remove

Останавливает инстанс (если running) и удаляет его из реестра вместе с локальными файлами инстанса. Плагин в кэше может остаться — его можно снова использовать через ush start <plugin>.

bash

ush remove shell-eedb1b0f

platform

Установка и управление Docker-стеком на сервере. Общие флаги всех подкоманд:

Флаг	Env	По умолчанию
`--dir`	`INSTALL_DIR`	`/opt/unishift`
`--base-url`	`BASE_URL`	`https://storage.unishift.ru/services/prod`

Флаг, заданный явно, важнее переменной окружения.

platform install

Скачивает compose и конфиги, один раз генерирует .env с секретами, накатывает миграции и поднимает стек. Повторный запуск секреты не переписывает.

bash

ush platform install
ush platform install --public-host 203.0.113.10
ush platform install --public-host app.example.com --public-scheme https
ush platform install --dir /srv/unishift --tag 0.0.3

Флаг	Env	По умолчанию
`--public-host`	`PUBLIC_HOST`	`localhost`
`--public-scheme`	`PUBLIC_SCHEME`	`http`
`--registry`	`REGISTRY`	`leggnom`
`--tag`	`TAG`	`latest`
`--client-port`	`CLIENT_PORT`	`18080` (хост-порт SPA `unishift_client_web`; не путать с именем образа)
`--centrifugo-port`	`CENTRIFUGO_PORT`	`18100`
`--web-base-url`	`WEB_BASE_URL`	из host/scheme
`--centrifugo-ws-url`	`CENTRIFUGO_WS_URL`	из host/scheme
`--centrifugo-allowed-origins`	`CENTRIFUGO_ALLOWED_ORIGINS`	из host/scheme

http → http://HOST:18080 и ws://HOST:18100/…. https → https://HOST и wss://HOST/… (ожидается reverse proxy на 443).

Выбор состава стека (--type, иначе интерактивный опрос в TTY):

bash

ush platform install --type all                    # всё из services.yaml
ush platform install --type core                   # минимальное ядро
ush platform install --type direction --directions business,automate
ush platform install --type services --services task-tracker,documents

Флаг	Env	Значения
`--type`	`INSTALL_TYPE`	`all` \| `direction` \| `services` \| `core`
`--directions`	`INSTALL_DIRECTIONS`	направления через запятую
`--services`	`INSTALL_SERVICES`	сервисы через запятую
`--non-interactive`	—	не спрашивать, а падать без `--type`

Ядро (core: postgres, nats, minio, centrifugo, gateway, auth, spaces, client) ставится всегда; зависимости выбранных сервисов резолвятся по services.yaml. Состав сохраняется в .ush-state.json — с ним работают upgrade, services и enable / disable.

platform update

Подтягивает актуальные файлы со storage, при --public-host переписывает только публичные URL в .env (секреты не трогает), гоняет миграции и docker compose up -d.

bash

ush platform update
ush platform update --public-host 203.0.113.10
ush platform update --public-host app.example.com --public-scheme https

Флаги те же, что у install. Без --public-host / PUBLIC_HOST URL в .env не меняются.

platform migrate

Поднимает postgres и minio, создаёт недостающие БД и бакет, по очереди прогоняет *-migrate через docker compose run --rm.

Список сервисов с миграциями (должен совпадать с devops/*/migrate.sh): auth, spaces, documents, command-manager, scheduler, storage, env-manager, flow-manager, spark-grid, ai-router, task-tracker, notifications, mcp-gateway, data-tables, messaging, collatio, concierge, guard.

bash

ush platform migrate
ush platform migrate --dir /opt/unishift

ush platform install / update вызывают migrate автоматически. Если сервис в restart loop с database "…_db" does not exist — на старом томе Postgres init-скрипты не перезапускаются; повторный ush platform migrate создаст БД через ensureDatabase и накатит схему.

platform ps / logs / up / down

Обёртки над docker compose в каталоге установки.

bash

ush platform ps
ush platform logs -f
ush platform logs --tail 80 postgres
ush platform up
ush platform down              # тома сохраняются
ush platform down --volumes    # СНОСИТ данные

Флаг	Команда	Описание
`-f`, `--follow`	`logs`	Следить за выводом
`-n`, `--tail`	`logs`	Сколько последних строк
`--since`	`logs`	Логи с момента (`42m`, RFC3339)
`-v`, `--volumes`	`down`	Удалить named volumes

platform upgrade

Обновляет образы только для установленного набора сервисов (из .ush-state.json) и пересоздаёт контейнеры, у которых образ реально поменялся. Безопаснее update, когда нужен только апдейт кода без правки файлов стека.

Не тянет сторонние образы (minio, postgres, nats, centrifugo, searxng): MinIO грузится из storage.unishift.ru/deps/minio.tgz апгрейд unishift_*. compose up идёт с --remove-orphans (после переименования вроде concierge-web → concierge_web старый контейнер убирается). Алиас имён: concierge-web → concierge_web.

bash

ush platform upgrade --check          # только отчёт, ничего не трогает
ush platform upgrade --yes            # без подтверждения
ush platform upgrade --services auth,gateway   # подмножество установленного
ush platform upgrade --rollback       # вернуть TAG до последнего upgrade

Флаг	Описание
`--check`	Показать доступные обновления и выйти
`--yes`	Не спрашивать подтверждение
`--services x,y`	Ограничить подмножеством установленных сервисов
`--rollback`	Откатить `TAG` к значению до последнего upgrade

platform services

Таблица состояния по каждому сервису: направление из каталога, статус контейнера и образ — объединение .ush-state.json и docker compose ps.

bash

ush platform services

platform collect

Собирает всё нужное для расследования инцидента в один архив tar.gz: логи всех установленных сервисов, диагностику Docker и хоста, обеззараженные конфиги и логи раннеров. Сбой одного источника (например, контейнер не создан) не роняет сбор — он фиксируется в manifest.json внутри архива.

bash

ush platform collect                       # все сервисы, логи за 24 часа
ush platform collect --since 72h           # глубже
ush platform collect --since all           # всё, что ещё хранит docker
ush platform collect gateway auth          # подмножество сервисов
ush platform collect --tail 5000           # ограничение по строкам вместо окна
ush platform collect --out /tmp/bundle.tar.gz --no-redact

Флаг	Описание
`--since`	Окно логов (docker duration или RFC3339), по умолчанию `24h`; `all` — без ограничения
`-n`, `--tail`	Собрать N последних строк на сервис вместо окна
`--out`	Путь архива (по умолчанию `unishift-logs-<дата-время>.tar.gz` в текущем каталоге)
`--no-redact`	Не вычищать значения секретов из архива

Состав архива: logs/<сервис>.log; manifest.json (время, каталог установки, TAG/REGISTRY, список сервисов, статус каждого источника); config/ — .env с маскированными секретами, .ush-state.json, services.yaml, docker-compose.yaml; docker/ — compose ps, inspect контейнеров (рестарты, OOM, exit code), версия и system df; host/ — uname, df, uptime; runners/ — хвосты логов экземпляров раннеров из ~/.ush/runners.

Значения секретов из .env (ключи с TOKEN, SECRET, PASSWORD, _KEY) вычищаются из всех файлов архива по умолчанию, поэтому архив можно прикладывать к тикету или передавать в поддержку.

platform enable / disable

Включение и выключение отдельных сервисов поверх установленного набора.

bash

ush platform enable data-tables      # + зависимости, затем compose up -d
ush platform enable concierge
ush platform disable spark-grid      # стоп и удаление из install state

enable резолвит зависимости сервиса по services.yaml, добавляет его в .ush-state.json и стартует недостающие контейнеры.
disable нельзя применить к сервисам ядра (core) и к тем, от кого зависят другие включённые сервисы.

Локальный planner — провайдер Ollama в AI Router, не сервис ush platform.

platform config

Просмотр и правка <dir>/.env без ручного редактирования. Секреты маскируются, пока не передан --reveal.

bash

ush platform config show             # все KEY=value (секреты скрыты)
ush platform config show --reveal    # с настоящими значениями
ush platform config get TAG
ush platform config set TAG=0.0.4 REGISTRY=leggnom
ush platform config diff             # расхождение ключей с каноническим набором

set принимает несколько пар key=value за раз и сначала копирует.env в .env.bak.
diff показывает, каких ключей из дефолтного набора нет в .env и какие ключи там лишние.
После set изменения применяются ush platform upgrade (или update).

Плагины

Раннеры скачиваются с https://storage.unishift.ru/runners/{os}/{plugin}.

Плагин	Назначение
`shell`	Shell-команды на хосте
`code`	Код в изолированном контейнере
`docker`	Задачи в Docker
`sql`	SQL-запросы
`ollama`	LLM через Ollama
`docx-generator` / `pdf-generator` / `xlsx-generator`	Генерация документов

Данные на диске

Состояние раннеров — в ~/.ush/:

Путь	Содержимое
`~/.ush/registry.json`	Реестр инстансов
`~/.ush/runners/<plugin>/<id>/`	Бинарник, `config.json`, логи
`~/.ush/tmp/`	Временные загрузки

Состояние платформы — в --dir (по умолчанию /opt/unishift):

Путь	Содержимое
`docker-compose.yaml`	Описание стека
`.env`	Конфиг и секреты (`chmod 600`)
`.ush-state.json`	Установленный набор сервисов
`services.yaml`	Каталог сервисов и направлений
`postgres/`, `centrifugo/`, `searxng/`	Монтируемые конфиги

CLI ​

Быстрая установка ​

Подключить компьютер как терминал ​

Параметры установки ​

Ручная установка ​

Обновление CLI ​

URL платформы (важно) ​

Быстрый старт ​

Команды ​

Платформа ​

Терминал ​

Раннеры ​

connect ​

connects ​

install ​

start ​

stop ​

restart ​

status ​

logs ​

config ​

update ​

remove ​

platform ​

platform install ​

platform update ​

platform migrate ​

platform ps / logs / up / down ​

platform upgrade ​

platform services ​

platform collect ​

platform enable / disable ​

platform config ​

Плагины ​

Данные на диске ​

CLI

Быстрая установка

Подключить компьютер как терминал

Параметры установки

Ручная установка

Обновление CLI

URL платформы (важно)

Быстрый старт

Команды

Платформа

Терминал

Раннеры

connect

connects

install

start

stop

restart

status

logs

config

update

remove

platform

platform install

platform update

platform migrate

platform ps / logs / up / down

platform upgrade

platform services

platform collect

platform enable / disable

platform config

Плагины

Данные на диске