Comment utiliser l'Apidog CLI dans Hermes Agent

Hermes Agent s'exécute depuis votre terminal, se souvient de ce qu'il apprend d'une session à l'autre, et utilise de vraies commandes shell pour accomplir des tâches. Cette dernière partie est l'ouverture : s'il peut exécuter une commande, il peut exécuter vos tests d'API.

L'exécuteur qui les connecte est l'Apidog CLI, un package npm nommé apidog-cli. Il exécute les scénarios de test que vous avez construits visuellement dans Apidog directement depuis un terminal et se termine avec un code d'état sur lequel Hermes peut agir. Ce guide couvre la moitié spécifique à Hermes : l'outil terminal qui exécute la commande, le fichier de contexte qui enseigne votre flux de travail à Hermes, comment l'exécution s'intègre dans sa boucle, et le serveur Apidog MCP optionnel qui fournit à Hermes votre spécification d'API pendant qu'il travaille.

Si l'CLI n'est pas encore installé, commencez par comment installer l'Apidog CLI avec un agent de codage IA, qui guide un agent à travers l'installation et l'authentification. Revenez une fois que apidog --version affiche un nombre. Vous avez également besoin d'un compte Apidog avec au moins un scénario de test enregistré ; téléchargez Apidog si vous n'en avez pas.

bouton

Ce que signifie « utiliser l'CLI dans Hermes »

Hermes Agent, développé par Nous Research, s'exécute dans votre terminal, communique avec vos modèles d'IA et agit via des outils intégrés. Celui qui nous intéresse ici est l'outil terminal : Hermes exécute des commandes shell en l'appelant dans votre répertoire de travail, puis réintègre la sortie dans son raisonnement. Il n'y a pas de plugin Apidog à installer, et vous n'en avez pas besoin. Utiliser l'Apidog CLI dans Hermes signifie trois choses :

Enseigner le flux de travail à Hermes une seule fois en l'écrivant dans un fichier de contexte que Hermes charge au démarrage, afin qu'il connaisse la commande, les options et que le code de sortie soit la source de vérité.
Faire exécuter apidog run par Hermes via l'outil terminal, comme toute autre commande.
Connecter optionnellement le serveur Apidog MCP, afin que Hermes puisse lire votre spécification d'API pendant qu'il écrit le code que ces tests vérifient.

Le fichier de contexte est ce qui rend ce processus spécifique à Hermes plutôt qu'un guide générique « ouvrir un terminal et taper », transformant un « exécuter mes tests » ponctuel en quelque chose qu'il recherche de lui-même.

Le mécanisme : un fichier de contexte, pas un rappel de chat

Hermes charge le contexte du projet au début d'une session. Son moteur de contexte scanne votre répertoire de travail à la recherche de fichiers d'instructions, y compris CLAUDE.md et AGENTS.md, et les injecte dans l'invite système. C'est la même convention qu'utilisent Claude Code et Codex, donc si votre dépôt a déjà un AGENTS.md, Hermes le lira également.

C'est pourquoi vous écrivez l'CLI dans un fichier de contexte au lieu de le mentionner dans le chat. Un ID de scénario tapé dans une session disparaît à la fin de celle-ci ; un ID dans AGENTS.md est là pour chaque membre de l'équipe et chaque exécution Hermes à partir de maintenant. (Hermes lit également un SOUL.md, mais cela concerne la persona de l'agent, pas votre projet. Gardez les instructions de test dans AGENTS.md.)

Étape 1 : Ajouter un bloc Apidog à votre fichier de contexte

Ouvrez AGENTS.md à la racine de votre dépôt, ou créez-le, et ajoutez une section indiquant à Hermes l'existence de l'CLI, comment l'exécuter et comment lire le résultat. Donnez-lui la commande et l'ID réels, pas une description.

## Test d'API avec l'Apidog CLI

