HSM CLI Reference

Полное руководство по командам интерфейса командной строки Hyper Stack Manager (hsm).

Принципы дизайна

HSM CLI следует современным практикам проектирования (2026):

1. Noun-Verb иерархия: Команды сгруппированы вокруг объектов (library, service, group, registry). Это обеспечивает предсказуемость и удобное автодополнение. Подробнее о принципе: Command Line Interface Guidelines.
2. Interactive + Flags: Мы поддерживаем два равноправных способа взаимодействия:
   • Интерактивный (Wizard): Для разработчиков людей. Если запустить команду без аргументов, HSM проведет вас через пошаговый мастер.
   • Флаги (Automation): Для систем автоматизации, CI и LLM-ассистентов. Все параметры можно передать через флаги, что идеально для CI/CD пайплайнов и работе в партнерстве с LLM-агентами.
3. Симметрия с сокращениями: Интерфейсы управления Проектом (hsm ...) и Реестром (hsm registry ...) зеркальны. Однако, так как с проектом мы работаем 90% времени, префикс project опускается (аналогично тому, как uv sync работает с текущим проектом).

Помощь и документация

Любая команда или подкоманда поддерживает флаг --help, который выводит подробное описание доступных аргументов и опций.

Пример:

hsm --help
hsm registry library add --help

Автодополнение (Shell Completion)

HSM поддерживает автодополнение команд для Bash, Zsh и Fish.

• --install-completion: Установить скрипт автодополнения для текущей оболочки.
• --show-completion: Вывести скрипт автодополнения в терминал (для ручной настройки).

---

1. Управление Проектом (Project Management)

Команды для работы с текущим проектом и файлом hsm.yaml. Используются сокращенные алиасы для частого доступа.

Общие команды

hsm init

Инициализирует новый HSM-проект в текущей директории.

• Аргументы:
  • --name, -n (Optional): Имя проекта.

hsm sync

Синхронизирует состояние проекта с манифестом hsm.yaml. Аналог uv sync, но для всего стека (Python + Docker + VES).

• Аргументы:
  • --frozen (Optional): Использовать lock-файлы без обновления зависимостей.
  • --verify / --no-verify (Optional): Верифицировать окружение после синхронизации (по умолчанию включено).

hsm list

Отображает текущий состав стека проекта (дерево зависимостей).

hsm check

Выполняет полную валидацию текущего проекта и реестра без внесения изменений. Это "сухой прогон" (dry-run) перед синхронизацией.

• Критерии проверки:
  • Наличие и синтаксис hsm.yaml.
  • Наличие всех компонентов в реестре.
  • Отсутствие конфликтов в группах и implies.

hsm mode

Глобальное переключение режима для всех компонентов в проекте.

• Аргументы:
  • MODE (Required): Режим (dev или prod).
• Пример: hsm mode dev (переводит все компоненты на локальные исходники).
• Зачем это нужно: Позволяет одной командой перевести весь проект в режим разработки (для старта спринта) или в режим продакшена (для проверки сборки), предотвращая "дрейф конфигурации".

hsm python-manager set

Выбирает менеджер пакетов для Python.

• Аргументы:
  • MANAGER (Required): Имя менеджера (сейчас поддерживается только uv, в будущем планируется pixi, pip).

hsm container-manager set (Future)

Выбирает рантайм для контейнеров (например, docker или podman).

Управление Сервисами (hsm service ...)

hsm service add

Добавляет сервис в hsm.yaml.

• Аргументы:
  • NAME (Required): Имя сервиса.
  • --group, -g (Optional): Добавить как опцию в существующую группу сервисов.

hsm service remove

Удаляет сервис из hsm.yaml.

• Аргументы:
  • NAME (Required): Имя сервиса.
  • --group, -g (Optional): Удалить из конкретной группы.

hsm service mode

Атомарное переключение режима для конкретного сервиса.

• Аргументы:
  • NAME (Required): Имя сервиса.
  • MODE (Required): Режим (dev или prod).

