--- title: CLI Pingvera — мониторинг из терминала и скриптов description: pingvera monitors create в онбординг-скрипте, мониторинг в CI, бэкап конфигурации мониторинга в Terraform одной командой. Разбираем CLI-бинарь Pingvera — установка, токен, команды, коды выхода. source: https://pingvera.ru/blog/cli-pingvera-monitoring-iz-terminala.html --- # CLI Pingvera: мониторинг из терминала и скриптов Дашборд удобен, когда мониторинг настраивает один человек мышкой. Но когда сайтов десятки, а заводить проверки нужно на каждом онбординге нового клиента, кликать по формам — это разговор не про удобство, а про потерянное время и человеческую ошибку в четвёртом мониторе за день. Поэтому у Pingvera есть CLI: тот же [write-API](https://pingvera.ru/blog/api-upravleniya-monitoringom.html), что использует дашборд, но в терминале, скрипте или CI. CLI — не отдельный продукт, а тонкая обёртка. Всё, что он делает, дашборд тоже умеет через тот же API (см. `docs/api.md`). Разница только в том, кто нажимает кнопки: человек или скрипт. ## Установка — одна строка Хаб раздаёт готовые бинарники по `/dl` — тем же механизмом, что агент и пробер. Собраны linux amd64/arm64, macOS (Intel и Apple Silicon) и Windows: `# Linux amd64 curl -fsSL https://app.pingvera.ru/dl/pingvera-cli-linux-amd64 -o pingvera && chmod +x pingvera sudo mv pingvera /usr/local/bin/` Рядом с каждым бинарником лежит `.sha256` — при желании сверяете хэш перед тем, как класть файл в `$PATH`. Зависимостей нет: CLI собран на стандартной библиотеке Go, это один статический файл. Кто предпочитает собрать сам — `go build -o pingvera ./cmd/cli` из исходников репозитория, результат тот же бинарь. ## Подключение: адрес и токен Два параметра, оба можно задать флагом или переменной окружения (флаг сильнее): Токен создаётся в дашборде: **Настройки → API-токены**, со скоупом под задачу (`read:monitoring`, `write:monitors`, `write:status-pages`, `write:channels` — подробнее в `docs/api.md`). В CI токен кладётся в секреты пайплайна и пробрасывается переменной — в шаге ничего, кроме команды, не появляется: `export PINGVERA_TOKEN=pv_... pingvera monitors list` Вывод по умолчанию — читаемый JSON ответа сервера. Для `list`-команд есть флаг `-o table` — печатает таблицей, удобно смотреть глазами в терминале, не парсить JSON ради обзора. ## Три команды на онбординге Самый частый сценарий у студии — новый клиент, новый сайт, нужно завести проверки. Вместо того чтобы открывать дашборд и кликать форму монитора, это строчка в скрипте онбординга: `pingvera monitors create --type http --name "Главная" \ --target https://example.com --interval-s 60 pingvera monitors create --type tls --name "SSL example.com" \ --target example.com pingvera monitors create --type wp --name "WordPress example.com" \ --target https://example.com --site site_01J...` Тот же скрипт может дальше создать статус-страницу под клиентским доменом и канал уведомлений — `status-pages create --slug --title --monitors a,b` и `channels create --type telegram|email|...` — и на выходе онбординг клиента отдаёт не только сайт, но и готовый, включённый мониторинг, без единого клика в UI. ## Обновление и удаление — частичный PATCH `monitors update` шлёт на сервер только явно переданные флаги — это частичное изменение, не перезапись всей конфигурации монитора. У булевых флагов важна форма с явным знаком равенства: `--enabled=false`, а не просто `--enabled false` — иначе Go трактует флаг без значения как включение, что для частичного PATCH неоднозначно. `pingvera monitors update mon_01J... --enabled=false pingvera monitors delete mon_01J... # 204, печатает ok` Отдельной ручки «получить один монитор» в API нет — `monitors get ` в CLI забирает полный `list` и фильтрует по `public_id` на своей стороне. Для внешнего пользователя команды разницы нет, но если понадобится грепать вывод руками — так понятнее, откуда берутся данные. ## В CI: smoke-проверка и коды выхода CLI возвращает три кода выхода, которые прямо ложатся на условия пайплайна: `0` — успех, `1` — сервер ответил ошибкой (HTTP ≥ 400) или сеть недоступна, `2` — ошибка использования (нет токена, не хватает флага, неизвестная команда). Это значит, что мониторинг можно завести и проверить прямо в шаге деплоя, без обвязки: `out=$(pingvera monitors create --type http --name "Smoke" --target https://example.com) || exit 1 id=$(echo "$out" | grep -o '"public_id": "mon_[^"]*"' | head -1 | cut -d'"' -f4) pingvera monitors list -o table pingvera monitors delete "$id"` Тот же принцип годится и как обратный сценарий — не создавать монитор в CI, а сверять, что он уже существует и включён: `monitors list` плюс проверка кода выхода как условие «зелёного» шага деплоя. ## Каналы доставки из терминала `channels create` принимает `--type` — `email`, `telegram`, `max`, `webhook`, `slack`, `discord` или `vk` — и JSON в `--config`: для вебхука/Slack/Discord нужен `{"url": "https://..."}`, для email — `{"address": "a@b.ru"}`. У вебхук-канала сервер выдаёт секрет для HMAC-подписи один раз, при создании — CLI печатает его отдельной строкой в конце вывода, и это единственный момент, когда его можно забрать (подробнее — в статье [про подписанные вебхуки](https://pingvera.ru/blog/podpisannye-vebhuki.html)). `pingvera channels create --type webhook --name "Мой вебхук" \ --config '{"url":"https://example.com/hook"}'` Флагманская команда: terraform generate Если студия уже настроила часть мониторинга руками через дашборд, а часть — через CLI, рано или поздно возникает вопрос: а что вообще сейчас включено, и можно ли это держать в git, а не только в голове того, кто настраивал. Ответ — `pingvera terraform generate`. Команда читает read-API вашей организации (список мониторов и статус-страниц) и печатает готовый Terraform-конфиг: блок провайдера, по ресурсу `pingvera_monitor` и `pingvera_status_page` на каждую существующую сущность, и `import`-блок сразу за каждым ресурсом — это config-driven import из Terraform 1.5+, руками ничего импортировать не нужно. `pingvera terraform generate --out pingvera.tf cd $(dirname pingvera.tf) && terraform init export PINGVERA_TOKEN=pv_... terraform apply # применит import-блоки terraform plan # должен быть пустым (no changes)` Все поля в сгенерированном коде печатаются явно, включая пустые и дефолтные (`tags = []`, `config = "{}"` и подобные) — цель именно нулевой дрейф: первый `terraform plan` после импорта не должен показывать никаких изменений. На практике это значит, что весь текущий мониторинг — не только новый, а тот, что годами настраивался кликами в дашборде — можно одной командой превратить в код, положить в тот же репозиторий, что инфраструктуру клиента, и дальше вести привычным ревью пул-реквестов, а не помнить, что где нажато. Кто уже работает с провайдером Terraform напрямую — с этого места дальше про сам HCL и ресурсы рассказано в статье [про Terraform-провайдер Pingvera](https://pingvera.ru/blog/terraform-provider-monitoring-kak-kod.html). ## Главное CLI не добавляет мониторингу новых возможностей — он даёт другой способ им управлять: скриптом, а не мышкой. Для студии, которая заводит проверки на каждом онбординге, это меньше кликов и меньше ошибок. Для CI — smoke-проверка на кодах выхода без парсинга UI. А для тех, кто хочет держать мониторинг рядом с остальной инфраструктурой как код, — мост к Terraform одной командой, с нулевым дрейфом с первого дня. ## Частые вопросы **Как установить CLI?** Одной командой: `curl -fsSL https://app.pingvera.ru/dl/pingvera-cli-linux-amd64 -o pingvera && chmod +x pingvera`. Хаб раздаёт готовые бинарники под linux amd64/arm64, macOS (Intel и Apple Silicon) и Windows по `/dl` — тем же механизмом, что агент и пробер. Рядом лежит файл `.sha256` для проверки целостности. Можно и собрать из исходников: `go build -o pingvera ./cmd/cli` — бинарь один, без зависимостей. **Где взять токен и как его передать?** Токен создаётся в дашборде: **Настройки → API-токены**, со скоупом под нужные команды (`read:monitoring`, `write:monitors`, `write:status-pages`, `write:channels`). CLI принимает его через переменную окружения `PINGVERA_TOKEN` или флаг `--token` (флаг сильнее переменной). Адрес API берётся из `PINGVERA_URL` или флага `--url`, по умолчанию `https://app.pingvera.ru`. **Можно ли выгрузить текущий мониторинг в код?** Да, команда `pingvera terraform generate` читает read-API вашей организации и печатает готовый `.tf`: провайдер, ресурсы `pingvera_monitor` и `pingvera_status_page` на каждый существующий монитор и статус-страницу, и import-блок сразу за каждым ресурсом. После `terraform apply` первый `terraform plan` показывает ноль изменений — весь текущий мониторинг становится управляемым кодом без ручного переписывания.