Apidog CLI in Claude Code nutzen: So geht's

Claude Code ist eine Schleife: Es bearbeitet Dateien, führt Befehle in Ihrem Terminal aus, liest die Ausgabe und entscheidet, was als Nächstes zu tun ist. Warum sind Ihre API-Tests nicht Teil dieser Schleife? Sie sitzen in Apidog hinter einer GUI und werden ausgeführt, wenn sich jemand daran erinnert, zu klicken. Ihr Agent rührt sie nie an.

Apidog noch heute ausprobieren

Die Lösung ist ein einziger Konfigurationsblock. Die Apidog CLI ist ein npm-Paket, apidog-cli, das die in Apidog erstellten Testszenarien direkt im Terminal ausführt. Sobald die CLI installiert ist und Claude Code weiß, dass sie existiert, führt Ihr Agent ein Apidog-Szenario genauso aus wie Ihre Komponententests: Befehl auslösen, Exit-Code lesen und bei Fehlern den Code korrigieren.

Dieser Leitfaden zeigt den Claude-Code-spezifischen Teil, den allgemeine Installationsanleitungen oft überspringen: den Eintrag in CLAUDE.md, das Berechtigungsmodell für apidog run und die Einbindung der Ergebnisse in die Editier-Test-Korrektur-Schleife.

Wenn Sie die CLI noch nicht installiert haben, erledigen Sie das zuerst. So installieren Sie die Apidog CLI mit einem KI-Coding-Agenten beschreibt npm-Installation und ersten Lauf. Dieser Artikel setzt voraus, dass apidog --version eine Versionsnummer ausgibt und Ihr Apidog-Konto authentifiziert ist.

Um welchen Claude Code es hier geht

Gemeint ist die Claude Code CLI: Anthropics Coding-Agent für Terminal und Desktop-App. Er liest Ihr Repository, bearbeitet Dateien und führt Shell-Befehle aus. Je nach Berechtigungsmodus fordert er dafür eine Genehmigung an.

Es geht nicht um die Claude-Chat-App und nicht um einen einfachen API-Aufruf. Wenn Sie claude im Repository starten und einen interaktiven Agenten erhalten, der Änderungen und Befehlsausführungen vorschlägt, sind Sie hier richtig.

Ihre Terminal-Anweisungen liegen in Claude Code Schrägstrich-Befehlen und in der Regeldatei des Projekts. Genau dort gehört die Apidog CLI hin.

Die Unterscheidung ist wichtig: Claude Code lernt Projektregeln über CLAUDE.md. Damit wird aus einem einmaligen „Führe meine Tests aus“ eine dauerhafte Anweisung, die Claude selbstständig verwenden kann.

Schritt 1: Den Apidog-Block zu CLAUDE.md hinzufügen

Claude Code liest CLAUDE.md-Dateien zu Beginn jeder Sitzung. Das ist das direkte Gegenstück zu AGENTS.md für Codex. Laut Claude-Code-Dokumentation liest Claude Code CLAUDE.md, nicht AGENTS.md. Wenn Sie bereits eine AGENTS.md für einen anderen Agenten verwenden, können Sie sie mit @AGENTS.md importieren.

Wenn Sie die Apidog CLI bereits in Codex eingerichtet haben, ist das Prinzip identisch — nur der Dateiname ist anders.

Legen Sie CLAUDE.md im Stammverzeichnis Ihres Repositories an. Claude Code akzeptiert auch ./.claude/CLAUDE.md sowie ~/.claude/CLAUDE.md für persönliche globale Standards. Claude Code durchsucht den Verzeichnisbaum ab dem Startverzeichnis und lädt jede gefundene CLAUDE.md.

Fügen Sie einen Block wie diesen ein:

## API-Tests mit Apidog CLI

Dieses Projekt enthält Apidog-Testszenarien. Um die API zu überprüfen, führen Sie Folgendes aus:

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

- Exit-Code 0 bedeutet, dass jede Assertion bestanden wurde. Ungleich Null bedeutet, dass etwas fehlgeschlagen ist; öffnen Sie den Bericht und beheben Sie den Fehler, bevor Sie fortfahren.
- Die Maschine ist bereits über `apidog login` authentifiziert. Fügen Sie niemals ein `--access-token`-Flag hinzu und speichern Sie niemals ein Token in dieser Datei.
- Wenn ein Flag unbekannt ist, führen Sie `apidog run --help` aus und verwenden Sie das dort dokumentierte Flag.

Ersetzen Sie <scenario_id> und <env_id> im nächsten Schritt durch Ihre tatsächlichen Werte.

Warum gehört das in CLAUDE.md statt in den Chat? Eine während der Sitzung genannte Szenario-ID geht beim Sitzungsende verloren. Eine Anweisung in CLAUDE.md steht jedem Teammitglied und jedem Claude-Code-Lauf dauerhaft zur Verfügung. Die Datei wird beim Start geladen und bleibt auch nach /compact aktiv.

Schritt 2: Den Befehl aus Apidog übernehmen