hsm service init

Инициализирует новый сервис в директории проекта.

• Аргументы:
  • NAME (Required): Имя сервиса.
  • --runtime, -r (Optional): Рантайм сервиса (uv, docker, podman). По умолчанию uv.
  • --path, -p (Optional): Путь к сервису (по умолчанию ./services/<name>).
  • --register / --no-register (Optional): Автоматически добавить в реестр (по умолчанию включено).

Управление Библиотеками (hsm library ...)

hsm library add

Добавляет библиотеку в hsm.yaml.

• Аргументы:
  • NAME (Required): Имя библиотеки.
  • --group, -g (Optional): Добавить как опцию в существующую группу.

hsm library remove

Удаляет библиотеку из hsm.yaml.

• Аргументы:
  • NAME (Required): Имя библиотеки.
  • --group, -g (Optional): Удалить из конкретной группы.

hsm library init

Инициализирует новую Python-библиотеку в директории проекта и автоматически регистрирует ее в локальном реестре.

• Аргументы:
  • NAME (Required): Имя библиотеки.
  • --path, -p (Optional): Путь к библиотеке (по умолчанию ./packages/<name>).
  • --register / --no-register (Optional): Автоматически добавить в реестр (по умолчанию включено).

hsm library mode

Атомарное переключение режима для конкретной библиотеки.

• Аргументы:
  • NAME (Required): Имя библиотеки.
  • MODE (Required): Режим (dev или prod).
• Зачем это нужно: Можно собрать окружение из любых компонентов как dev так и prod еализации.

Это дает точечный контроль для отладки конкретных компонентов в системе, не затрагивая стабильность остальных компонентов.

Напрмер, когда нужно сделать фикс в коде затрагивающим сразу 3 компонента системы, а остальные оставить в режиме prod.

Управление Группами (hsm group ...)

hsm group add

Добавляет новую группу в hsm.yaml.

• Аргументы:
  • NAME (Required): Имя группы.
  • --option, -o (Required): Имя пакета-опции.

hsm group remove

Удаляет группу целиком из hsm.yaml.

• Аргументы:
  • NAME (Required): Имя группы.

hsm group add-option

Добавляет или устанавливает вариант выбора (опцию) в существующую группу в манифесте.

• Аргументы:
  • GROUP (Required): Имя группы.
  • OPTION (Required): Имя компонента-опции.
• Поведение:
  • Для стратегии 1-of-N: Заменяет текущий выбор на указанную опцию (например, смена qdrant на milvus).
  • Для стратегии M-of-N: Добавляет опцию к списку выбранных.
  • Implies (Автоматические зависимости): Если выбранная опция имеет поле implies в реестре (например, клиент БД требует сервис БД), HSM автоматически добавит или предложит добавить соответствующие зависимости в другие группы.

hsm group remove-option

Удаляет вариант выбора из группы в манифесте.

• Аргументы:
  • GROUP (Required): Имя группы.
  • OPTION (Required): Имя компонента-опции.

---

2. Управление Реестром (hsm registry ...)

Команды для управления глобальным реестром компонентов (hsm-registry/).

Поиск и Просмотр

hsm registry search

Поиск компонентов в реестре.

• Аргументы: QUERY (Required).

hsm registry list

Выводит список всех доступных компонентов.

hsm registry show

Показывает детальную информацию о компоненте.

• Аргументы: NAME (Required).

hsm registry path set

Устанавливает путь к директории реестра (по умолчанию ./hsm-registry).

• Аргументы: PATH (Required).

Управление Библиотеками (hsm registry library ...)

hsm registry library add

Добавляет новую библиотеку в реестр.

• Аргументы: NAME (Optional), --version, --description, --prod-type, --prod-url, --dev-path.
• Интерактивность: Если аргументы не указаны, запускается мастер.

hsm registry library remove

Удаляет библиотеку из реестра.

