--- title: Утилита командной строки cmp description: Установка и использование CLI cmp из вашей панели: вход по коду через браузер, команды из API, коды возврата, работа в CI и подписанные обновления. url: https://nexcmp.com/ru/docs/developers/cmp-cli/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Утилита командной строки `cmp` {#cmp-command-line-tool} > **Где найти в портале:** команды установки находятся в справочнике API (`https:///apidoc`, раздел Command-line interface). Подтверждение входа: `https:///link`. Подключенные устройства: API keys (`/api-keys`) › Connected apps & devices. ## Назначение {#what-it-does} `cmp` — это компактная утилита командной строки для ваших клиентов (и для вас), которая превращает **каждую операцию API в отдельную команду**: `cmp vm list`, `cmp vm start `, `cmp billing invoice list`. Она собирается на основе документа OpenAPI **вашей** установки во время релиза, поэтому набор команд в точности соответствует включенным функциям. Это единый статический бинарный файл для Linux, macOS и Windows (amd64 и arm64), не требующий установки дополнительных компонентов. ## Требования {#requirements} | Параметр | Требование | |---|---| | Сервер | Ничего дополнительно. Пакеты релиза включены в состав NexCMP и раздаются панелью по адресу `https:///cli/`. | | Компьютер клиента | Linux, macOS или Windows (PowerShell 5.1+). `ssh-keygen` (OpenSSH 8.0+) требуется только для проверки подписи. | | Учетные данные | Вход через браузер с одноразовым кодом или [API key](https://nexcmp.com/ru/docs/developers/api-keys/). | | Сеть | HTTPS-подключение к вашей панели. CLI отклоняет отправку ключа по обычному `http://`, за исключением `localhost`. | ## Подготовка инфраструктуры {#prepare-the-infrastructure} Ничего. Панель отдает эти файлы из `/cli/` (сборка или загрузка не требуются): | Файл | Назначение | |---|---| | `install.sh`, `install.ps1` | Инсталляторы для Linux/macOS и Windows; они содержат адрес вашей панели. | | `latest.json` | Текущая версия, список файлов, размеры, sha256. | | `v/cmp___.tar.gz` или `.zip` | Программы: linux amd64/arm64, darwin amd64/arm64/universal, windows amd64/arm64. | | `v/SHA256SUMS`, `SHA256SUMS.sig` | Контрольные суммы и их подпись ed25519. | | `cmp-cli.pub` | Открытый ключ релиза. | ## Установка (клиент) {#install-customer} macOS и Linux: ```bash curl -fsSL https://cloud.example.com/cli/install.sh | sh ``` Windows 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 ``` ![Раздел API-справочника с командой cmp install для macOS и Linux](https://nexcmp.com/ru/docs/images/developers/cmp-cli-01-install.webp) ## Вход {#log-in} ```bash cmp login ``` 1. CLI выводит одноразовый **код** и ссылку (`https://cloud.example.com/link?code=WDJB-MJHT`), открывает браузер и ожидает. 2. Войдите в портал через браузер, проверьте имя клиента, устройство, IP-адрес и страну, отметьте нужные разрешения (scopes) и выберите срок действия ключа (по умолчанию 90 дней). Разрешения, списывающие средства или удаляющие данные, изначально отключены. Нажмите approve. 3. 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 ``` ## Использование команд {#using-commands} ```text cmp [subgroup] [ ...] [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 ` | Выбрать ключ для платной команды. | | `--retry ` | При HTTP 429 ждать `Retry-After` и повторять запрос до n раз. | | `--timeout ` | Время ожидания заголовков ответа в секундах (по умолчанию 60). | | `--debug` | Выводить процесс HTTP-обмена в stderr со скрытыми ключами. | Команды, которые **списывают средства с кошелька или удаляют данные**, запрашивают подтверждение и при оплате отправляют автоматически сгенерированный `Idempotency-Key` (выводится в stderr, что позволяет безопасно повторить попытку с `--idempotency-key`). Без терминала они отклоняются, если не передан флаг `--yes`. ### Коды возврата {#exit-codes} | Код | Значение | |---|---| | 0 | Успешно | | 1 | Другая ошибка (сеть, незарегистрированные коды HTTP 4xx/5xx) | | 2 | Ошибка использования | | 3 | Не авторизован (401/403) | | 4 | Не найдено (404) | | 5 | Превышен лимит запросов (429) | | 6 | Требуется подтверждение или отклонено | | 130 | Прервано | ### Профили и переменные окружения {#profiles-and-environment} `cmp config` выводит список профилей; `cmp config use ` переключает; клиенты реселлера используют собственный домен: `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`. ## Обновление и удаление {#update-and-uninstall} ```bash cmp version cmp update --check cmp update ``` `cmp update` загружает `latest.json`, `SHA256SUMS` и подпись, проверяет подпись с помощью открытого ключа, **встроенного в текущий бинарный файл**, проверяет хеш пакета и только затем обновляет исполняемый файл. Для отката версии требуется `--force`. При обновлении NexCMP панель раздает релиз CLI, поставляемый с новой версией. Для удаления удалите исполняемый файл `cmp` и каталог конфигурации (его путь показывает `cmp config path`). При утере устройства отзовите ключ в разделе **API keys**. ## Проверка {#verify} 1. `cmp version` выводит версию и версию документа API. 2. `cmp login`, подтвердите в браузере, затем `cmp whoami` покажет профиль и URL вашей панели. 3. `cmp vm list` возвращает список ваших VM; `cmp vm list -o json | jq .` выводит исходный JSON. ## Ограничения и примечания {#limits-notes} - Список команд зависит от вашей сборки: пакеты генерируются на основе документа OpenAPI вашей системы при сборке релиза, поэтому для продуктов, отключенных в вашем релизе, команд не будет. Для неизвестных CLI путей используйте `cmp api`. - CLI распространяется по лицензии MIT. - Каждый пакет подписан ключом ed25519; ключ верификации зашит в установщик и бинарный файл, а не загружается при обновлении. - Ключи ограничены по лимитам запросов на ключ и на аккаунт (см. [REST API](https://nexcmp.com/ru/docs/developers/api/#rate-limits)). ## Устранение неполадок {#troubleshooting} | Симптом | Причина | Решение | |---|---|---| | `curl .../cli/install.sh` возвращает 404 | В релизе на сервере отсутствует папка CLI или хост не включен в лицензию | Проверьте `https:///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://`. |