Utilisation et Arguments

Ce guide couvre tout, depuis les options de base jusqu’aux techniques avancées de scripting avec la CLI Apprise.

Arguments en Ligne de Commande

Vous pouvez afficher le menu d’aide complet à tout moment avec apprise --help.

Composition du Message

Flag	Option longue	Description
`-b`	`--body`	Le corps du message à envoyer. Si omis, Apprise lit depuis `stdin`.
`-t`	`--title`	Le titre du message (optionnel).
`-n`	`--notification-type`	Type de notification. Valeurs : `info`, `success`, `warning`, `failure`. Par défaut : `info`.
`-i`	`--input-format`	Format d’entrée. Valeurs : `text`, `html`, `markdown`. Par défaut : `text`.
`-e`	`--interpret-escapes`	Interpréter les séquences d’échappement dans `--body` (par exemple `\n`, `\r`).
`-j`	`--interpret-emojis`	Interpréter les shortcodes emoji dans `--body` (par exemple `:smile:`).
`-T`	`--theme`	Définir le thème par défaut.

Configuration, Filtrage et Plugins

Flag	Option longue	Description
`-c`	`--config`	Un ou plusieurs emplacements de configuration (fichier local ou URL distante).
`-g`	`--tag`	Filtrer les services à notifier (voir filtrage par tags).
`-R`	`--recursion-depth`	Nombre maximal de directives `include` récursives autorisées lors du chargement de la configuration. Par défaut : `1`. Mettez `0` pour ignorer `include`/imports.
`-P`	`--plugin-path`	Ajouter un ou plusieurs chemins à scanner pour les plugins de notification personnalisés.

Pièces Jointes

Flag	Option longue	Description
`-a`	`--attach`	Un ou plusieurs emplacements de pièces jointes (chemin de fichier local ou URL). Peut être utilisé plusieurs fois.

Stockage

Apprise prend en charge un cache de stockage persistant. Vous pouvez l’ajuster avec les options ci-dessous ou utiliser la sous-commande apprise storage.

Flag	Option longue	Description
`-S`	`--storage-path`	Chemin vers l’emplacement du cache de stockage persistant.
`-SM`	`--storage-mode`	Mode de stockage. Valeurs : `auto`, `flush`, `memory`. Par défaut : `auto`.
`-SPD`	`--storage-prune-days`	Nombre de jours utilisé pour `storage prune`. Par défaut : `30`. Mettez `0` pour supprimer tout le contenu accumulé.
`-SUL`	`--storage-uid-length`	Nombre de caractères uniques utilisés pour stocker le cache persistant. Par défaut : `8`.

Exécution et Diagnostic

Flag	Option longue	Description
`-Da`	`--disable-async`	Envoyer de manière synchrone (l’un après l’autre) plutôt qu’en parallèle.
`-d`	`--dry-run`	Exécution d’essai. Affiche quels services seraient déclenchés sur `stdout`. N’envoie aucune notification.
`-l`	`--details`	Afficher les détails des services actuellement pris en charge.
`-v`	`--verbose`	Augmenter la verbosité. Peut être empilé (par exemple `-vvvv`).
`-D`	`--debug`	Mode debug, utile pour le dépannage.
`-V`	`--version`	Afficher la version puis quitter.

Variables d’Environnement

Vous pouvez prédéfinir certains comportements via des variables d’environnement. C’est utile dans des environnements conteneurisés ou pour définir des valeurs par défaut au niveau système.

Variable	Description
`APPRISE_URLS`	URL de service par défaut à notifier si aucune n’est fournie sur la ligne de commande. Séparées par des espaces et/ou des virgules. Si `--config` est spécifié, cela écrase `APPRISE_URLS`.
`APPRISE_CONFIG_PATH`	Remplacer les chemins de recherche de configuration par défaut. Utilisez `;`, `\n` et/ou `\r` pour séparer plusieurs entrées.
`APPRISE_PLUGIN_PATH`	Remplacer les chemins de recherche de plugins par défaut. Utilisez `;`, `\n` et/ou `\r` pour séparer plusieurs entrées.
`APPRISE_STORAGE_PATH`	Remplacer le chemin par défaut du stockage persistant.

Emplacements de Configuration par Défaut

