La CLI heron

La commande heron donne accès à tes mails depuis un terminal. Elle est pensée pour les agents qui passent par la ligne de commande, mais tu peux aussi l’utiliser toi-même. Elle utilise la même connexion et les mêmes outils que le serveur MCP de Heron, donc exactement les mêmes droits : niveaux par boîte et validation des envois compris.

Installer

La CLI arrive bientôt sur npm, sous le nom heronmail. Il faudra Node 20 ou plus récent :

npm i -g heronmail

Se connecter

heron login     # ouvre le navigateur : connexion Heron puis autorisation
heron status    # serveur utilisé et état de la session
heron accounts  # tes boîtes partagées avec les agents et leur niveau d'accès

heron login ouvre une page Heron dans ton navigateur : connecte-toi, choisis les accès de chaque boîte et clique sur Autoriser. La CLI apparaît ensuite dans tes agents connectés sous le nom « Heron CLI — nom de ta machine ».

Lire et chercher

heron folders --account <id>
heron list --in inbox --unread --limit 20
heron search "from:camille has:attachment after:2026-09-01"
heron read <id>                  # --max-chars N pour limiter, --html pour le HTML
heron thread <id> --no-bodies    # la conversation, sans les corps
heron attachment <message-id> <attachment-id>
heron contacts camille

La recherche accepte la même syntaxe que l’app : from:, to:, subject:, has:attachment, is:unread, is:flagged, before:, after:, in:, account:. Voir Rechercher.

Brouillons et rangement

heron reply <id> --body "Merci, c'est noté !"     # crée un brouillon de réponse (--all : répondre à tous)
heron draft --account <id> --to camille@exemple.fr --subject "Jeudi" --body-file note.txt
heron archive <id> <id> --thread
heron move <id> --to junk          # inbox, archive, junk, trash ou un dossier
heron mark-read <id>   heron flag <id>
heron snooze <id> --until tomorrow # laterToday, tonight, tomorrow, weekend, nextWeek ou une date ISO
heron undo <token>                 # annule une action (10 minutes)

Le texte d’un message peut venir de --body, de --body-file ou de l’entrée standard. La signature de la boîte est ajoutée automatiquement ; --signature NOM en choisit une autre, --signature none n’en met pas.

Envoyer

Il faut le niveau Tout, y compris l’envoi sur la boîte.

heron send --draft <draft-id>                 # envoie un brouillon
heron send --draft <draft-id> --at 2026-11-03T09:00:00+01:00   # le programme
heron pending <action-id>                     # état d'un envoi en attente de validation

Avec Confirmer avant envoi, l’envoi attend ta validation dans Heron : voir Valider les envois d’un agent.

Options utiles

• --json : sortie JSON, idéale pour les agents et les scripts.
• --server URL ou la variable HERON_SERVER : serveur à utiliser (par défaut https://api.heronmailapp.com).
• heron tools liste tous les outils ; heron call <outil> '<json>' appelle n’importe lequel.
• heron skill affiche le guide destiné aux agents.
• heron --help affiche toutes les commandes.
• Code de sortie 3 : action refusée par les droits (niveau insuffisant ou accès coupé).

Se déconnecter

heron logout

Cela révoque l’accès de la CLI et oublie ses jetons. Ceux-ci sont rangés dans le Trousseau macOS quand il est disponible, sinon dans ~/.config/heron/credentials.json, lisible par toi seul.