# Kommandozeile (CLI)

Sende Push-Benachrichtigungen aus dem Terminal, aus Skripten und der CI und verwalte [Pocket Alert](https://pocketalert.app)-Anwendungen, Geräte, Webhooks und API-Schlüssel. Quellcode und Releases: [github.com/PocketAlert/cli](https://github.com/PocketAlert/cli).

## Installation

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

Das Skript prüft die SHA-256-Prüfsumme und installiert nach `/usr/local/bin` (oder `~/.local/bin`). Setze `POCKETALERT_VERSION=v2.1.0`, um eine Version festzulegen.

### Manueller Download

Diese Links zeigen immer auf das neueste Release:

| Plattform | Architektur | Download |
|----------|--------------|----------|
| 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
```

## Authentifizierung

Erstelle einen API-Schlüssel unter [Einstellungen → API-Schlüssel](https://pocketalert.app/account/apikeys) und führe dann aus:

```bash
pocketalert auth
```

Füge den Schlüssel an der verdeckten Eingabeaufforderung ein – er landet so nicht in deinem Shell-Verlauf. Die CLI prüft den Schlüssel, bevor sie ihn in `~/.pocketalert/config.json` speichert. Du kannst ihn auch durchreichen: `echo "$KEY" | pocketalert auth`.

In CI und Containern überspringst du `auth` und setzt stattdessen eine Umgebungsvariable:

| Variable | Zweck |
|----------|---------|
| `POCKETALERT_API_KEY` | API-Schlüssel; hat Vorrang vor dem gespeicherten |
| `POCKETALERT_API_URL` | Basis-URL der API (Standard `https://api.pocketalert.app`) |
| `POCKETALERT_CONFIG` | Pfad der Konfigurationsdatei |

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

---

## Push-Benachrichtigungen senden

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

Titel und Nachricht können als Argumente oder über Flags (`-t`, `-m`) übergeben werden. Leite Text per Pipe weiter oder übergib `-m -`, um die Nachricht von stdin zu lesen:

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

| Flag | Beschreibung |
|------|-------------|
| `-a, --app <tid>` | Anwendung |
| `-d, --device <tid>` | Gerät oder `all` (Standard: alle Geräte) |
| `-l, --level <level>` | `silent`, `low`, `default`, `high`, `critical` (oder `-2`…`2`) |
| `--action <type:label:value>` | Aktionsbutton, bis zu 3-mal wiederholbar |
| `--image <path\|url>` | Bildanhang |
| `--at <time>` | Zustellung um `2026-10-20 09:00` (Zeitzone des Kontos), RFC 3339 oder Unix-Sekunden |
| `--in <delay>` | Zustellung nach `30m`, `2h`, `1d`, `1d12h` |
| `-q, --quiet` | Nur die TID der Nachricht ausgeben |

### Prioritätsstufen

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

`critical` umgeht „Nicht stören“. (Paid) Im kostenlosen Tarif wird sie als `high` zugestellt, und die CLI gibt einen Hinweis aus. Siehe [Prioritätsstufen](https://info.pocketalert.app/features/priority-levels.md).

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

| Typ | Wert |
|------|-------|
| `view` | URL zum Öffnen |
| `http` | `URL` (sendet POST), `GET https://…` oder ein JSON-Objekt `{"url":"…","method":"PUT","headers":{…},"body":"…"}` |
| `copy` | Zu kopierender Text |

Siehe [Aktionsbuttons](https://info.pocketalert.app/features/action-buttons.md).

### Geplanter Versand (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>
```

Nachrichten lassen sich bis zu 30 Tage im Voraus planen. Siehe [Geplanter Versand](https://info.pocketalert.app/features/scheduled-delivery.md).

### Bilder (Paid)

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

---

## Interaktiver Modus

```bash
pocketalert ui
```

`pocketalert ui` öffnet eine Vollbild-App. Durchsuche und filtere den Posteingang, lies Nachrichten (beim Öffnen werden sie als gelesen markiert) und verfasse neue mit Anwendung, Gerät, Stufe, Zustellzeit, Bild und Aktionsbuttons. Geplante Nachrichten, Anwendungen, Geräte und Webhooks – mit ihren letzten Anfragen – sind mit einem Tastendruck erreichbar. Neue Nachrichten erscheinen automatisch.

![Posteingang mit Vorschaubereich](https://info.pocketalert.app/images/cli/inbox.png)

Der Vorschaubereich zeigt die gesamte Nachricht, einschließlich ihrer Aktionsbuttons und des jeweiligen Ziels:

![Eine Nachricht mit Aktionsbuttons](https://info.pocketalert.app/images/cli/actions.png)

`n` öffnet den Editor. Aktionsbuttons verwenden dasselbe Format `type:label:value` wie `--action`:

![Eine neue Nachricht verfassen](https://info.pocketalert.app/images/cli/compose.png)

| Taste | Aktion |
|-----|--------|
| `tab`, `1`…`5` | Posteingang, Geplant, Anwendungen, Geräte, Webhooks |
| `enter` / `esc` | Öffnen / zurück. Bei einer Anwendung oder einem Gerät: deren Nachrichten anzeigen |
| `n` | Neue Nachricht, `ctrl+s` sendet |
| `f` | Ausgewählte Nachricht erneut senden oder duplizieren |
| `r` / `a` / `u` | Gelesen umschalten / alle als gelesen markieren / nur ungelesene anzeigen |
| `d` | Nachricht löschen, geplante abbrechen, Ressource entfernen (fragt vorher nach) |
| `s` | An die ausgewählte Anwendung oder das Gerät senden |
| `e` / `v` / `t` | Umbenennen / Standardstufe der App / Webhook pausieren oder fortsetzen |
| `/` | Suchen |
| `y` | Nachrichtentext, TID oder Webhook-URL kopieren |
| `?` | Alle Tastenkürzel |

---

## Benachrichtigung, wenn ein Befehl fertig ist

`exec` führt einen Befehl aus, gibt seine Ausgabe wie gewohnt aus und sendet danach eine Push-Benachrichtigung mit dem Exit-Status, der Dauer und den letzten Ausgabezeilen. Der Exit-Code des Befehls wird unverändert weitergegeben.

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

| Flag | Beschreibung |
|------|-------------|
| `--on <when>` | `always` (Standard), `success`, `failure` |
| `--tail <n>` | Anzahl der einzuschließenden Ausgabezeilen (Standard 10, `0` zum Weglassen) |
| `-t, --title <name>` | Name im Titel statt des Befehls |

Fehlgeschlagene Läufe verwenden standardmäßig die Stufe `high`. Die Zustell-Flags von `send` (`-a`, `-d`, `-l`, `--action`, `--image`, `-q`) funktionieren hier ebenfalls. Die Bestätigung geht an stderr, damit die Standardausgabe des Befehls für Pipes sauber bleibt.

## Ein Log beobachten

`watch` macht aus weitergeleiteten Zeilen Benachrichtigungen. Zeilen, die innerhalb von `--batch` (Standard `5s`) eintreffen, werden zu einer Push-Benachrichtigung gebündelt, bis zu `--max-lines` (Standard 20). So kostet eine Fehlerflut nur eine Nachricht aus deinem Tageskontingent. Die Zustell-Flags von `send` funktionieren hier ebenfalls.

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

---

## Nachrichten

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

## Anwendungen

```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` legt die Standardstufe für Nachrichten fest, die keine angeben.

## Geräte

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

## Webhooks

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

Die Ausgabe zeigt die eingehende URL (`https://p4a.me/wh/…`) und einen `curl`-Befehl zum Testen. `webhooks update <tid>` ändert nur die übergebenen Flags; mit `--active=false` pausierst du einen Webhook.

## Formulare

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

Formulare werden in der [Web-Konsole](https://pocketalert.app/forms) erstellt.

## API-Schlüssel

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

> **Warning**
>
> Das Token wird nur einmal bei der Erstellung angezeigt – speichere es sofort.

---

## Skripting

Jeder Befehl akzeptiert `--json` und gibt die rohe API-Antwort aus:

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

Fehler gehen an stderr und beenden das Programm mit einem Exit-Code ungleich null. Eine `429`-Antwort erklärt das Tageslimit und wann es zurückgesetzt wird.

## Konfiguration

```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` (Berechtigungen `600`, Verzeichnis `700`):

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

## Upgrade von 1.x

Installiere 2.x mit einer der oben genannten Methoden. Die Version liest dieselbe `~/.pocketalert/config.json`, daher funktioniert der gespeicherte Schlüssel weiter. Skripte brauchen unter Umständen drei Änderungen:

- **Eine Nachricht ist Pflicht.** `pocketalert send -t "Cron OK"` ohne `-m` ist jetzt ein Fehler. Füge eine Nachricht hinzu, leite eine per Pipe weiter oder verwende `exec`.
- **Die Formen nicht mischen.** Verwende `send "Title" "Message"` oder `send -t "Title" -m "Message"`. `send -t "Title" "Message"` schlägt mit `title given both as argument and --title` fehl.
- **Für generierten Text `-m` verwenden.** Eine Positionsnachricht, die mit `-` beginnt (etwa eine Markdown-Liste von einem KI-Agenten), wird als Flag interpretiert; `-m "$text"` ist immer sicher.

Release-Archive heißen jetzt `pocketalert_<os>_<arch>.tar.gz` (unter Windows `.zip`) statt der alten Dateien `cdn.pocketalert.app/cli/*.zip`.

## Shell-Vervollständigung

**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 installiert die Vervollständigung automatisch.

---

## Beispiele

### GitHub Actions

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

Lieber einen fertigen Schritt? Siehe die [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
```

### Dienstprüfung

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