Утилита командной строки cmp
Где найти в портале: команды установки находятся в справочнике API (
https://<your-domain>/apidoc, раздел Command-line interface). Подтверждение входа:https://<your-domain>/link. Подключенные устройства: API keys (/api-keys) › Connected apps & devices.
Назначение
cmp — это компактная утилита командной строки для ваших клиентов (и для вас), которая превращает каждую операцию API в отдельную команду: cmp vm list, cmp vm start <id>, cmp billing invoice list. Она собирается на основе документа OpenAPI вашей установки во время релиза, поэтому набор команд в точности соответствует включенным функциям. Это единый статический бинарный файл для Linux, macOS и Windows (amd64 и arm64), не требующий установки дополнительных компонентов.
Требования
| Параметр | Требование |
|---|---|
| Сервер | Ничего дополнительно. Пакеты релиза включены в состав NexCMP и раздаются панелью по адресу https://<your-domain>/cli/. |
| Компьютер клиента | Linux, macOS или Windows (PowerShell 5.1+). ssh-keygen (OpenSSH 8.0+) требуется только для проверки подписи. |
| Учетные данные | Вход через браузер с одноразовым кодом или API key. |
| Сеть | HTTPS-подключение к вашей панели. CLI отклоняет отправку ключа по обычному http://, за исключением localhost. |
Подготовка инфраструктуры
Ничего. Панель отдает эти файлы из /cli/ (сборка или загрузка не требуются):
| Файл | Назначение |
|---|---|
install.sh, install.ps1 | Инсталляторы для Linux/macOS и Windows; они содержат адрес вашей панели. |
latest.json | Текущая версия, список файлов, размеры, sha256. |
v<version>/cmp_<version>_<os>_<arch>.tar.gz или .zip | Программы: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64. |
v<version>/SHA256SUMS, SHA256SUMS.sig | Контрольные суммы и их подпись ed25519. |
cmp-cli.pub | Открытый ключ релиза. |
Установка (клиент)
macOS и Linux:
bash
curl -fsSL https://cloud.example.com/cli/install.sh | shWindows PowerShell:
powershell
irm https://cloud.example.com/cli/install.ps1 | iexИнсталлятор выбирает пакет под нужную ОС и процессор, скачивает SHA256SUMS и его подпись, проверяет подпись встроенным в скрипт ключом, сверяет хеш пакета и устанавливает cmp в /usr/local/bin (от root) или ~/.local/bin; в Windows — в %LOCALAPPDATA%\cmp\bin (с добавлением в пользовательский PATH). При ошибке любой проверки ничего не устанавливается.
| Переменная | Значение |
|---|---|
CMP_VERSION | Установить эту версию вместо последней. |
CMP_INSTALL_DIR | Папка установки. |
CMP_REQUIRE_SIGNATURE | 1 = прерывать установку, если подпись не удается проверить. |
CMP_BASE_URL | Базовый адрес загрузки (для зеркал). |
Ручная загрузка и проверка:
bash
curl -fsSLO https://cloud.example.com/cli/latest.json
sha256sum --check --ignore-missing SHA256SUMS
Вход
bash
cmp login- CLI выводит одноразовый код и ссылку (
https://cloud.example.com/link?code=WDJB-MJHT), открывает браузер и ожидает. - Войдите в портал через браузер, проверьте имя клиента, устройство, IP-адрес и страну, отметьте нужные разрешения (scopes) и выберите срок действия ключа (по умолчанию 90 дней). Разрешения, списывающие средства или удаляющие данные, изначально отключены. Нажмите approve.
- CLI получает собственный ключ, отдельный от созданных клиентом вручную, и сохраняет его в
~/.config/cmp/config.json(права0600;%APPDATA%\cmpв Windows). Он отображается в API keys › Connected apps & devices и может быть отозван там же.
Срок действия кода — 10 минут. Для подтверждения требуется реальная активная сессия в портале с подтвержденным e-mail, а не другой ключ или сессия имперсонации.
Полезные флаги: --scopes vm:read,billing:read, --name "build server", --no-browser, --profile, --api-url.
Для CI или серверов без браузера используйте ключ из портала:
bash
printf %s "$KEY" | cmp login --with-token
export CMP_TOKEN=vk_XXXX # nothing is written to disk
cmp whoamiИспользование команд
text
cmp <group> [subgroup] <action> [<id> ...] [flags]- Параметры пути передаются позиционными аргументами; параметры запроса и поля тела преобразуются во флаги в формате kebab-case (
--start-port 443). --data '{"a":1}',--data @file.jsonили--data -отправляет тело JSON целиком; флаги переопределяют его поля.cmp help vm firewall add(или--help) отображает подробную информацию о любой команде.
bash
cmp catalog plans
cmp vm list --state active --per-page 50
cmp vm get 3f2a1c9e-0000-4000-8000-000000000000
cmp vm start 3f2a1c9e-0000-4000-8000-000000000000
cmp vm firewall add 3f2a1c9e-... --protocol tcp --start-port 22 --cidr-list 203.0.113.0/24
cmp billing wallet
cmp api GET /v1/vm --query page=2 # raw call to any endpointВстроенные команды: login, logout, whoami, config, api, completion, version, update, help. Все остальные берутся из API-документа.
Глобальные флаги:
| Флаг | Значение |
|---|---|
-o, --output json|table|yaml | Формат. По умолчанию table в терминале и json при передаче через пайп. |
--profile, --api-url | Какую сохраненную учетную запись и какой сайт использовать. |
-y, --yes | Пропускать подтверждение для деструктивных или платных команд. |
--idempotency-key <k> | Выбрать ключ для платной команды. |
--retry <n> | При HTTP 429 ждать Retry-After и повторять запрос до n раз. |
--timeout <s> | Время ожидания заголовков ответа в секундах (по умолчанию 60). |
--debug | Выводить процесс HTTP-обмена в stderr со скрытыми ключами. |
Команды, которые списывают средства с кошелька или удаляют данные, запрашивают подтверждение и при оплате отправляют автоматически сгенерированный Idempotency-Key (выводится в stderr, что позволяет безопасно повторить попытку с --idempotency-key). Без терминала они отклоняются, если не передан флаг --yes.
Коды возврата
| Код | Значение |
|---|---|
| 0 | Успешно |
| 1 | Другая ошибка (сеть, незарегистрированные коды HTTP 4xx/5xx) |
| 2 | Ошибка использования |
| 3 | Не авторизован (401/403) |
| 4 | Не найдено (404) |
| 5 | Превышен лимит запросов (429) |
| 6 | Требуется подтверждение или отклонено |
| 130 | Прервано |
Профили и переменные окружения
cmp config выводит список профилей; cmp config use <name> переключает; клиенты реселлера используют собственный домен: cmp login --api-url https://shop.example.net --profile shop. Приоритет: флаг, окружение, файл конфигурации. Переменные: CMP_TOKEN, CMP_PROFILE, CMP_API_URL, CMP_OUTPUT, CMP_CONFIG_DIR, CMP_ALLOW_HTTP, CMP_UPDATE_URL.
GitHub Actions:
yaml
- name: Install cmp
run: |
curl -fsSL https://cloud.example.com/cli/install.sh | CMP_INSTALL_DIR="$RUNNER_TEMP/bin" sh
echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
- name: List running VMs
env:
CMP_TOKEN: ${{ secrets.CMP_TOKEN }} # a read-only key
run: cmp vm list -o json | jq -r '.items[] | select(.cs_state=="Running") | .hostname'Автодополнение для оболочки: cmp completion bash|zsh|fish|powershell.
Обновление и удаление
bash
cmp version
cmp update --check
cmp updatecmp update загружает latest.json, SHA256SUMS и подпись, проверяет подпись с помощью открытого ключа, встроенного в текущий бинарный файл, проверяет хеш пакета и только затем обновляет исполняемый файл. Для отката версии требуется --force. При обновлении NexCMP панель раздает релиз CLI, поставляемый с новой версией.
Для удаления удалите исполняемый файл cmp и каталог конфигурации (его путь показывает cmp config path). При утере устройства отзовите ключ в разделе API keys.
Проверка
cmp versionвыводит версию и версию документа API.cmp login, подтвердите в браузере, затемcmp whoamiпокажет профиль и URL вашей панели.cmp vm listвозвращает список ваших VM;cmp vm list -o json | jq .выводит исходный JSON.
Ограничения и примечания
- Список команд зависит от вашей сборки: пакеты генерируются на основе документа OpenAPI вашей системы при сборке релиза, поэтому для продуктов, отключенных в вашем релизе, команд не будет. Для неизвестных CLI путей используйте
cmp api. - CLI распространяется по лицензии MIT.
- Каждый пакет подписан ключом ed25519; ключ верификации зашит в установщик и бинарный файл, а не загружается при обновлении.
- Ключи ограничены по лимитам запросов на ключ и на аккаунт (см. REST API).
Устранение неполадок
| Симптом | Причина | Решение |
|---|---|---|
curl .../cli/install.sh возвращает 404 | В релизе на сервере отсутствует папка CLI или хост не включен в лицензию | Проверьте https://<domain>/cli/latest.json и домен; обновите NexCMP. |
| "не удалось проверить подпись" | ssh-keygen отсутствует или устарел | Установите OpenSSH 8.0+ или задайте CMP_REQUIRE_SIGNATURE=0, только если принимаете риски. |
cmp login сообщает, что срок действия кода истек | Прошло 10 минут | Выполните cmp login повторно. |
| Код возврата 3 | У ключа отсутствуют права (scope), он истек или отозван | cmp whoami; создайте или подтвердите заново с расширенными правами. |
| Код возврата 6 в скрипте | Платная или деструктивная команда запущена без терминала | Добавьте --yes (и собственный --idempotency-key). |
| "отказывается передавать ключ по http" | URL API использует обычный http | Используйте https://, или CMP_ALLOW_HTTP=1 только для тестовой среды. |
| Браузер открывает не тот сайт | Для реселлера не задан --api-url | cmp login --api-url https://<reseller-domain>. |