Die Werte für <scenario_id> und <env_id> sollten Sie nicht erraten.

1. Öffnen Sie das Testszenario in Apidog.
2. Wechseln Sie zum Tab CI/CD.
3. Kopieren Sie den generierten apidog run ...-Befehl.
4. Übernehmen Sie die darin enthaltene Szenario-ID, Umgebungs-ID und den Reporter -r cli in Ihre CLAUDE.md.

Der Reporter -r cli gibt die Ergebnisse direkt im Terminal aus: ausgeführte Schritte, Assertions und eine Zusammenfassung. Das ist genau die Ausgabe, die Claude Code für die Entscheidung über den nächsten Schritt lesen kann.

Eine Übersicht der verfügbaren Optionen finden Sie im vollständigen Apidog CLI-Leitfaden und in der apidog run-Befehlsreferenz.

Schritt 3: Claude Code den Test ausführen lassen

Starten Sie Claude Code im Stammverzeichnis Ihres Repositories:

claude

Claude Code lädt beim Start Ihre CLAUDE.md und kennt damit den Testbefehl. Nehmen Sie eine API-relevante Änderung vor oder fordern Sie Claude explizit auf, die API-Tests auszuführen. Claude Code kann dann den in CLAUDE.md hinterlegten apidog run-Befehl verwenden.

Berechtigungen für apidog run

Im Standardmodus fragt Claude Code nach, bevor ein noch nicht genehmigter Shell-Befehl ausgeführt wird. Genehmigen Sie apidog run, wenn Sie dazu aufgefordert werden.

Für einen vertrauenswürdigen Befehl können Sie eine Berechtigungsregel hinterlegen:

• Führen Sie /permissions innerhalb der Claude-Code-Sitzung aus, oder
• erlauben Sie Bash(apidog run *) in .claude/settings.json.

Ein schreibgeschütztes Testszenario gegen Staging eignet sich für eine Whitelist. Für unbeaufsichtigte Ausführungen steht --dangerously-skip-permissions zur Verfügung. Verwenden Sie diese Option für CI, nicht für die tägliche lokale Arbeit.

Achten Sie darauf, dass Claude Code den ausgeführten Befehl, die Terminalausgabe und den Exit-Code zeigt — nicht nur eine textliche Erfolgsmeldung.

Schritt 4: Den Bericht in Claude Code lesen

Wenn ein Lauf fehlschlägt, enthält der CLI-Bericht die relevanten Details:

• jede ausgeführte Anfrage,
• jede Assertion,
• erwartete und tatsächliche Werte,
• fehlgeschlagene Statuscodes oder Felder.

Die fehlgeschlagene Assertion nennt in der Regel das konkrete Problem. Damit kann Claude Code eine Korrektur ableiten, den Code anpassen und den Test erneut ausführen.

Für einen zusätzlich im Browser nutzbaren Bericht ergänzen Sie den HTML-Reporter:

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

Der Reporter html schreibt eine eigenständige Datei nach ./apidog-reports. Lassen Sie cli in der Reporter-Liste stehen, damit Claude Code die Inline-Ausgabe weiterhin lesen kann.

Informationen zu JUnit-Ausgabe für CI-Dashboards und weiteren Formaten finden Sie unter Apidog CLI Testberichte.

Claude Code-Tests innerhalb der eigenen Schleife

Der Nutzen entsteht, wenn Claude Code das Szenario nicht nur auf Nachfrage ausführt, sondern es aufgrund der Projektanweisung selbst in seinen Workflow einbezieht.

Beispiel: Claude Code bearbeitet einen Handler für eine Checkout-Antwort.

1. Claude ändert den Code.
2. Claude führt das Apidog-Szenario gegen Staging aus.
3. Claude liest Terminalausgabe und Exit-Code.
4. Bei Exit-Code 0 arbeitet Claude weiter.
5. Bei einem Exit-Code ungleich 0 prüft Claude die fehlgeschlagene Assertion.
6. Claude korrigiert den Code und führt den Test erneut aus.

Damit wird der API-Test Teil derselben Editier-Test-Korrektur-Schleife, in der Claude Code bereits Komponententests ausführt.

Das entspricht dem Modell „delegieren, dann verifizieren“: Claude Code führt den Befehl aus und liest das Ergebnis, während Sie die Szenarien weiterhin visuell in Apidog erstellen und stichprobenartig prüfen, ob Exit-Codes korrekt interpretiert werden. Weitere Hintergründe finden Sie unter KI-Agenten für API-Tests verwenden und im Apidog AI Test Harness.

Überprüfen, ob Claude Code die CLI tatsächlich ausführt

Agenten können Erfolge melden, ohne die erwartete Prüfung ausgeführt zu haben. Prüfen Sie deshalb diese drei Punkte.

1. Wurde der Befehl wirklich ausgeführt?

Claude Code zeigt ausgeführte Befehle und deren Ausgabe inline an. Suchen Sie nach der wörtlichen Zeile:

apidog run ...

