Comment utiliser la CLI Apidog avec Claude Code

Claude Code fonctionne en boucle : il modifie des fichiers, exécute des commandes dans votre terminal, lit leur sortie et décide quoi faire ensuite. Vos tests d’API doivent donc faire partie de cette boucle, au lieu de rester dans une interface graphique qu’un humain doit lancer manuellement.

Essayez Apidog dès aujourd’hui

La solution tient dans un bloc de configuration. La CLI Apidog, distribuée via le package npm apidog-cli, exécute depuis le terminal les scénarios de test créés dans Apidog. Une fois la CLI installée et déclarée dans les règles de Claude Code, l’agent peut lancer un scénario Apidog comme il lancerait vos tests unitaires : exécuter la commande, lire le code de sortie et corriger le code si le test échoue.

Ce guide se concentre sur l’intégration avec Claude Code : le contenu à ajouter dans CLAUDE.md, la gestion des permissions pour apidog run et l’exploitation des résultats dans une boucle édition-test-correction.

Si la CLI n’est pas encore installée, commencez par là : installer la CLI Apidog avec un agent de codage IA. Ce guide suppose que la commande suivante renvoie un numéro de version et que votre compte Apidog est authentifié :

apidog --version

De quel Claude Code s’agit-il ?

Il s’agit de la CLI Claude Code d’Anthropic, exécutée dans un terminal ou dans l’application de bureau. Elle lit votre dépôt, modifie des fichiers et exécute des commandes shell selon votre mode de permission.

Ce n’est ni l’application de chat Claude, ni un simple appel d’API. Si vous lancez claude dans un dépôt et obtenez un agent interactif qui propose des modifications et l’exécution de commandes, vous utilisez le bon outil.

Les instructions de terminal peuvent être placées dans vos commandes slash Claude Code, mais les règles persistantes du projet doivent être placées dans CLAUDE.md.

CLAUDE.md transforme une demande ponctuelle — « exécute mes tests » — en règle disponible à chaque session.

Étape 1 : ajouter le bloc Apidog à CLAUDE.md

Claude Code lit les fichiers CLAUDE.md au début de chaque session. C’est l’équivalent de AGENTS.md pour Codex. La documentation Anthropic précise que Claude Code lit CLAUDE.md, et non AGENTS.md. Si vous maintenez déjà un AGENTS.md, vous pouvez l’importer avec @AGENTS.md.

Si vous avez déjà configuré la CLI Apidog dans Codex, le principe est identique : seul le nom du fichier change.

Créez un fichier CLAUDE.md à la racine du dépôt. Claude Code accepte aussi :

• ./.claude/CLAUDE.md
• ~/.claude/CLAUDE.md pour les préférences globales personnelles

Claude Code remonte l’arborescence depuis le répertoire où vous l’avez lancé et charge chaque fichier CLAUDE.md trouvé. Un fichier à la racine du dépôt s’applique donc à toutes les sessions du projet.

Ajoutez un bloc court et explicite :

## Tests d'API avec la CLI Apidog

Ce projet contient des scénarios de test Apidog. Pour vérifier l'API, exécutez :

`apidog run -t <scenario_id> -e <env_id> -r cli`

- Un code de sortie 0 signifie que toutes les assertions sont passées. Non-zéro signifie qu'un problème est survenu ; ouvrez le rapport et corrigez-le avant de continuer.
- La machine est déjà authentifiée via `apidog login`. N'ajoutez jamais d'option `--access-token` et ne mettez jamais de jeton dans ce fichier.
- Si une option est inconnue, exécutez `apidog run --help` et utilisez l'option exacte qui s'y trouve.

Remplacez <scenario_id> et <env_id> par les identifiants réels de votre scénario et de votre environnement.

Pourquoi l’ajouter à CLAUDE.md plutôt que de le demander dans le chat ?

• Une instruction saisie dans une conversation disparaît à la fin de la session.
• Une instruction dans CLAUDE.md est disponible pour tous les membres de l’équipe.
• Le fichier est rechargé à chaque démarrage.
• L’instruction reste disponible même après /compact.

Étape 2 : récupérer la commande depuis Apidog

Ne devinez pas les valeurs de <scenario_id> et <env_id>.

1. Ouvrez votre scénario de test dans Apidog.
2. Accédez à l’onglet CI/CD.
3. Copiez la commande apidog run ... générée.
4. Collez les identifiants réels dans votre CLAUDE.md.

