> ## Documentation Index > Fetch the complete documentation index at: https://docs.oximail.ch/llms.txt > Use this file to discover all available pages before exploring further. # Administration assistée par agent > Ce sur quoi un script, une ronde de supervision ou un agent conversationnel peut compter quand il pilote une box OxiMail par sa ligne de commande : sorties JSON contractuelles, codes de sortie, essais à blanc, confirmations uniformes, diagnostics serveur arrêté. Toute l'exploitation d'une box OxiMail passe par un seul binaire, `oximail`, et sa surface de commandes tient quelques promesses. Chaque verbe qu'une machine lit parle JSON. Chaque code de sortie veut dire la même chose partout. Chaque écriture est montrée avant d'être faite. Les diagnostics marchent quand le serveur est arrêté. Ce sont exactement les propriétés qu'exige un opérateur automatique : un script en cron, une ronde de supervision nocturne, ou un agent d'IA qui exploite la box pour son administrateur et lui rend compte. Aucune n'a été conçue pour l'IA. Elles existent parce que l'exploitation les exigeait, et un test de la CI du serveur échoue quand un nouveau verbe en casse une. C'est pour cela qu'on peut bâtir dessus. Cette page est le contrat de qui écrit cette automatisation. La [référence de la CLI](./cli) dresse la carte des verbes ; `oximail --help` reste l'autorité sur les options. ## Le contrat | Garantie | Ce que ça veut dire pour un automate | | - | - | | **`--json` est un contrat de supervision** | Une fois qu'un verbe émet du JSON, ses champs ne font que s'ajouter. Un script écrit aujourd'hui lit encore la sortie de demain. Lisez le JSON, jamais le texte destiné aux humains, qui ne promet aucune stabilité. | | **Les codes de sortie ont un sens** | `0` tout va bien, `1` dégradé (la commande a fait son travail et quelque chose est rouge, par exemple un enregistrement DNS à créer), `2` ou plus : la commande n'a pas pu conclure. Un `1` est une réponse, pas une panne : une ronde décide sans lire le texte. | | **Un mutateur ponctuel fait un essai à blanc par défaut** | Il affiche ce qu'il ferait et ne touche à rien avant `--apply`. L'automate *montre* le changement, un humain le lit, puis on l'applique. | | **Un verbe destructeur exige son drapeau de confirmation** | `--yes` pour un objet, `--force` pour passer outre une cardinalité, `--apply` pour un balayage. C'est la même grammaire partout : l'automate a besoin d'un seul garde-fou, pas d'un par verbe. | | **Les diagnostics marchent serveur arrêté** | Ils lisent directement la base : on s'en sert *pendant* l'incident, là où ils comptent le plus. | | **Une façade, jamais un moteur** | Un verbe passe par les mêmes méthodes du magasin et les mêmes validations que l'API JMAP. Une écriture en CLI ne contourne aucune validation, et un automate qui se trompe est arrêté par les mêmes contrôles qu'un humain dans l'interface. | | **Jamais d'échec silencieux** | Une erreur remonte, en texte et en code de sortie. C'est la condition de toute délégation. | ## Par où commencer Trois commandes donnent l'état d'une box, dans cet ordre : ```bash theme={null} oximail doctor --json oximail status --json oximail schema check --json ``` * `doctor` est le contrôle d'ensemble : configuration, base, file d'attente, DNS, DKIM, certificat, DANE, plan de sauvegarde, séquestre de la clé, âge du dernier exercice de restauration. Lisez chaque `status` : `ok`, `warn`, `fail` et `skipped`. `skipped` veut dire que rien n'a été mesuré, ce qui n'est jamais un succès. Chaque entrée porte aussi sa `family`, ses `facts` datés (`observedAt`, `expiresAt`) et, sur un `warn` ou un `fail`, le `remedy` : le verbe à proposer, tel qu'il se tape ([la ronde doctor](./operations#la-ronde-doctor)). * `status` compte les comptes, les messages, la file d'attente, les bannissements et le stockage. * `schema check` dit si le binaire accepte la base présente sur le disque (`accepts`, `newer` ou `error`). Lisez-le avant un déploiement ou un retour arrière. ## Le mode d'emploi est livré avec le binaire ```bash theme={null} oximail skill show ``` La commande affiche le mode d'emploi destiné à un agent : l'ordre des gestes, le contrat ci-dessus et ce qu'il ne faut jamais faire. C'est le binaire lui-même qui l'affiche : le mode d'emploi correspond donc toujours à la version installée. Il n'y a rien à télécharger, et aucune copie ne vieillit. Un agent qui se connecte à une box par ssh peut commencer par là. ## La délégation laisse un humain aux commandes L'automate propose, un humain applique. L'essai à blanc et les drapeaux de confirmation existent pour que la personne responsable lise ce qui va s'écrire avant que ce soit écrit. Sur une box qui sert des gens, montrez l'essai à blanc avant de lancer `--apply`. **Le journal dit qui a décidé.** Un processus qui lance les verbes pour un agent le déclare dans l'environnement de chaque verbe qu'il démarre : `OXIMAIL_CLI_CHANNEL=agent` et `OXIMAIL_CLI_DECIDED_BY=`. Les actes d'administration de ce verbe sont alors journalisés en `cli-agent` au nom de cette personne, jamais comme une commande qu'elle aurait tapée, et jamais au nom de l'agent : l'agent ne décide rien. Toute autre valeur de canal, `agent` sans nom, ou un nom sans `agent` est refusé. ## Les limites, dites d'emblée * **Le contrat engage les verbes créés après lui.** Quelques anciens verbes de migration ponctuelle (`backfill-*` et leur famille) s'exécutent par défaut et prennent `--dry-run`. Leur défaut n'est pas inversé : changer un défaut déjà livré change en silence ce que fait un script. Leur `--help` le dit. * **Les verbes de lecture parlent JSON ; un verbe qui produit un fichier, non.** `print-systemd-unit` affiche une unité systemd, du texte par nature. `--help` montre si un verbe prend `--json`. * **Une question se règle par une option, jamais par une invite sur un tube.** `oximail setup --config-file` refuse, en la nommant, une question que son fichier ne règle pas. `oximail setup dns` tourne sans terminal et accepte `--replace-mx`, `--replace-spf`, `--replace-dmarc` et `--public-ipv4` : une question de remplacement laissée ouverte garde l'enregistrement existant et se termine en sortie 1, une IPv4 publique non tranchée arrête l'exécution avant toute publication, en sortie 2 ([sous-commandes de setup](../first-boot#sous-commandes-de-setup-individuelles)). * **Le texte pour les humains n'est pas un contrat.** Les messages deviennent plus clairs d'une version à l'autre. Seuls la sortie JSON et les codes de sortie sont stables. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.