CLI Pingvera: мониторинг из терминала и скриптов

21 июля 2026 · 7 мин чтения

Дашборд удобен, когда мониторинг настраивает один человек мышкой. Но когда сайтов десятки, а заводить проверки нужно на каждом онбординге нового клиента, кликать по формам — это разговор не про удобство, а про потерянное время и человеческую ошибку в четвёртом мониторе за день. Поэтому у Pingvera есть CLI: тот же write-API, что использует дашборд, но в терминале, скрипте или 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	--url	PINGVERA_URL	https://app.pingvera.ru
токен	--token	PINGVERA_TOKEN	обязателен

Токен создаётся в дашборде: Настройки → 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 <id> в 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 печатает его отдельной строкой в конце вывода, и это единственный момент, когда его можно забрать (подробнее — в статье про подписанные вебхуки).

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.

Главное

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 показывает ноль изменений — весь текущий мониторинг становится управляемым кодом без ручного переписывания.

Читайте также: Мониторинг в вашем ИИ-ассистенте: MCP и Подписанные вебхуки: откуда получатель знает, что это правда Pingvera.