Si vous ne spécifiez pas de fichier de configuration via la CLI (--config), Apprise charge automatiquement un fichier de configuration par défaut.

Linux/BSD/Apple
Microsoft Windows

Les fichiers de configuration suivants sont recherchés dans l’ordre indiqué ci-dessous ; la première correspondance est chargée et aucune recherche supplémentaire n’est effectuée.

~/.apprise
~/.apprise.conf
~/.apprise.yml
~/.apprise.yaml
~/.config/apprise
~/.config/apprise.conf
~/.config/apprise.yml
~/.config/apprise.yaml
~/.apprise/apprise
~/.apprise/apprise.conf
~/.apprise/apprise.yml
~/.apprise/apprise.yaml
~/.config/apprise/apprise
~/.config/apprise/apprise.conf
~/.config/apprise/apprise.yml
~/.config/apprise/apprise.yaml

Les chemins globaux suivants sont également recherchés si rien n’est trouvé ci-dessus :

/etc/apprise
/etc/apprise.yml
/etc/apprise.yaml
/etc/apprise/apprise
/etc/apprise/apprise.conf
/etc/apprise/apprise.yml
/etc/apprise/apprise.yaml

Les fichiers de configuration suivants sont recherchés dans l’ordre indiqué ci-dessous ; la première correspondance est chargée et aucune recherche supplémentaire n’est effectuée.

%APPDATA%\Apprise\apprise
%APPDATA%\Apprise\apprise.conf
%APPDATA%\Apprise\apprise.yml
%APPDATA%\Apprise\apprise.yaml
%LOCALAPPDATA%\Apprise\apprise
%LOCALAPPDATA%\Apprise\apprise.conf
%LOCALAPPDATA%\Apprise\apprise.yml
%LOCALAPPDATA%\Apprise\apprise.yaml

Les chemins globaux suivants sont également recherchés si rien n’est trouvé ci-dessus :

%ALLUSERSPROFILE%\Apprise\apprise
%ALLUSERSPROFILE%\Apprise\apprise.conf
%ALLUSERSPROFILE%\Apprise\apprise.yml
%ALLUSERSPROFILE%\Apprise\apprise.yaml
%PROGRAMFILES%\Apprise\apprise
%PROGRAMFILES%\Apprise\apprise.conf
%PROGRAMFILES%\Apprise\apprise.yml
%PROGRAMFILES%\Apprise\apprise.yaml
%COMMONPROGRAMFILES%\Apprise\apprise
%COMMONPROGRAMFILES%\Apprise\apprise.conf
%COMMONPROGRAMFILES%\Apprise\apprise.yml
%COMMONPROGRAMFILES%\Apprise\apprise.yaml

En supposant que l’utilisateur soit foobar et que Microsoft Windows soit installé sur le lecteur C:\, les variables ci-dessus peuvent être interprétées ainsi :

Variable d’environnement	Exemple de traduction
`%APPDATA%`	`C:\Users\foobar\AppData\Roaming`
`%LOCALAPPDATA%`	`C:\Users\foobar\AppData\Local`
`%ALLUSERSPROFILE%`	`C:\ProgramData`
`%PROGRAMFILES%`	`C:\Program Files`
`%COMMONPROGRAMFILES`	`C:\Program Files\Common Files`

Pièces Jointes Fichier

Vous pouvez envoyer des fichiers avec vos notifications via l’option --attach (-a). Apprise gère automatiquement la logique d’upload pour les services qui prennent cela en charge (comme Discord, Slack et Telegram).

Fichiers Locaux

Envoyer un fichier log ou une image depuis votre disque local.

apprise \
  --title "System Log" \
  --body "See attached log for details" \
  --attach "/var/log/syslog" \
  "discord://webhook_id/webhook_token"

Pièces Jointes Distantes

Apprise peut récupérer un fichier depuis une URL puis le transmettre comme pièce jointe.

# Apprise télécharge l'image puis l'envoie à Telegram
apprise \
  --title "Front Door" \
  --body "Motion detected" \
  --attach "http://camera-ip/snapshot.jpg" \
  "tgram://bot_token/chat_id"

Pièces Jointes Multiples

Vous pouvez spécifier l’option plusieurs fois pour envoyer plusieurs fichiers à la fois.