La commande générée contient déjà :

• l’ID du scénario ;
• l’ID de l’environnement ;
• le reporter -r cli.

Exemple :

apidog run -t <scenario_id> -e <env_id> -r cli

Le reporter cli affiche les étapes et le résumé dans le terminal. C’est la sortie que Claude Code peut lire pour déterminer la suite : continuer, inspecter une assertion ou corriger le code.

Pour le détail des options, consultez le guide complet de la CLI Apidog et la référence de apidog run.

Étape 3 : demander à Claude Code d’exécuter le test

Démarrez Claude Code à la racine de votre dépôt :

claude

Au démarrage, Claude Code charge CLAUDE.md. Il connaît donc déjà la commande à utiliser pour vérifier votre API.

Vous pouvez ensuite :

• lui demander de modifier un endpoint ;
• lui demander d’exécuter les tests d’API ;
• lui demander de corriger les tests en échec.

Claude Code doit alors exécuter la commande apidog run déclarée dans votre fichier de règles.

Gérer les permissions

Dans son mode par défaut, Claude Code demande une approbation avant d’exécuter une commande shell qui n’a pas encore été autorisée.

Lorsqu’il propose apidog run, approuvez la commande. Pour éviter de valider la même commande à chaque session, ajoutez une règle de permission :

• exécutez /permissions dans Claude Code ;
• ou ajoutez une règle dans .claude/settings.json.

Exemple de règle :

{
  "permissions": {
    "allow": [
      "Bash(apidog run *)"
    ]
  }
}

Un scénario en lecture seule exécuté contre un environnement de staging est généralement un bon candidat à cette liste d’autorisation.

Claude Code propose aussi --dangerously-skip-permissions, qui désactive entièrement les invitations de permission. Réservez cette option aux exécutions non supervisées en CI, pas à l’utilisation quotidienne locale.

Pendant l’exécution, vérifiez que Claude Code affiche :

1. la commande lancée ;
2. la sortie brute ;
3. le code de sortie ;
4. le résumé des assertions.

Ne vous contentez pas d’une phrase indiquant que les tests ont réussi.

Étape 4 : lire le rapport dans Claude Code

Quand une exécution échoue, le reporter cli fournit les informations nécessaires pour corriger le problème :

• la requête concernée ;
• chaque assertion exécutée ;
• l’assertion qui a échoué ;
• la valeur attendue ;
• la valeur réelle ;
• un éventuel code HTTP inattendu.

Cette sortie permet généralement à Claude Code d’identifier le gestionnaire, le champ ou la réponse à corriger.

Pour conserver aussi un rapport ouvrable dans un navigateur, ajoutez le reporter HTML :

apidog run -t <scenario_id> -e <env_id> -r cli,html

Le reporter html écrit un rapport autonome dans :

./apidog-reports

Conservez toujours cli dans la liste des reporters : Claude Code doit pouvoir lire la sortie directement dans le terminal.

Pour les rapports JUnit compatibles avec les tableaux de bord CI et les autres formats, consultez les rapports de test de la CLI Apidog.

Intégrer les tests à la boucle de Claude Code

L’objectif est que Claude Code exécute le scénario sans que vous deviez le rappeler à chaque étape.

Supposons qu’il modifie un gestionnaire qui construit une réponse de commande. Sa boucle devient :

1. il modifie le code ;
2. il exécute le scénario Apidog contre staging ;
3. il lit le code de sortie ;
4. si le résultat est vert, il continue ;
5. si le résultat est rouge, il lit l’assertion en échec ;
6. il corrige le code ;
7. il relance le test.

Le test d’API rejoint ainsi la même boucle édition-test-correction que vos tests unitaires.

Le principe reste celui du modèle « déléguer puis vérifier » :

• vous créez et maintenez les scénarios visuellement dans Apidog ;
• Claude Code exécute la CLI ;
• vous vérifiez que l’agent se base bien sur la sortie réelle et les codes de sortie.

Pour aller plus loin, consultez comment utiliser les agents IA pour les tests d’API et le harnais de test IA d’Apidog.

Vérifier que Claude Code exécute réellement la CLI

Un agent peut annoncer un succès sans avoir réellement exécuté la commande. Vérifiez ces trois points.

1. Vérifier que la commande a été lancée