Ce dépôt utilise l'Apidog CLI (`apidog-cli`, la commande `apidog`) pour exécuter des
scénarios de test d'API. Les scénarios vivent dans notre projet Apidog, et non dans ce dépôt.

Lorsque vous modifiez un gestionnaire d'API, une route ou la forme d'une réponse, exécutez le
scénario Apidog pertinent via l'outil terminal avant de considérer la modification terminée :

    apidog run -t 605067 -e 1629989 -n 1 -r cli

- `-t 605067` est le scénario de test du flux de paiement.
- `-e 1629989` est l'environnement de staging.
- La machine est déjà authentifiée via `apidog login`, donc NE PAS passer
  de jeton d'accès et NE PAS en afficher.

Considérez le code de sortie comme la source de vérité : `0` signifie que toutes les assertions sont passées,
non-nul signifie un échec. S'il sort non-nul, lisez l'assertion défaillante dans
le rapport et corrigez le code, puis réexécutez. Ne signalez pas de succès en cas de
sortie non-nulle.

Remplacez 605067 par votre véritable ID de scénario et 1629989 par l'environnement que Hermes doit utiliser pendant le travail normal, généralement le staging ou le développement local, jamais la production. Pour obtenir les bons ID, copiez la commande apidog run qu'Apidog génère dans l'onglet CI/CD du scénario (couvert ci-après), et supprimez le jeton d'accès avant de la coller, car la machine est déjà connectée et un jeton ne doit pas figurer dans un fichier versionné.

Deux choses font fonctionner ce bloc. Il nomme la commande exactement, de sorte que Hermes ne devine pas les options. Et il énonce la règle de réussite/échec en langage clair, afin que Hermes sache que le code de sortie prime sur son propre résumé, ce qui vous évite l'échec d'agent le plus courant : un « tests passés » confiant sur une exécution rouge.

Étape 2 : Obtenir la commande d'Apidog

Obtenez une commande fonctionnelle avant de demander à Hermes d'exécuter quoi que ce soit. Ouvrez votre scénario dans Apidog, passez à son onglet CI/CD et choisissez l'option de ligne de commande. Apidog construit la commande apidog run complète avec les ID et un jeton d'accès déjà renseignés :

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli

605067 est l'ID du scénario et 1629989 est l'ID de l'environnement ; les vôtres seront différents. Puisque vous avez authentifié l'CLI lors de l'installation, supprimez la partie --access-token et conservez les ID. C'est la commande que votre fichier de contexte a dit à Hermes d'utiliser.

Étape 3 : Faire exécuter le test par Hermes

Démarrez Hermes dans votre dépôt, puis demandez-lui d'exécuter la vérification. Avec le bloc en place, l'invite est courte :

Exécutez notre scénario de test d'API Apidog tel que décrit dans AGENTS.md. Je suis déjà authentifié, donc ne passez pas de jeton d'accès. Utilisez apidog run -t 605067 -e 1629989 -n 1 -r cli. Montrez-moi la sortie complète et dites-moi le code de sortie.

Hermes appelle son outil terminal pour exécuter la commande dans votre répertoire de travail, et le rapporteur -r cli diffuse un résultat étape par étape dans son contexte, où vous observez chaque requête et assertion. Parce que Hermes achemine les commandes via une couche d'approbation, vous pourriez voir une invite avant qu'il ne s'exécute, selon votre configuration. Un scénario de test en lecture seule contre le staging est exactement le genre de commande sûre et interne à l'espace de travail qu'il est acceptable d'autoriser.

Votre vérification : examinez le code de sortie, pas le résumé. apidog run se termine avec 0 lorsque toutes les assertions passent et avec une valeur non nulle lorsqu'une échoue. Ce comportement est la raison principale pour laquelle cela fonctionne comme un garde-fou, pour le CI et pour Hermes. Si Hermes dit « tests passés » mais que le code de sortie était non nul, c'est faux ; faites confiance au code. C'est l'échec que le bloc de l'Étape 1 prévient.