apprise \
  --body "Here are the build artifacts" \
  --attach "release-notes.txt" \
  --attach "build.zip" \
  "slack://tokenA/tokenB/tokenC"

Tags et Filtrage

Apprise vous permet de cibler des sous-ensembles spécifiques de votre configuration grâce aux tags.

Règles de Logique

Utilisez --tag (-g) pour spécifier un ou plusieurs tags et filtrer les services à notifier :

-g "tagA" -g "tagB" : correspond à tagA OU tagB (union).
-g "tagA,tagB" : correspond à tagA ET tagB (strict).
-g "all" : notifie TOUS les services (tagués et non tagués).
(omis) : notifie uniquement les services non tagués.

Une autre manière de voir les choses :

Logique OU : pour notifier des services qui possèdent soit Tag A OU Tag B, utilisez l’option --tag plusieurs fois.
Logique ET : pour notifier des services qui possèdent à la fois Tag A ET Tag B, séparez les tags par une virgule dans une seule option.

Filtrage par Priorité

Les tags définis dans votre configuration peuvent porter un préfixe numérique de priorité (par exemple 1:alerts ou 5:alerts dans un fichier YAML). Deux modes sont disponibles selon que vous incluez ou non une priorité dans votre valeur --tag.

Sans préfixe de priorité — mode escalade (par défaut)

Lorsque vous passez un nom de tag simple, Apprise envoie les notifications en ordre de priorité croissante. Si tous les services du groupe de priorité la plus basse réussissent, Apprise retourne immédiatement et ignore tous les groupes de priorité supérieure. En cas d’échec d’un service de ce groupe, Apprise passe au groupe suivant.

-g "alerts" : envoie d’abord aux entrées de priorité 1. Si elles réussissent toutes, ignore la priorité 5 (et les suivantes). En cas d’échec, déclenche les entrées de priorité 5 en repli.

Avec un préfixe de priorité — mode exclusif

Lorsque vous incluez un préfixe numérique, Apprise cible uniquement les services dont le tag alerts porte cette priorité exacte. Aucun autre niveau de priorité n’est déclenché.

-g "2:alerts" : déclenche uniquement les entrées alerts assignées à la priorité 2.

Remplacement du Nombre de Tentatives par Appel

Une valeur de tag peut également porter un nombre de tentatives en suffixe (:N) qui remplace le nombre de tentatives configuré pour chaque service correspondant, uniquement pour cet appel :

-g "alerts:3" : notifie tous les services alerts en réessayant chacun jusqu’à 3 fois en cas d’échec.
-g "2:alerts:3" : notifie uniquement les services alerts de priorité 2, avec jusqu’à 3 tentatives.

Le nombre de tentatives ne modifie pas la configuration permanente du service ; il s’applique uniquement à l’invocation en cours.

Exemples

# Notifier les services tagués 'devops' OU 'admin'
apprise -t "Union Test" --config apprise.yml \
   --tag devops --tag admin

# Notifier les services tagués à la fois 'devops' ET 'critical'
apprise -t "Intersection Test" --config apprise.yml \
   --tag "devops,critical"

# Notifier uniquement les services 'alerts' de priorité 2
apprise -t "High Alert" --config apprise.yml \
   --tag "2:alerts"

# Notifier tous les services 'alerts' avec jusqu'à 3 tentatives en cas d'échec
apprise -t "Critical Event" --config apprise.yml \
   --tag "alerts:3"

# Notifier uniquement les services 'alerts' de priorité 2 avec jusqu'à 3 tentatives
apprise -t "Critical Event" --config apprise.yml \
   --tag "2:alerts:3"

# Déclencher une configuration stockée sous la clé 'my-alerts' sur un serveur
# Apprise API local en utilisant la clé 'my-alerts'
apprise -t "Job Finished" \
    "apprise://localhost:8000/my-alerts"

# Déclencher une instance distante sécurisée, en ciblant seulement le tag 'devops'
apprise -t "Production Issue" \
    --tag devops \
    "apprises://apprise.example.com/234-3242-23-2111-34"

Formatage et Emojis

Formats d’Entrée

Par défaut, Apprise traite le corps comme du texte brut. Vous pouvez modifier cela avec --input-format.

