Aller au contenu

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. Code source et versions : github.com/PocketAlert/cli.

Installation ​

bash
curl -fsSL https://raw.githubusercontent.com/PocketAlert/cli/main/install.sh | sh
bash
brew install pocketalert/tap/pocketalert
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 :

PlateformeArchitectureTéléchargement
LinuxAMD64pocketalert_linux_amd64.tar.gz
LinuxARM64pocketalert_linux_arm64.tar.gz
macOSIntelpocketalert_darwin_amd64.tar.gz
macOSApple Siliconpocketalert_darwin_arm64.tar.gz
WindowsAMD64pocketalert_windows_amd64.zip
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
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, 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 :

VariableRôle
POCKETALERT_API_KEYClé API ; prioritaire sur la clé enregistrée
POCKETALERT_API_URLURL de base de l’API (par défaut https://api.pocketalert.app)
POCKETALERT_CONFIGChemin 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"
OptionDescription
-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, --quietAffiche 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. Payant Avec l’offre gratuite, il est envoyé en high et le CLI affiche un avertissement. Voir Niveaux de priorité.

Boutons d’action Payant ​

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"
TypeValeur
viewURL à ouvrir
httpURL (envoie un POST), GET https://…, ou un objet JSON {"url":"…","method":"PUT","headers":{…},"body":"…"}
copyTexte à copier

Voir Boutons d’action.

Envoi programmé Payant ​

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é.

Images Payant ​

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

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

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

Rédaction d’un nouveau message

ToucheAction
tab, 1…5Boîte de réception, Programmés, Applications, Appareils, Webhooks
enter / escOuvrir / revenir. Sur une application ou un appareil : affiche ses messages
nNouveau message, ctrl+s envoie
fRenvoyer ou dupliquer le message sélectionné
r / a / uBasculer lu / tout marquer comme lu / afficher uniquement les non lus
dSupprimer un message, annuler un message programmé, supprimer une ressource (demande confirmation)
sEnvoyer à l’application ou à l’appareil sélectionné
e / v / tRenommer / niveau par défaut de l’application / suspendre ou reprendre un webhook
/Rechercher
yCopier 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
OptionDescription
--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>
bash
pocketalert webhooks create -n "GitHub" -m "*"
bash
pocketalert webhooks create -n "Deploy" -m "Deployed %repository.name% by %sender.login%"
bash
pocketalert webhooks create -n "Alertmanager" -m "%alerts.0.annotations.summary%" -l critical \
  --action "view:Open:%externalURL%"
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.

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 ​

bash
pocketalert completion zsh > "${fpath[1]}/_pocketalert"
bash
pocketalert completion bash > /etc/bash_completion.d/pocketalert
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.

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"

Documentation de Pocket Alert