Uptimely CLI

CLI помогает работать с мониторингом из терминала: посмотреть список проверок, добавить монитор после релиза, поставить его на паузу или передать данные в свой скрипт. Команды также доступны для инцидентов, страниц статуса и каналов уведомлений.

Установка

Понадобится Node.js 22.12 или новее. Установите пакет @uptimelyru/cli :


npm install --global @uptimelyru/cli
uptimely --version
uptimely --help

Для обновления повторите команду установки. В CI можно закрепить версию:


npm install --global @uptimelyru/cli@0.2.0

Интерактивный пульт

Начиная с версии 0.2.0, запустите uptimely без подкоманды, чтобы открыть пульт в терминале. Если ключ ещё не сохранён, CLI предложит войти. Для выбора профиля: uptimely --profile work.

Клавиша	Действие
Tab	Мониторы / инциденты
↑↓ и Enter	Выбрать запись и открыть карточку
`/`	Поиск по имени, адресу или ID монитора
`f`	Фильтры: ←→ состояние, Tab тип монитора
`r`	Обновить данные
`p` в карточке монитора	Пауза / возобновление с подтверждением `y`
`n`	Мастер создания HTTP-монитора
`l` в инцидентах	Загрузить следующую часть истории
Esc / `q`	Назад / выход

Мастер проверяет имя, URL, метод GET/HEAD, интервал, таймаут, ожидаемый HTTP-код и перенаправления. Enter переводит к следующему полю и затем к сводке; ещё один Enter создаёт монитор. Ошибка сервера сохраняет введённые значения. Повтор неизменённого запроса из этой формы использует прежний ключ идемпотентности; после создания откроется карточка с ожиданием первой проверки.

Активный экран обновляется раз в минуту после ответа API. При сетевой ошибке старые данные остаются с отметкой «Не обновлено»; время получения данных и время последней проверки показаны отдельно. Инциденты загружаются по 50: поиск и фильтры работают по уже загруженной истории. Подробных результатов отдельных проверок в этой версии пульта нет.

Нужен терминал от 80×24. Состояния подписаны текстом, поддерживается NO_COLOR. В CI, при перенаправлении вывода или TERM=dumb команда без подкоманды показывает справку. Обычные команды и JSON-вывод продолжают работать; --json и --format требуют подкоманду.

Вход через браузер


uptimely auth login

Выберите «Подтвердить в браузере». В открывшемся кабинете сверьте код с терминалом, выберите рабочее пространство и подтвердите доступ. По умолчанию отмечены только права на чтение. Если планируете создавать или менять мониторы, добавьте право «Изменение мониторов» (MONITORS_WRITE) перед подтверждением.

Для терминала на удалённом сервере используйте:


uptimely auth login --no-browser

CLI покажет ссылку: откройте её на своём компьютере и подтвердите вход. Код действует 10 минут. После подтверждения вернитесь в терминал и проверьте подключение:


uptimely auth status
uptimely monitors list

Если запустить команду без сохранённого ключа в обычном терминале, CLI сам предложит войти. Справка и локальная проверка запроса через --dry-run доступны без входа.

Вход по API-ключу

Создайте ключ в настройках API-ключей рабочего пространства. Выполните uptimely auth login и выберите «Ввести API key» — ввод будет скрыт. Доступ ограничен правами ключа и текущей ролью его создателя.

Чтобы передать ключ из менеджера секретов, направьте его вывод в команду:


uptimely auth login --api-key-stdin

Этот режим читает ключ из стандартного ввода до конца потока. Для CI удобнее переменная UPTIMELY_API_KEY: CLI использует её сразу, без входа в браузере и сохранения на диск. Она имеет приоритет над сохранённым ключом.

Работа с мониторами

Получите все мониторы в JSON:


uptimely monitors list --all --json

Для создания нужен ключ с правом «Изменение мониторов» (MONITORS_WRITE). Пример HTTP-проверки с интервалом 300 секунд и таймаутом 10 секунд:


uptimely monitors create http --name checkout --url https://example.com --interval 300 --timeout 10

CLI поддерживает создание HTTP, Ping, TCP, Heartbeat, Keyword, DNS, Domain и SSL мониторов. Доступные интервалы, типы проверок и количество мониторов зависят от тарифа.

В следующих командах замените MONITOR_ID на UUID из списка мониторов:


uptimely monitors get MONITOR_ID --json
uptimely monitors update MONITOR_ID --name checkout-api
uptimely monitors pause MONITOR_ID
uptimely monitors resume MONITOR_ID

