# Interface en ligne de commande (CLI)

Envoyez des notifications push depuis votre terminal, vos scripts et votre CI, et gérez les applications, appareils, webhooks et clés API de [Pocket Alert](https://pocketalert.app). Code source et versions : [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
```

Le script vérifie la somme de contrôle SHA-256 et installe le binaire dans `/usr/local/bin` (ou `~/.local/bin`). Définissez `POCKETALERT_VERSION=v2.1.0` pour figer une version.

### Téléchargement manuel

Ces liens pointent toujours vers la dernière version :

| Plateforme | Architecture | Téléchargement |
|----------|--------------|----------|
| 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
```

## Authentification

Créez une clé API dans [Paramètres → Clés API](https://pocketalert.app/account/apikeys), puis exécutez :

```bash
pocketalert auth
```

Collez la clé à l’invite masquée : elle n’apparaît ainsi pas dans l’historique de votre shell. Le CLI vérifie la clé avant de l’enregistrer dans `~/.pocketalert/config.json`. Vous pouvez aussi la transmettre par un tube : `echo "$KEY" | pocketalert auth`.

En CI et dans les conteneurs, passez la commande `auth` et définissez plutôt une variable d’environnement :

| Variable | Rôle |
|----------|---------|
| `POCKETALERT_API_KEY` | Clé API ; prioritaire sur la clé enregistrée |
| `POCKETALERT_API_URL` | URL de base de l’API (par défaut `https://api.pocketalert.app`) |
| `POCKETALERT_CONFIG` | Chemin du fichier de configuration |

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

---

## Envoi de notifications

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

Le titre et le message peuvent être passés en arguments ou via des options (`-t`, `-m`). Transmettez du texte par un tube, ou utilisez `-m -`, pour lire le message depuis l’entrée standard :

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

| Option | Description |
|------|-------------|
| `-a, --app <tid>` | Application |
| `-d, --device <tid>` | Appareil, ou `all` (par défaut : tous les appareils) |
| `-l, --level <level>` | `silent`, `low`, `default`, `high`, `critical` (ou `-2`…`2`) |
| `--action <type:label:value>` | Bouton d’action, à répéter jusqu’à 3 fois |
| `--image <path\|url>` | Pièce jointe image |
| `--at <time>` | Envoi le `2026-10-20 09:00` (fuseau horaire du compte), au format RFC 3339 ou en secondes Unix |
| `--in <delay>` | Envoi après `30m`, `2h`, `1d`, `1d12h` |
| `-q, --quiet` | Affiche uniquement le TID du message |

### Niveaux

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

`critical` contourne le mode Ne pas déranger. (Paid) Avec l’offre gratuite, il est envoyé en `high` et le CLI affiche un avertissement. Voir [Niveaux de priorité](https://info.pocketalert.app/features/priority-levels.md).

### Boutons d’action (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 | Valeur |
|------|-------|
| `view` | URL à ouvrir |
| `http` | `URL` (envoie un POST), `GET https://…`, ou un objet JSON `{"url":"…","method":"PUT","headers":{…},"body":"…"}` |
| `copy` | Texte à copier |

Voir [Boutons d’action](https://info.pocketalert.app/features/action-buttons.md).

### Envoi programmé (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>
```

Les messages peuvent être programmés jusqu’à 30 jours à l’avance. Voir [Envoi programmé](https://info.pocketalert.app/features/scheduled-delivery.md).

### Images (Paid)

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

---

## Mode interactif

```bash
pocketalert ui
```

`pocketalert ui` ouvre une application plein écran. Parcourez et recherchez dans la boîte de réception, lisez les messages (l’ouverture d’un message le marque comme lu) et rédigez-en de nouveaux avec une application, un appareil, un niveau, une heure d’envoi, une image et des boutons d’action. Les messages programmés, les applications, les appareils et les webhooks, avec leurs requêtes récentes, sont accessibles en une touche. Les nouveaux messages s’affichent automatiquement.

![Boîte de réception avec le volet d’aperçu](https://info.pocketalert.app/images/cli/inbox.png)

Le volet d’aperçu affiche le message complet, y compris ses boutons d’action et la destination de chacun :

![Un message avec des boutons d’action](https://info.pocketalert.app/images/cli/actions.png)

`n` ouvre le compositeur. Les boutons d’action utilisent le même format `type:label:value` que `--action` :

![Rédaction d’un nouveau message](https://info.pocketalert.app/images/cli/compose.png)

| Touche | Action |
|-----|--------|
| `tab`, `1`…`5` | Boîte de réception, Programmés, Applications, Appareils, Webhooks |
| `enter` / `esc` | Ouvrir / revenir. Sur une application ou un appareil : affiche ses messages |
| `n` | Nouveau message, `ctrl+s` envoie |
| `f` | Renvoyer ou dupliquer le message sélectionné |
| `r` / `a` / `u` | Basculer lu / tout marquer comme lu / afficher uniquement les non lus |
| `d` | Supprimer un message, annuler un message programmé, supprimer une ressource (demande confirmation) |
| `s` | Envoyer à l’application ou à l’appareil sélectionné |
| `e` / `v` / `t` | Renommer / niveau par défaut de l’application / suspendre ou reprendre un webhook |
| `/` | Rechercher |
| `y` | Copier le texte du message, le TID ou l’URL du webhook |
| `?` | Tous les raccourcis |

---

## Être notifié à la fin d’une commande

`exec` exécute une commande, affiche sa sortie comme d’habitude, puis envoie une notification push avec le statut de sortie, la durée et les dernières lignes de sortie. Le code de retour de la commande est transmis tel quel.

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

| Option | Description |
|------|-------------|
| `--on <when>` | `always` (par défaut), `success`, `failure` |
| `--tail <n>` | Nombre de lignes de sortie à inclure (10 par défaut, `0` pour les omettre) |
| `-t, --title <name>` | Nom affiché dans le titre à la place de la commande |

Les exécutions en échec utilisent par défaut le niveau `high`. Les options d’envoi de `send` (`-a`, `-d`, `-l`, `--action`, `--image`, `-q`) fonctionnent aussi ici. La confirmation est écrite sur stderr, ce qui laisse la sortie standard de la commande propre pour les tubes.

## Surveiller un journal

`watch` transforme les lignes reçues par un tube en notifications. Les lignes qui arrivent pendant la durée de `--batch` (`5s` par défaut) sont regroupées en un seul push, dans la limite de `--max-lines` (20 par défaut). Une salve d’erreurs ne consomme donc qu’un seul message de votre quota quotidien. Les options d’envoi de `send` fonctionnent aussi ici.

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

---

## Messages

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

## Applications

```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` définit le niveau par défaut des messages qui n’en précisent pas.

## Appareils

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

La sortie affiche l’URL entrante (`https://p4a.me/wh/…`) ainsi qu’une commande `curl` pour la tester. `webhooks update <tid>` ne modifie que les options que vous passez ; utilisez `--active=false` pour suspendre un webhook.

## Formulaires

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

Les formulaires se créent dans la [console web](https://pocketalert.app/forms).

## Clés API

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

> **Warning**
>
> Le jeton n’est affiché qu’une seule fois, à la création : conservez-le immédiatement.

---

## Scripts

Toutes les commandes acceptent `--json` et affichent la réponse brute de l’API :

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

Les erreurs sont écrites sur stderr et le programme se termine avec un code non nul. Une réponse `429` indique la limite quotidienne atteinte et l’heure de réinitialisation.

## Configuration

```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` (permissions `600`, dossier `700`) :

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

## Migrer depuis la 1.x

Installez la 2.x par l’une des méthodes ci-dessus : elle lit le même fichier `~/.pocketalert/config.json`, donc la clé enregistrée continue de fonctionner. Vos scripts peuvent nécessiter trois modifications :

- **Un message est obligatoire.** `pocketalert send -t "Cron OK"` sans `-m` provoque désormais une erreur. Ajoutez un message, transmettez-le par un tube ou utilisez `exec`.
- **Ne mélangez pas les formes.** Utilisez `send "Title" "Message"` ou `send -t "Title" -m "Message"`. `send -t "Title" "Message"` échoue avec `title given both as argument and --title`.
- **Utilisez `-m` pour le texte généré.** Un message positionnel commençant par `-` (une liste Markdown produite par un agent IA, par exemple) est interprété comme une option ; `-m "$text"` est toujours sûr.

Les archives de version sont désormais nommées `pocketalert_<os>_<arch>.tar.gz` (`.zip` sous Windows) au lieu des anciens fichiers `cdn.pocketalert.app/cli/*.zip`.

## Complétion du 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 installe automatiquement les complétions.

---

## Exemples

### GitHub Actions

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

Vous préférez une étape prête à l’emploi ? Consultez l’[action GitHub](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
```

### Vérification de service

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