Claude Code affiche les commandes qu’il exécute et leur sortie.

Recherchez explicitement une ligne de ce type :

apidog run ...

Elle doit être suivie par la sortie de la CLI.

Si Claude affirme avoir exécuté les tests mais qu’aucune commande n’apparaît, demandez-lui de relancer le test et d’afficher la sortie brute.

2. Vérifier le code de sortie

Demandez explicitement :

Quel était le code de sortie de cette commande apidog run ?

La règle est simple :

• 0 : toutes les assertions ont réussi ;
• valeur non nulle : au moins une erreur ou une assertion en échec.

Si le résumé indique « tests réussis » mais que le code de sortie est non nul, considérez l’exécution comme un échec. Le code de sortie fait foi.

3. Vérifier les identifiants utilisés

Une erreur comme « scénario introuvable » indique souvent que Claude Code a utilisé un ID incorrect ou inventé.

Comparez les valeurs suivantes :

• -t <scenario_id>
• -e <env_id>

avec :

• la commande générée dans l’onglet CI/CD d’Apidog ;
• les valeurs présentes dans CLAUDE.md.

Les identifiants de CLAUDE.md doivent rester votre référence.

Facultatif : connecter le serveur MCP d’Apidog

L’exécution de apidog run depuis CLAUDE.md couvre la majorité des besoins. Vous pouvez aussi connecter un serveur MCP pour que Claude Code lise votre spécification d’API pendant qu’il écrit le code.

Claude Code prend en charge le protocole Model Context Protocol (MCP). Ajoutez un serveur avec claude mcp add ..., ou versionnez un fichier .mcp.json à la racine du projet avec le scope project.

Le serveur MCP Apidog expose vos spécifications d’API via MCP.

La répartition est claire :

• la CLI exécute les tests ;
• MCP fournit la spécification à Claude Code pendant le développement.

Quand Claude Code se trompe

Il ignore le bloc CLAUDE.md

Si Claude Code n’exécute aucune commande ou utilise une commande générique :

1. vérifiez que le fichier se nomme exactement CLAUDE.md ;
2. vérifiez qu’il se trouve à la racine du dépôt ou dans un répertoire parent ;
3. exécutez /memory pour lister les fichiers réellement chargés ;
4. redémarrez la session pour forcer une nouvelle lecture.

Si le fichier n’apparaît pas dans /memory, Claude Code ne l’a pas chargé.

Il ajoute un jeton d’accès

Si Claude Code tente d’ajouter --access-token, il s’appuie probablement sur un exemple public plutôt que sur vos instructions.

Le bloc CLAUDE.md doit indiquer clairement :

La machine est déjà authentifiée via `apidog login`.
N'ajoutez jamais `--access-token`.
Ne stockez jamais de jeton dans ce fichier.

Pour la configuration initiale, consultez l’authentification de la CLI Apidog.

Il invente une option

Une erreur « option inconnue » signifie que Claude Code a deviné une option absente de votre version installée.

Demandez-lui d’exécuter :

apidog run --help

Il doit ensuite utiliser l’option exacte affichée par cette commande.

Il annonce un succès malgré un échec

C’est l’erreur la plus coûteuse.

Lorsque le résumé de Claude et le code de sortie ne concordent pas, le code de sortie l’emporte. C’est pourquoi cette règle doit apparaître dans CLAUDE.md et dans vos vérifications de revue.

D’un agent quotidien à une boucle testée

La configuration est simple :

1. installez apidog-cli en suivant le guide d’installation ;
2. ajoutez une commande apidog run avec les vrais identifiants dans CLAUDE.md ;
3. autorisez cette commande dans les permissions de Claude Code si nécessaire ;
4. vérifiez systématiquement la sortie et le code de sortie.

Claude Code peut alors exécuter vos tests d’API dans la même boucle que celle utilisée pour modifier le code. Un endpoint cassé est détecté pendant la modification, plutôt qu’après le déploiement.

Un test derrière une interface graphique dépend d’un clic humain. Une commande dans CLAUDE.md peut être exécutée chaque fois que Claude Code doit valider une modification.

Continuez à construire vos scénarios dans Apidog, puis ajoutez leur commande apidog run dans CLAUDE.md. Pour exécuter ensuite la même commande dans un pipeline CI sans Claude Code, consultez la CLI Apidog dans GitHub Actions.