Для удаления нужно отдельное право «Удаление мониторов» (MONITORS_DELETE). Выполните uptimely monitors delete MONITOR_ID. В терминале CLI запросит подтверждение; в скрипте его нужно передать явно флагом --confirm.

Настройки в JSON-файле

Получите пример, отредактируйте его и проверьте запрос перед отправкой:


uptimely monitors schema http --example --json > monitor.json
uptimely monitors create http --body @monitor.json --dry-run --json

--dry-run проверяет форму запроса локально и ничего не создаёт. Проверку URL, прав и лимитов выполняет сервер при настоящем запросе. Когда настройки готовы, повторите команду без --dry-run.

--body @monitor.json задаёт весь запрос; его нельзя смешивать с флагами вроде --name или --url. Для HTTP-тела самой проверки есть отдельный флаг --request-body.

Другие команды


uptimely incidents list --json
uptimely status-pages list
uptimely notification-channels list
uptimely monitors create --help
uptimely status-pages --help

Справка --help работает на каждом уровне и показывает доступные действия и параметры.

CLI в CI

Сохраните API-ключ в секретах вашей CI-системы и передайте его заданию как UPTIMELY_API_KEY. Для выгрузки мониторов достаточно права «Чтение мониторов» (MONITORS_READ). После установки CLI запустите:


uptimely auth status --json
uptimely monitors list --all --json > monitors.json

Результат идёт в стандартный вывод, ошибки — в stderr. Списки возвращаются объектом с полями items и pagination. У команд с постраничным выводом --all собирает весь список; для одной страницы доступны --page и --size, нумерация начинается с нуля.

CLI не повторяет запросы на изменение автоматически. Если связь оборвалась во время создания монитора, сначала проверьте список. Для повторения одного и того же запроса создания можно заранее задать --idempotency-key и использовать то же значение при повторе. При новом запуске без этого флага CLI генерирует новый ключ запроса.

Код завершения	Что означает
`0`	Команда выполнена
`1`	Ошибка сети, сервера или локального окружения
`2`	Неверные параметры
`4`	Требуется вход или ключ больше не действует
`5`	Не хватает прав или возможностей тарифа
`6`	Ресурс не найден
`7`	Превышен лимит запросов
`8`	Конфликт с текущим состоянием ресурса
`130`	Команда отменена

Не вставляйте ключ в текст команд, файлы репозитория или журналы сборки.

Хранение ключа и выход

По умолчанию ключ сохраняется в системном хранилище ОС. На Linux для этого нужен Secret Service. Если на Linux или macOS хранилище недоступно, можно явно выбрать файл:


uptimely auth login --storage file

Файл доступен только владельцу, но не зашифрован. В Windows этот режим отключён: используйте системное хранилище или UPTIMELY_API_KEY.


uptimely auth logout

Эта команда удаляет сохранённый локально ключ. Чтобы закрыть доступ к API, отзовите ключ в кабинете. Переменная UPTIMELY_API_KEY после выхода продолжает действовать, пока вы не удалите её из окружения. Каждый подтверждённый вход через браузер выпускает отдельный ключ.

Для разных рабочих пространств можно завести профили: uptimely --profile work auth login. Затем передавайте тот же --profile work остальным командам. По умолчанию используется профиль default.

Если что-то не получилось

Ситуация	Что сделать
Браузер не открылся	Откройте выведенную ссылку вручную или повторите вход с `--no-browser`.
Код истёк или вход отклонён	Запустите `uptimely auth login` ещё раз.
Список доступен, но создать монитор нельзя	Проверьте права через `auth status`. Нужно право «Изменение мониторов» (`MONITORS_WRITE`); также действуют роль и тариф.
Вход подтверждён, но ключ не сохранился	Отзовите созданный CLI-ключ в кабинете, настройте хранилище и повторите вход.
После входа используется другое рабочее пространство	Проверьте `--profile` и `UPTIMELY_API_KEY`: переменная окружения перекрывает сохранённый ключ.
Команда просит авторизацию в CI	Передайте `UPTIMELY_API_KEY` из секретов именно в окружение задания.

Для своего развёртывания укажите --api-url или UPTIMELY_API_URL, например http://localhost:8080. Нужен адрес без пути /api: по умолчанию CLI использует https://api.uptimely.ru. Обычный HTTP разрешён только для localhost, 127.0.0.1 и [::1]; для остальных адресов нужен HTTPS.