• Аргументы:
  • NAME (Required): Имя библиотеки.
  • --yes, -y (Optional): Подтвердить удаление без запроса (для скриптов).

Управление Группами (hsm registry group ...)

hsm registry group add

Создает новую группу в реестре.

• Аргументы: NAME, --type, --strategy, --option (multiple), --description.
• Implies: Для настройки зависимостей (implies) между опциями используйте редактирование YAML файла группы после создания, так как это сложная структура для CLI аргументов.

hsm registry group remove

Удаляет группу из реестра.

• Аргументы: NAME, --yes, -y.
• Безопасность: Сборка реестра — трудоемкий процесс, поэтому удаление требует подтверждения.
  • Интерактивный режим: Запрашивает подтверждение у пользователя ("Are you sure? [y/N]").
  • Автоматизация: Флаг --yes позволяет LLM-агентам и CI-скриптам выполнять удаление без зависания на ожидании ввода.

hsm registry group add-option

Добавляет новую доступную опцию в определение группы в реестре.

• Аргументы:
  • GROUP (Required): Имя группы.
  • OPTION (Required): Имя библиотеки.

hsm registry group remove-option

Удаляет доступную опцию из определения группы в реестре.

• Аргументы:
  • GROUP (Required): Имя группы.
  • OPTION (Required): Имя библиотеки.

Управление Сервисами (hsm registry service ...)

hsm registry service add

Добавляет описание сервиса в реестр.

Общие аргументы:

• NAME (Required): Имя сервиса (например, qdrant).
• --runtime, -rt (Optional): Рантайм сервиса (docker, uv, podman). По умолчанию docker.
• --dependency, -dep (Optional, Multiple): Зависимости сервиса (другие библиотеки или сервисы).
• --container-name (Optional): Явное имя контейнера (например, qdrant-instance).
• --network-alias (Optional, Multiple): Сетевые алиасы (например, vector-db).
• --description, -d (Optional): Описание сервиса.
• --env, -e (Optional, Multiple): Общие переменные окружения (например, TZ=UTC).
• --no-input (Optional): Отключить интерактивный режим.

Production (Stable) аргументы:

• --image (Optional): Docker image для Prod-режима (например, qdrant/qdrant:latest).
• --prod-container-name (Optional): Имя контейнера только для Prod.
• --prod-network-alias (Optional, Multiple): Алиасы только для Prod.
• --prod-port (Optional, Multiple): Порты только для Prod (например, 80:80).
• --prod-volume (Optional, Multiple): Тома только для Prod (например, qdrant_data:/data).
• --prod-env (Optional, Multiple): Env только для Prod.

Development (Local) аргументы:

• --build-path (Optional): Путь к контексту сборки для Dev-режима (например, ./docker/qdrant).
• --dockerfile (Optional): Имя Dockerfile, если отличается от стандартного (по умолчанию Dockerfile).
• --dev-image (Optional): Docker image для Dev-режима (если не используется сборка).
• --dev-container-name (Optional): Имя контейнера только для Dev.
• --dev-network-alias (Optional, Multiple): Алиасы только для Dev.
• --dev-port (Optional, Multiple): Порты для Dev (например, 6333:6333 для отладки).
• --dev-volume (Optional, Multiple): Тома для Dev (например, ./data:/data для hot-reload).
• --dev-env (Optional, Multiple): Env для Dev.

hsm registry service remove

Удаляет сервис из реестра.

• Аргументы:
  • NAME (Required): Имя сервиса.
  • --yes, -y (Optional): Подтвердить удаление без запроса.

---

Сводная таблица симметрии

Действие	Проект (hsm ...)	Реестр (hsm registry ...)
Добавить библиотеку	library add	library add
Удалить библиотеку	library remove	library remove
Добавить группу	group add	group add
Удалить группу	group remove	group remove
Добавить опцию	group add-option	group add-option
Удалить опцию	group remove-option	group remove-option
Режим	mode, library mode, service mode	—
Добавить сервис	service add	service add
Удалить сервис	service remove	service remove