# Интерфейс командной строки

Отправляйте push-уведомления из терминала, скриптов и CI, а также управляйте приложениями, устройствами, вебхуками и API-ключами [Pocket Alert](https://pocketalert.app). Исходный код и релизы: [github.com/PocketAlert/cli](https://github.com/PocketAlert/cli).

## Установка

**Script (macOS/Linux)**

```bash
curl -fsSL https://raw.githubusercontent.com/PocketAlert/cli/main/install.sh | sh
```

**Homebrew**

```bash
brew install pocketalert/tap/pocketalert
```

**Go**

```bash
go install github.com/PocketAlert/cli/cmd/pocketalert@latest
```

Скрипт проверяет контрольную сумму SHA-256 и устанавливает CLI в `/usr/local/bin` (или `~/.local/bin`). Чтобы зафиксировать версию, задайте `POCKETALERT_VERSION=v2.1.0`.

### Ручная загрузка

Эти ссылки всегда ведут на последний релиз:

| Платформа | Архитектура | Загрузка |
|----------|--------------|----------|
| Linux | AMD64 | [pocketalert_linux_amd64.tar.gz](https://github.com/PocketAlert/cli/releases/latest/download/pocketalert_linux_amd64.tar.gz) |
| Linux | ARM64 | [pocketalert_linux_arm64.tar.gz](https://github.com/PocketAlert/cli/releases/latest/download/pocketalert_linux_arm64.tar.gz) |
| macOS | Intel | [pocketalert_darwin_amd64.tar.gz](https://github.com/PocketAlert/cli/releases/latest/download/pocketalert_darwin_amd64.tar.gz) |
| macOS | Apple Silicon | [pocketalert_darwin_arm64.tar.gz](https://github.com/PocketAlert/cli/releases/latest/download/pocketalert_darwin_arm64.tar.gz) |
| Windows | AMD64 | [pocketalert_windows_amd64.zip](https://github.com/PocketAlert/cli/releases/latest/download/pocketalert_windows_amd64.zip) |

**Linux/macOS**

```bash
tar -xzf pocketalert_*.tar.gz
sudo mv pocketalert /usr/local/bin/
# macOS, if Gatekeeper blocks a browser download:
xattr -d com.apple.quarantine /usr/local/bin/pocketalert
```

**Windows**

```powershell
# Unzip, then add the folder with pocketalert.exe to PATH
.\pocketalert.exe --help
```

## Аутентификация

Создайте API-ключ в разделе [Настройки → API-ключи](https://pocketalert.app/account/apikeys), а затем выполните:

```bash
pocketalert auth
```

Вставьте ключ в скрытое поле ввода — он не попадёт в историю shell. Перед сохранением в `~/.pocketalert/config.json` CLI проверяет ключ. Его также можно передать через пайп: `echo "$KEY" | pocketalert auth`.

В CI и контейнерах пропустите `auth` и задайте переменную окружения:

| Переменная | Назначение |
|----------|---------|
| `POCKETALERT_API_KEY` | API-ключ; имеет приоритет над сохранённым |
| `POCKETALERT_API_URL` | Базовый URL API (по умолчанию `https://api.pocketalert.app`) |
| `POCKETALERT_CONFIG` | Путь к файлу конфигурации |

```bash
pocketalert profile   # who am I?
pocketalert logout    # remove the saved key
```

---

## Отправка уведомлений

```bash
pocketalert send "Deploy finished" "v1.4.2 is live"
```

Заголовок и текст можно передать как аргументы или через флаги (`-t`, `-m`). Чтобы прочитать текст из stdin, передайте его через пайп или укажите `-m -`:

```bash
df -h | pocketalert send "Disk report"
```

| Флаг | Описание |
|------|-------------|
| `-a, --app <tid>` | Приложение |
| `-d, --device <tid>` | Устройство или `all` (по умолчанию: все устройства) |
| `-l, --level <level>` | `silent`, `low`, `default`, `high`, `critical` (или `-2`…`2`) |
| `--action <type:label:value>` | Кнопка действия, можно указать до 3 раз |
| `--image <path\|url>` | Вложение-изображение |
| `--at <time>` | Доставить в `2026-10-20 09:00` (часовой пояс аккаунта), RFC 3339 или Unix-время в секундах |
| `--in <delay>` | Доставить через `30m`, `2h`, `1d`, `1d12h` |
| `-q, --quiet` | Вывести только TID сообщения |

### Уровни

```bash
pocketalert send "Disk 95%" "/var is almost full" --level high
pocketalert send "Prod is down" "502 from api" --level critical
```

`critical` обходит режим «Не беспокоить». (Paid) На бесплатном тарифе уведомление доставляется как `high`, а CLI выводит примечание. См. [Уровни приоритета](https://info.pocketalert.app/features/priority-levels.md).

### Кнопки действий (Paid)

```bash
pocketalert send "Deploy failed" "main@4f2c" -l critical \
  --action "view:Open logs:https://ci.example.com/run/1" \
  --action "http:Retry:https://ci.example.com/run/1/retry" \
  --action "copy:Copy SHA:4f2c9e1"
```

| Тип | Значение |
|------|-------|
| `view` | URL для открытия |
| `http` | `URL` (отправляет POST), `GET https://…` или JSON-объект `{"url":"…","method":"PUT","headers":{…},"body":"…"}` |
| `copy` | Текст для копирования |

См. [Кнопки действий](https://info.pocketalert.app/features/action-buttons.md).

### Отложенная отправка (Paid)

```bash
pocketalert send "Standup" "In 10 minutes" --at "2026-10-20 09:50"
pocketalert send "Reminder" "Rotate the keys" --in 1d

pocketalert scheduled list                  # pending, soonest first
pocketalert scheduled list --status all
pocketalert scheduled cancel <tid>
```

Сообщения можно запланировать не более чем на 30 дней вперёд. См. [Отложенная отправка](https://info.pocketalert.app/features/scheduled-delivery.md).

### Изображения (Paid)

```bash
pocketalert send "Grafana" "CPU spike" --image ./panel.png
pocketalert send "Grafana" "CPU spike" --image https://example.com/panel.png
```

---

## Интерактивный режим

```bash
pocketalert ui
```

`pocketalert ui` открывает полноэкранное приложение. Здесь можно просматривать и искать сообщения во входящих, читать их (открытие сообщения отмечает его прочитанным) и создавать новые с выбором приложения, устройства, уровня, времени доставки, изображения и кнопок действий. Отложенные сообщения, приложения, устройства и вебхуки с их последними запросами открываются одной клавишей. Новые сообщения появляются автоматически.

![Входящие с панелью предпросмотра](https://info.pocketalert.app/images/cli/inbox.png)

Панель предпросмотра показывает сообщение целиком, включая кнопки действий и адрес каждой из них:

![Сообщение с кнопками действий](https://info.pocketalert.app/images/cli/actions.png)

`n` открывает редактор. Кнопки действий задаются в том же формате `type:label:value`, что и `--action`:

![Создание нового сообщения](https://info.pocketalert.app/images/cli/compose.png)

| Клавиша | Действие |
|-----|--------|
| `tab`, `1`…`5` | Входящие, Отложенные, Приложения, Устройства, Вебхуки |
| `enter` / `esc` | Открыть / назад. Для приложения или устройства: показать его сообщения |
| `n` | Новое сообщение, `ctrl+s` отправляет |
| `f` | Отправить повторно или дублировать выбранное сообщение |
| `r` / `a` / `u` | Переключить прочтение / отметить все прочитанными / показать только непрочитанные |
| `d` | Удалить сообщение, отменить отложенное или удалить ресурс (с подтверждением) |
| `s` | Отправить в выбранное приложение или на устройство |
| `e` / `v` / `t` | Переименовать / уровень по умолчанию для приложения / приостановить или возобновить вебхук |
| `/` | Поиск |
| `y` | Скопировать текст сообщения, TID или URL вебхука |
| `?` | Все сочетания клавиш |

---

## Уведомление по завершении команды

`exec` запускает команду, выводит её результат как обычно, а затем отправляет push с кодом выхода, длительностью и последними строками вывода. Код выхода самой команды передаётся дальше.

```bash
pocketalert exec -- make release
pocketalert exec --on failure -l critical -- ./backup.sh
pocketalert exec -t "Nightly import" --tail 20 -- python import.py
```

| Флаг | Описание |
|------|-------------|
| `--on <when>` | `always` (по умолчанию), `success`, `failure` |
| `--tail <n>` | Количество строк вывода для включения (по умолчанию 10, `0` чтобы не включать) |
| `-t, --title <name>` | Имя в заголовке вместо команды |

Неудачные запуски по умолчанию получают уровень `high`. Флаги отправки из `send` (`-a`, `-d`, `-l`, `--action`, `--image`, `-q`) работают и здесь. Подтверждение выводится в stderr, поэтому stdout команды остаётся чистым для пайпов.

## Наблюдение за логом

`watch` превращает строки из пайпа в уведомления. Строки, пришедшие в течение `--batch` (по умолчанию `5s`), объединяются в один push, но не более `--max-lines` (по умолчанию 20), поэтому всплеск ошибок расходует одно сообщение из дневного лимита. Флаги отправки из `send` работают и здесь.

```bash
tail -f app.log | grep --line-buffered ERROR | pocketalert watch -t "app errors"
journalctl -fu nginx | pocketalert watch --batch 1m -l high
```

---

## Сообщения

```bash
pocketalert messages list                 # 20 newest
pocketalert messages list -n 50 --offset 50
pocketalert messages list --sort asc --device <device-tid>
pocketalert messages get <tid>            # also marks it as read
pocketalert messages read <tid> [<tid>…]
pocketalert messages read --all
pocketalert messages delete <tid> [<tid>…]
pocketalert messages delete --all         # asks for confirmation; --yes in scripts
pocketalert messages stats                # messages per day
pocketalert usage                         # today's usage against the daily limit
```

## Приложения

```bash
pocketalert apps list
pocketalert apps get <tid>
pocketalert apps create -n "Production" -c "#EF4444" -l high
pocketalert apps update <tid> --name "Prod" --level critical
pocketalert apps delete <tid>
```

`--level` задаёт уровень по умолчанию для сообщений, которые его не указывают.

## Устройства

```bash
pocketalert devices list
pocketalert devices get <tid>
pocketalert devices rename <tid> "Work iPhone"
pocketalert devices delete <tid>
```

## Вебхуки

```bash
pocketalert webhooks list
pocketalert webhooks get <tid>
pocketalert webhooks history <tid> [--status error] [--page 2]
pocketalert webhooks delete <tid>
```

**Full JSON payload**

```bash
pocketalert webhooks create -n "GitHub" -m "*"
```

**Extract fields**

```bash
pocketalert webhooks create -n "Deploy" -m "Deployed %repository.name% by %sender.login%"
```

**Level and actions**

```bash
pocketalert webhooks create -n "Alertmanager" -m "%alerts.0.annotations.summary%" -l critical \
  --action "view:Open:%externalURL%"
```

**Custom URL**

```bash
pocketalert webhooks create -n "Uptime" -m "%monitor.name% is %status%" --slug uptime-alerts
```

Вывод показывает входящий URL (`https://p4a.me/wh/…`) и команду `curl` для проверки. `webhooks update <tid>` меняет только переданные флаги; используйте `--active=false`, чтобы приостановить вебхук.

## Формы

```bash
pocketalert forms list
pocketalert forms delete <tid>
```

Формы создаются в [веб-консоли](https://pocketalert.app/forms).

## API-ключи

```bash
pocketalert apikeys list
pocketalert apikeys create -n "CI"
pocketalert apikeys delete <tid>
```

> **Warning**
>
> Токен выводится один раз при создании — сохраните его сразу.

---

## Скрипты

Каждая команда принимает `--json` и выводит необработанный ответ API:

```bash
pocketalert messages list --json | jq -r '.data[].title'
TID=$(pocketalert send "Build" "started" -q)
```

Ошибки выводятся в stderr, и команда завершается с ненулевым кодом. Ответ `429` объясняет дневной лимит и время его сброса.

## Конфигурация

```bash
pocketalert config                                    # show settings and where the key comes from
pocketalert config set base_url https://api.example.com
pocketalert config reset base_url
```

`~/.pocketalert/config.json` (права `600`, каталог `700`):

```json
{
  "api_key": "your-api-key",
  "base_url": "https://api.pocketalert.app"
}
```

## Переход с 1.x

Установите 2.x любым из способов выше: CLI читает тот же `~/.pocketalert/config.json`, поэтому сохранённый ключ продолжит работать. В скриптах может понадобиться три изменения:

- **Сообщение обязательно.** `pocketalert send -t "Cron OK"` без `-m` теперь вызывает ошибку. Добавьте сообщение, передайте его через пайп или используйте `exec`.
- **Не смешивайте формы записи.** Используйте `send "Title" "Message"` или `send -t "Title" -m "Message"`. Запись `send -t "Title" "Message"` завершается ошибкой `title given both as argument and --title`.
- **Используйте `-m` для сгенерированного текста.** Позиционный текст, который начинается с `-` (например, список Markdown от ИИ-агента), разбирается как флаг; `-m "$text"` всегда безопасен.

Архивы релизов теперь называются `pocketalert_<os>_<arch>.tar.gz` (`.zip` в Windows) вместо старых файлов `cdn.pocketalert.app/cli/*.zip`.

## Автодополнение в shell

**zsh**

```bash
pocketalert completion zsh > "${fpath[1]}/_pocketalert"
```

**bash**

```bash
pocketalert completion bash > /etc/bash_completion.d/pocketalert
```

**fish**

```bash
pocketalert completion fish > ~/.config/fish/completions/pocketalert.fish
```

Homebrew устанавливает автодополнение автоматически.

---

## Примеры

### GitHub Actions

```yaml
- name: Deploy
  run: pocketalert exec -t "Deploy ${{ github.ref_name }}" -- make deploy
  env:
    POCKETALERT_API_KEY: ${{ secrets.POCKETALERT_API_KEY }}
```

Если нужен готовый шаг, см. [GitHub Action](https://github.com/PocketAlert/notification-action).

### Cron

```bash
# Alert only when the backup fails
0 3 * * * /usr/local/bin/pocketalert exec --on failure -l critical -- /opt/backup.sh
```

### Проверка сервиса

```bash
#!/bin/sh
systemctl is-active --quiet nginx || \
  pocketalert send "NGINX down" "on $(hostname)" -l critical \
    --action "view:Status page:https://status.example.com"
```