Darunter muss eine tatsächliche Ausgabe stehen. Wenn Claude behauptet, die Tests seien gelaufen, Sie aber weder Befehl noch Ausgabe sehen, fordern Sie eine erneute Ausführung mit Rohausgabe an.

2. Was war der Exit-Code?

Fragen Sie direkt:

Was war der Exit-Code dieses apidog run-Befehls?

apidog run beendet sich mit 0, wenn alle Assertions bestanden wurden. Bei mindestens einem Fehler ist der Exit-Code ungleich 0.

Behandeln Sie diesen Wert als Gate:

• 0: Testlauf bestanden
• != 0: Testlauf fehlgeschlagen

Wenn Claudes Zusammenfassung „Tests bestanden“ sagt, der Exit-Code aber ungleich 0 ist, gilt der Exit-Code.

3. Wurde das reale Szenario verwendet?

Ein Fehler wie „Szenario nicht gefunden“ kann bedeuten, dass Claude eine ID geraten oder falsch erinnert hat. Vergleichen Sie die Werte für -t und -e mit:

• Ihrer CLAUDE.md
• dem von Apidog im CI/CD-Tab generierten Befehl

Die IDs in CLAUDE.md sollten dem generierten Befehl entsprechen.

Optional: Den Apidog MCP-Server verbinden

Das Ausführen von apidog run über CLAUDE.md deckt den zentralen Test-Workflow ab. Mit einem MCP-Server kann Claude Code zusätzlich Ihre API-Spezifikation lesen, während es Code schreibt.

Claude Code unterstützt das Model Context Protocol. Sie können einen Server mit claude mcp add ... hinzufügen oder eine .mcp.json im Projektstammverzeichnis committen und --scope project verwenden, damit das Team dieselbe Konfiguration nutzt.

Der Apidog MCP-Server stellt API-Spezifikationen über MCP bereit. Die Aufgabentrennung ist dabei klar:

• Apidog CLI: führt Tests aus
• Apidog MCP: liefert Claude Code die API-Spezifikation als Kontext

Wenn Claude Code Fehler macht

Claude ignoriert den CLAUDE.md-Block

Wenn Claude einen generischen Befehl oder gar keinen Befehl ausführt, wurde die Datei möglicherweise nicht geladen.

Prüfen Sie:

1. Die Datei heißt exakt CLAUDE.md.
2. Sie liegt im Repository-Stammverzeichnis oder einem übergeordneten Verzeichnis des aktuellen Arbeitsverzeichnisses.
3. /memory listet die Datei als geladen auf.

Wenn Ihre Datei nicht in /memory erscheint, kann Claude sie nicht verwenden. Starten Sie die Sitzung neu, um die Dateien erneut zu laden.

Claude übergibt trotzdem ein Zugriffstoken

Wenn Claude --access-token ergänzt, übernimmt es möglicherweise Muster aus öffentlichen Beispielen. Ihre CLAUDE.md sollte ausdrücklich festlegen, dass die Maschine bereits über apidog login authentifiziert ist.

Speichern Sie niemals ein echtes Token in CLAUDE.md. Details zur einmaligen Anmeldung finden Sie unter Apidog CLI Authentifizierung.

Claude erfindet ein Flag

Ein Fehler wie „unbekannte Option“ bedeutet, dass ein nicht unterstütztes Flag verwendet wurde. Weisen Sie Claude an, zuerst Folgendes auszuführen:

apidog run --help

Danach soll es das für Ihre installierte CLI-Version dokumentierte Flag verwenden.

Claude meldet Erfolg bei einem fehlgeschlagenen Lauf

Das ist der kostspieligste Fehler. Deshalb sollten Exit-Code-Regel und Verifizierungsschritte in CLAUDE.md stehen.

Wenn Zusammenfassung und Exit-Code nicht übereinstimmen, gewinnt immer der Exit-Code.

Vom täglichen Agenten zur getesteten Schleife

Die Einrichtung ist überschaubar:

1. Installieren Sie apidog-cli gemäß Installationsanleitung.
2. Kopieren Sie den echten apidog run-Befehl aus dem Apidog-CI/CD-Tab.
3. Legen Sie den Befehl inklusive Exit-Code-Regeln in CLAUDE.md ab.
4. Lassen Sie Claude Code den Test nach API-relevanten Änderungen ausführen.
5. Prüfen Sie Befehl, Ausgabe und Exit-Code.

Ein Test hinter einer GUI läuft nur, wenn ein Mensch klickt. Ein in CLAUDE.md dokumentierter Terminalbefehl kann Teil von Claudes normalem Arbeitsablauf werden. Sie erstellen Ihre Szenarien weiterhin visuell in Apidog, während Ihr Agent sie während der Implementierung ausführt.

Laden Sie Apidog herunter, erstellen Sie ein Szenario und fügen Sie dessen apidog run-Befehl in CLAUDE.md ein. Wenn Sie denselben Befehl später ohne Claude in einer Pipeline ausführen möchten, behandelt Apidog CLI in GitHub Actions Geheimnisse, Reporter und Exit-Code-Gating.