# Command Line Interface

Kirim push notification dari terminal, skrip, dan CI Anda, serta kelola aplikasi, perangkat, webhook, dan kunci API [Pocket Alert](https://pocketalert.app). Kode sumber dan rilis: [github.com/PocketAlert/cli](https://github.com/PocketAlert/cli).

## Instalasi

**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
```

Skrip ini memverifikasi checksum SHA-256 dan menginstal ke `/usr/local/bin` (atau `~/.local/bin`). Atur `POCKETALERT_VERSION=v2.1.0` untuk mengunci versi tertentu.

### Unduh manual

Tautan berikut selalu mengarah ke rilis terbaru:

| Platform | Arsitektur | Unduh |
|----------|--------------|----------|
| 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
```

## Autentikasi

Buat kunci API di [Pengaturan → Kunci API](https://pocketalert.app/account/apikeys), lalu:

```bash
pocketalert auth
```

Tempelkan kunci di prompt tersembunyi — kunci tidak akan tersimpan di riwayat shell Anda. CLI memeriksa kunci tersebut sebelum menyimpannya di `~/.pocketalert/config.json`. Anda juga bisa menggunakan pipa: `echo "$KEY" | pocketalert auth`.

Di CI dan container, lewati `auth` dan atur variabel lingkungan sebagai gantinya:

| Variabel | Fungsi |
|----------|---------|
| `POCKETALERT_API_KEY` | Kunci API; diprioritaskan di atas kunci yang tersimpan |
| `POCKETALERT_API_URL` | URL dasar API (default `https://api.pocketalert.app`) |
| `POCKETALERT_CONFIG` | Path file konfigurasi |

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

---

## Mengirim notifikasi

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

Judul dan pesan bisa berupa argumen atau flag (`-t`, `-m`). Alirkan teks lewat pipa, atau gunakan `-m -`, untuk membaca pesan dari stdin:

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

| Flag | Deskripsi |
|------|-------------|
| `-a, --app <tid>` | Aplikasi |
| `-d, --device <tid>` | Perangkat, atau `all` (default: semua perangkat) |
| `-l, --level <level>` | `silent`, `low`, `default`, `high`, `critical` (atau `-2`…`2`) |
| `--action <type:label:value>` | Tombol aksi, dapat diulang hingga 3 kali |
| `--image <path\|url>` | Lampiran gambar |
| `--at <time>` | Kirim pada `2026-10-20 09:00` (zona waktu akun), RFC 3339, atau detik Unix |
| `--in <delay>` | Kirim setelah `30m`, `2h`, `1d`, `1d12h` |
| `-q, --quiet` | Hanya cetak TID pesan |

### Level

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

`critical` melewati Jangan Ganggu. (Paid) Pada paket gratis, pesan dikirim sebagai `high` dan CLI akan menampilkan catatan. Lihat [Level prioritas](https://info.pocketalert.app/features/priority-levels.md).

### Tombol aksi (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"
```

| Type | Value |
|------|-------|
| `view` | URL yang akan dibuka |
| `http` | `URL` (mengirim POST), `GET https://…`, atau objek JSON `{"url":"…","method":"PUT","headers":{…},"body":"…"}` |
| `copy` | Teks yang akan disalin |

Lihat [Tombol aksi](https://info.pocketalert.app/features/action-buttons.md).

### Pengiriman terjadwal (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>
```

Pesan dapat dijadwalkan hingga 30 hari ke depan. Lihat [Pengiriman terjadwal](https://info.pocketalert.app/features/scheduled-delivery.md).

### Gambar (Paid)

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

---

## Mode interaktif

```bash
pocketalert ui
```

`pocketalert ui` membuka aplikasi layar penuh. Telusuri dan cari di kotak masuk, baca pesan (membuka pesan akan menandainya sebagai sudah dibaca), dan tulis pesan baru dengan aplikasi, perangkat, level, waktu pengiriman, gambar, dan tombol aksi. Pesan terjadwal, aplikasi, perangkat, dan webhook — beserta permintaan terbarunya — dapat diakses dengan satu tombol. Pesan baru akan muncul secara otomatis.

![Kotak masuk dengan panel pratinjau](https://info.pocketalert.app/images/cli/inbox.png)

Panel pratinjau menampilkan seluruh pesan, termasuk tombol aksinya dan tujuan masing-masing:

![Pesan dengan tombol aksi](https://info.pocketalert.app/images/cli/actions.png)

Tekan `n` untuk membuka penulis pesan. Tombol aksi menggunakan format `type:label:value` yang sama seperti `--action`:

![Menulis pesan baru](https://info.pocketalert.app/images/cli/compose.png)

| Tombol | Aksi |
|-----|--------|
| `tab`, `1`…`5` | Kotak masuk, Terjadwal, Aplikasi, Perangkat, Webhook |
| `enter` / `esc` | Buka / kembali. Pada aplikasi atau perangkat: tampilkan pesannya |
| `n` | Pesan baru, `ctrl+s` untuk mengirim |
| `f` | Kirim ulang atau duplikasi pesan yang dipilih |
| `r` / `a` / `u` | Ubah status baca / tandai semua dibaca / tampilkan hanya yang belum dibaca |
| `d` | Hapus pesan, batalkan pesan terjadwal, hapus sumber daya (akan meminta konfirmasi) |
| `s` | Kirim ke aplikasi atau perangkat yang dipilih |
| `e` / `v` / `t` | Ganti nama / level default aplikasi / jeda atau lanjutkan webhook |
| `/` | Cari |
| `y` | Salin teks pesan, TID, atau URL webhook |
| `?` | Semua pintasan |

---

## Beri tahu saat perintah selesai

`exec` menjalankan sebuah perintah, menampilkan outputnya seperti biasa, lalu mengirim push berisi status keluar, durasi, dan beberapa baris terakhir output. Kode keluar perintah tetap diteruskan.

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

| Flag | Deskripsi |
|------|-------------|
| `--on <when>` | `always` (default), `success`, `failure` |
| `--tail <n>` | Jumlah baris output yang disertakan (default 10, `0` untuk menghilangkan) |
| `-t, --title <name>` | Nama di judul sebagai pengganti perintah |

Proses yang gagal default ke level `high`. Flag pengiriman dari `send` (`-a`, `-d`, `-l`, `--action`, `--image`, `-q`) juga berfungsi di sini. Konfirmasi dikirim ke stderr, sehingga stdout perintah tetap bersih untuk pipa.

## Pantau log

`watch` mengubah baris yang dialirkan menjadi notifikasi. Baris yang masuk dalam rentang `--batch` (default `5s`) dikelompokkan menjadi satu push, hingga `--max-lines` (default 20), sehingga serangkaian error hanya memakan satu pesan dari kuota harian Anda. Flag pengiriman dari `send` juga berfungsi di sini.

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

---

## Pesan

```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
```

## Aplikasi

```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` mengatur level default untuk pesan yang tidak menentukannya.

## Perangkat

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

## Webhook

```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
```

Output menampilkan URL masuk (`https://p4a.me/wh/…`) dan perintah `curl` untuk mengujinya. `webhooks update <tid>` hanya mengubah flag yang Anda berikan; gunakan `--active=false` untuk menjeda webhook.

## Formulir

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

Formulir dibuat di [konsol web](https://pocketalert.app/forms).

## Kunci API

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

> **Warning**
>
> Token hanya ditampilkan sekali saat dibuat — simpan segera.

---

## Scripting

Setiap perintah menerima `--json` dan mencetak respons API mentah:

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

Error dikirim ke stderr dan keluar dengan kode non-zero. Respons `429` menjelaskan batas harian dan kapan batas tersebut direset.

## Konfigurasi

```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` (izin `600`, direktori `700`):

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

## Upgrade dari 1.x

Instal 2.x dengan metode apa pun di atas; versi ini membaca `~/.pocketalert/config.json` yang sama, sehingga kunci yang tersimpan tetap berfungsi. Skrip Anda mungkin memerlukan tiga perubahan:

- **Pesan wajib diisi.** `pocketalert send -t "Cron OK"` tanpa `-m` kini menjadi error. Tambahkan pesan, alirkan lewat pipa, atau gunakan `exec`.
- **Jangan campur bentuknya.** Gunakan `send "Title" "Message"` atau `send -t "Title" -m "Message"`. `send -t "Title" "Message"` akan gagal dengan `title given both as argument and --title`.
- **Gunakan `-m` untuk teks yang dihasilkan.** Pesan posisional yang diawali `-` (misalnya daftar Markdown dari agen AI) akan diurai sebagai flag; `-m "$text"` selalu aman.

Arsip rilis kini bernama `pocketalert_<os>_<arch>.tar.gz` (`.zip` di Windows), menggantikan file lama `cdn.pocketalert.app/cli/*.zip`.

## Penyelesaian perintah 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 memasang penyelesaian perintah secara otomatis.

---

## Contoh

### GitHub Actions

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

Lebih suka langkah siap pakai? Lihat [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
```

### Pemeriksaan layanan

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