Pour un format de rapport différent ou plus d'itérations, demandez à Hermes d'exécuter apidog run --help afin qu'il lise la liste réelle des options. Le guide complet de l'Apidog CLI documente toutes les options, y compris les rapporteurs html, json et junit.

Étape 4 : Hermes teste au sein de sa propre boucle

L'intérêt est ce qui se passe lorsque vous arrêtez de demander et que Hermes exécute le scénario de lui-même parce que AGENTS.md le lui a dit. Imaginez-le en train de modifier un gestionnaire qui construit une réponse de commande : il modifie le code, exécute votre scénario Apidog contre le staging via l'outil terminal, lit le code de sortie et agit en conséquence. Vert, il passe à autre chose. Rouge, il ouvre le rapport, lit quelle assertion a échoué (le code de statut, le champ manquant, la mauvaise valeur), tente une correction et réexécute. Le test d'API fait partie de la même boucle d'édition-test-correction qu'il utilise déjà pour vos tests unitaires. Vous avez écrit une instruction et il a intégré la commande à son fonctionnement habituel.

C'est le modèle de délégation puis de vérification qui rend tout flux de travail d'agent sûr. Hermes exécute la commande et lit le résultat ; vous continuez à créer des scénarios dans Apidog et vérifiez ponctuellement qu'il lit honnêtement les codes de sortie. Pour une exécution lente, un grand dossier ou un nombre élevé d'itérations, l'outil terminal accepte une option background=true, de sorte que Hermes peut lancer le balayage, continuer à travailler et interroger le code de sortie au lieu de bloquer. Pour le modèle plus large, voir comment utiliser les agents IA pour les tests d'API et le harnais de test IA Apidog.

Facultatif : connecter le serveur Apidog MCP

L'CLI permet à Hermes d'exécuter vos tests ; le serveur Apidog MCP lui permet de lire votre spécification d'API pendant qu'il écrit du code. Les deux s'empilent : MCP fournit votre schéma à Hermes afin qu'il génère du code correspondant au contrat, et l'CLI vérifie ce code par rapport à des scénarios réels.

Hermes prend en charge le protocole de contexte de modèle (MCP) de manière native. Modifiez ~/.hermes/config.yaml et ajoutez une entrée sous la section mcp_servers. Pour un serveur stdio local comme celui d'Apidog, cela comprend une command, un tableau d'args et toutes les valeurs d'env :

mcp_servers:
  apidog:
    command: "npx"
    args: ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"]
    env:
      APIDOG_ACCESS_TOKEN: "YOUR_ACCESS_TOKEN"

Après avoir enregistré, exécutez /reload-mcp à l'intérieur de Hermes, ou redémarrez-le. Hermes découvre les serveurs MCP au démarrage et enregistre leurs outils dans son registre normal, avec l'espace de noms mcp_apidog_<outil>, afin que l'agent puisse les utiliser lors de son raisonnement normal. Pour la configuration complète, y compris l'ID de projet et le jeton, consultez le guide du serveur Apidog MCP. Pour une version packagée de cette boucle, consultez le guide Apidog CLI avec Claude Skills.

De la boucle locale au CI

Une fois que Hermes a exécuté le scénario localement et agi sur le code de sortie, vous avez validé la commande exacte que votre pipeline utilisera. Le passage au CI est simple : le même apidog run, avec le jeton passé comme un secret masqué au lieu d'une connexion stockée. Demandez à Hermes d'écrire l'étape, puisqu'il connaît la commande à partir de votre fichier de contexte :

Écrivez une étape GitHub Actions qui installe apidog-cli et exécute apidog run -t 605067 -e 1629989 -r junit, en lisant le jeton d'accès à partir d'un secret de dépôt nommé APIDOG_ACCESS_TOKEN.

La mécanique de cette étape (secrets, rapporteurs, gestion du code de sortie) se trouve dans Apidog CLI dans GitHub Actions. La même commande s'exécute alors à trois endroits : votre terminal, la boucle de Hermes et le CI, le tout sur un seul code de sortie.

