homeconsole-cli 0.0.3

HomeConsole CLI (hc) — управление платформой через HTTP API

HomeConsole CLI (hc)

CLI-утилита для управления платформой HomeConsole исключительно через HTTP API CoreRuntime.

Установка

Рекомендуется — pipx (Debian / Ubuntu / Raspbian / OrangePi OS)

pipx создаёт изолированный venv автоматически и регистрирует hc глобально:

apt install pipx          # или: pip install pipx --user
pipx ensurepath           # добавляет ~/.local/bin в PATH (один раз)
pipx install homeconsole-cli

После pipx ensurepath перезапусти шелл или выполни source ~/.bashrc.

Обновление:

pipx upgrade homeconsole-cli

Альтернатива — pip --user

pip install --user homeconsole-cli

Убедись, что ~/.local/bin в PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

Локальная разработка (из исходников)

cd home-console-cli
python -m venv .venv
source .venv/bin/activate
pip install -e .

Проверка:

hc --help
hc nav

Конфигурация

Файл: ~/.config/hc/config.toml

[core]
host = "localhost"
port = 8080
token = "jwt-token-here"
verify_ssl = true

[display]
color = true
emoji = true

Токен берётся по приоритету:

• --token (если у команды есть такой флаг)
• переменная окружения HC_TOKEN
• config.toml

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

Подключиться и сохранить конфиг:

hc connect localhost --port 8080

Статус:

hc status

Список плагинов:

hc plugin list

Команды

• hc connect <host> [--port 8080] [--token TOKEN]
• hc status
• hc install <name> [--version X.Y.Z]
• hc remove <name> [--force]
• hc plugin list|start|stop|info
• hc module list|status
• hc logs [--follow] [--module <name>] [--level debug|info|warning|error]
• hc search <query>
• hc setup
• hc deploy (по умолчанию: build+push+rollout+wait) и hc deploy ... (тонкие подкоманды)
• hc deploy platform (локальный dev flow)
• hc deploy platform --mode image --image ghcr.io/home-console/platform-home-console --tag latest (image-only deploy)
• hc deploy stack dev / hc deploy stack prod (полный stack для dev/prod)
• hc update core ... (обновление core-runtime до нового image:tag)
• hc shell
• hc nav [section ...] (удобная навигация по командам: hc nav deploy, hc nav deploy dev)

Навигация по командам (без запоминания)

hc nav
hc nav deploy
hc nav deploy dev

Подсказка: на любом уровне можно проваливаться дальше и смотреть доступные разделы.

Быстрый dev up по профилям

hc deploy dev up --profile base
hc deploy dev up --profile platform
hc deploy dev up --profile cache
hc deploy dev up --profile db

Профили:

• base = core+proxy
• platform = core+proxy+platform
• cache = core+proxy+platform+cache
• db = core+proxy+platform+cache+db

Deploy “одной командой”

По умолчанию hc deploy делает полный жизненный цикл:

• build: docker build -t <image>:<tag>
• push: docker push <image>:<tag>
• rollout: docker compose pull core-runtime && docker compose up -d
• wait: ждёт healthy (проверка curl внутри контейнера)

Полезные флаги:

• --no-build, --no-push, --no-rollout
• --wait/--no-wait (по умолчанию --wait)
• --timeout 180 (сек), --interval 1.0 (сек)
• --health-url http://localhost:8000/api/v1/monitor/health (внутри контейнера)
• --quiet (минимальный вывод)
• --json (машинный вывод; удобно для CI/скриптов)

Логи core-runtime (для диагностики таймаута):

• hc deploy core logs -f

Deploy платформы

Локальный dev flow:

hc deploy platform

Только подготовить статику, без запуска стека:

hc deploy platform --no-start

Image-only deploy через GHCR:

hc deploy platform --mode image --image ghcr.io/home-console/platform-home-console --tag latest

Этот вариант использует platform-home-console/docker-compose.image.yml и PLATFORM_IMAGE.

Если “нет команды hc deploy”

Почти всегда это означает, что в окружении стоит не тот пакет, который предоставляет команду hc.

Проверка (в активированном venv):

python -c "import hc, inspect; print(hc.__file__)"

Должно указывать на .../home-console-cli/hc/__init__.py (или site-packages homeconsole-cli).

Ошибки и UX

• Traceback пользователю не показывается.
• Все ошибки печатаются через Rich: [red]Ошибка: ...[/red].
• При ошибке утилита завершает выполнение с кодом 1.