# Envoyer un message formaté en Markdown
apprise -t "Build Status" -b "**Success**: The build passed!" \
    --input-format markdown \
    "discord://..."

Prise en Charge des Emojis

Utilisez --interpret-emojis (-j) pour convertir les shortcodes emoji en vrais emojis.

apprise \
  --title "Server Status" \
  --body "The server is on :fire:. Please send help :ambulance:." \
  --interpret-emojis \
  "slack://..."

Séquences d’Échappement

Utilisez --interpret-escapes (-e) si vous voulez que les séquences \n dans votre corps deviennent de vrais retours à la ligne.

apprise \
  --title "Multi-line" \
  --body "Line 1\\nLine 2\\nLine 3" \
  --interpret-escapes \
  "discord://..."

Utiliser Apprise API

Si vous exécutez une instance auto-hébergée de Apprise API, vous pouvez utiliser la CLI pour la déclencher avec le schéma apprise://. Cela vous permet de centraliser votre configuration côté serveur et de garder vos clients locaux très simples.

Syntaxe

Non sécurisé (HTTP) : apprise://hostname/config_key
Sécurisé (HTTPS) : apprises://hostname/config_key

Exemples :

# Déclencher une configuration stockée sous la clé 'my-alerts' sur un serveur local
apprise -t "Job Finished" \
    "apprise://localhost:8000/my-alerts"

# Déclencher une instance distante sécurisée, en ciblant seulement le tag 'devops'
apprise -t "Production Issue" \
    --tag devops \
    "apprises://apprise.example.com/production-key"

Scripting et Pipes

La CLI est conçue pour s’intégrer proprement aux pipes et scripts système standard.

Entrée Multiligne

Si vous omettez --body, Apprise lit depuis stdin.

cat << '_EOF' | apprise --title "Database Status" \
    --notification-type success "discord://..."
Backup started: 10:00 AM
Backup finished: 10:05 AM
Status: SUCCESS
_EOF

Piping depuis des Fichiers

Rediriger directement le contenu d’un fichier dans le corps du message.

cat ~/notes.txt | apprise --title "Daily Notes" \
   "mailto://user:pass@example.com"

Utiliser des Variables

Si vous avez une variable multiligne dans votre script, entourez-la de guillemets pour préserver les sauts de ligne.

MULTILINE_VAR="""
This variable has been defined
with multiple lines in it.
"""

apprise --title "Variable Example" \
   --body "$MULTILINE_VAR" \
   "gotify://localhost"

Stockage Persistant

Le stockage persistant est écrit à l’emplacement suivant par défaut, sauf si APPRISE_STORAGE_PATH ou --storage-path le surcharge :

~/.local/share/apprise/cache

Apprise peut mettre en cache sur disque certaines recherches et informations d’authentification afin de réduire les appels API répétés. Cela est activé par défaut pour la CLI (mode auto).

Pour interagir avec le stockage, utilisez la sous-commande storage :

apprise storage

Pour l’explication complète (UID, emplacements de cache, captures d’écran et workflows de nettoyage), consultez Stockage Persistant.

Code de Sortie

La CLI Apprise quitte avec :

0 si toutes les notifications ont été envoyées avec succès.
1 si une ou plusieurs notifications n’ont pas pu être envoyées.
2 s’il y a eu une erreur de ligne de commande (par exemple des arguments invalides).
3 si une ou plusieurs URL de service ont été chargées avec succès, mais qu’aucune n’a pu être notifiée à cause du filtrage utilisateur (tags).

Intégrations

Tmux Alert Bell

Vous pouvez relier le hook tmux alert-bell à Apprise pour recevoir des notifications lorsque de longues commandes se terminent.

# 1. Définir bell-action sur 'other' dans tmux
set-option -g bell-action other

# 2. Déclencher Apprise sur 'alert-bell'
set-hook -g alert-bell 'run-shell "\
  apprise \
    --title \"Tmux notification on #{host}\" \
    --body \"Session #{session_name} window #{window_index}:#{window_name}\" \
    --notification-type info \
    discord://webhook_id/webhook_token"'

Questions ou commentaires ?

Documentation

Vous avez repéré une faute de frappe ou une erreur ? Signalez-la ou proposez une correction .

Problèmes Techniques

Vous rencontrez un problème avec le code ? Ouvrez un ticket sur GitHub :