Pièges courants

Hermes ignore le bloc de contexte. S'il exécute une commande générique ou aucune, confirmez que le fichier est nommé exactement AGENTS.md (ou CLAUDE.md) et qu'il se trouve dans le répertoire où Hermes a démarré. Redémarrer la session force une nouvelle lecture.

Il ne suggère la commande qu'au lieu de l'exécuter. Hermes exécute les commandes via l'outil terminal derrière une couche d'approbation. Approuvez une exécution en attente ; si votre configuration refuse les commandes terminal, assouplissez la permission pour apidog run.

apidog whoami indique que vous n'êtes pas authentifié. La connexion est stockée sur votre machine, pas dans Hermes. Exécutez vous-même apidog login --with-token avec un nouveau jeton, puis demandez à Hermes de confirmer avec apidog whoami. Gardez le jeton hors du chat.

Il invente une option. Une erreur « option inconnue » signifie que Hermes a deviné une option qui n'existe pas dans votre version. Demandez-lui d'exécuter apidog run --help et copiez la véritable option.

Il rapporte un succès sur une exécution échouée. Le plus coûteux, et la raison pour laquelle la règle du code de sortie est à la fois dans votre AGENTS.md et dans votre vérification manuelle. Lorsque le résumé et le code de sortie ne concordent pas, le code l'emporte.

En résumé

La configuration de Hermes se résume à un fichier et une habitude : un bloc AGENTS.md qui fixe la commande, la source d'authentification et la règle du code de sortie, plus l'habitude de laisser Hermes exécuter apidog run via son outil terminal et de vérifier vous-même le code de sortie. Ajoutez le serveur Apidog MCP via ~/.hermes/config.yaml et il pourra également lire votre spécification pendant qu'il code.

Vous continuez à créer des scénarios visuellement dans Apidog ; Hermes ne fait que les exécuter. À partir de là, pointez la même commande vers votre pipeline avec Apidog CLI dans GitHub Actions, ou lisez la référence complète des options dans le guide complet.

Questions fréquemment posées

Ai-je besoin d'un plugin Hermes pour utiliser l'Apidog CLI ?

Non. Hermes exécute des commandes shell via son outil terminal, il appelle donc apidog run directement. La seule configuration spécifique à Hermes est le bloc AGENTS.md, plus le serveur MCP optionnel.

Où dois-je placer les instructions qui enseignent le flux de travail à Hermes ?

Dans un fichier de contexte que Hermes charge au démarrage. Son moteur de contexte scanne le répertoire de travail à la recherche de fichiers comme AGENTS.md et CLAUDE.md et les injecte dans l'invite système. Placez votre bloc Apidog dans AGENTS.md à la racine du dépôt et chaque session dans ce dépôt le lira.

Comment m'assurer que Hermes ne simule pas un test réussi ?

Faites-lui rapporter le code de sortie, pas seulement un résumé, et vérifiez ce code vous-même. apidog run se termine avec 0 uniquement lorsque toutes les assertions sont passées. Lorsque le texte et le code ne concordent pas, faites confiance au code.

Comment connecter le serveur Apidog MCP à Hermes ?

Ajoutez une entrée mcp_servers à ~/.hermes/config.yaml avec la commande apidog-mcp-server et votre ID de projet, puis exécutez /reload-mcp ou redémarrez Hermes. Il découvre le serveur au démarrage et enregistre ses outils. Le guide du serveur Apidog MCP couvre l'ID de projet et le jeton.

Cela fonctionne-t-il de la même manière avec d'autres agents de codage IA ?

L'CLI est le même partout ; seule la manière d'enseigner l'agent diffère. Hermes lit AGENTS.md et exécute les commandes via son outil terminal ; d'autres agents utilisent leurs propres fichiers d'instructions. L'installation et l'authentification sont identiques, donc le guide d'installation s'applique à tout agent.