Apidog CLI in Cursor verwenden

Der Agent von Cursor bearbeitet bereits Dateien, führt Ihr Terminal aus, liest die Ausgabe und behebt Fehler, die er verursacht hat. Der nächste Schritt ist, Ihre API-Tests in diesen Kreislauf einzubinden: Lassen Sie Cursor Ihre echten Apidog-Szenarien ausführen, den Erfolg oder Misserfolg lesen und weiterarbeiten. Das Element, das dies ermöglicht, ist ein Befehlszeilen-Runner, den Cursor aufrufen kann.

Dieser Runner ist die Apidog CLI, ein npm-Paket namens apidog-cli. Es führt die Testszenarien aus, die Sie visuell in Apidog erstellt haben, über ein Terminal aus und beendet sich mit einem Statuscode, auf den Cursor reagieren kann. Dieser Leitfaden behandelt die Cursor-spezifische Hälfte: die Regeldatei, die Cursor Ihren Workflow beibringt, die Aufforderung, die einen Test ausführt, wie der Ablauf in seinen Bearbeiten-Testen-Beheben-Kreislauf integriert wird, und den optionalen MCP-Server, der Cursor Ihre API-Spezifikation während des Codierens zur Verfügung stellt.

Wenn die CLI noch nicht installiert ist, beginnen Sie mit der Installation der Apidog CLI mit einem KI-Codierungsagenten, der Cursor durch Installation und Authentifizierung führt. Kehren Sie zurück, sobald apidog --version eine Nummer ausgibt. Sie benötigen außerdem ein Apidog-Konto mit mindestens einem gespeicherten Testszenario. Laden Sie Apidog herunter, falls Sie keines haben.

Was „die CLI in Cursor verwenden“ bedeutet

Es gibt kein Apidog-Plugin für Cursor, und Sie benötigen auch keines. Der Agent von Cursor führt bereits Shell-Befehle in Ihrem Projektterminal aus. Die Verwendung der Apidog CLI in Cursor bedeutet also drei Dinge:

1. Bringen Sie Cursor den Workflow einmal bei mit einer Projektregel, damit es den Befehl, die Flags und weiß, dass der Exit-Code die Quelle der Wahrheit ist.
2. Lassen Sie den Agenten apidog run ausführen als normalen Schritt in seinem Kreislauf, so wie er Ihre Unit-Tests ausführt.
3. Verbinden Sie optional den Apidog MCP-Server, damit Cursor Ihre API-Spezifikation lesen kann, während es den Code schreibt, den diese Tests prüfen.

Die Regel ist das, was dies zu einem Cursor-spezifischen Leitfaden macht, anstatt eines allgemeinen „Terminal öffnen und tippen“-Leitfadens.

Schritt 1: Eine Projektregel hinzufügen

Cursor liest Projektregeln aus einem .cursor/rules-Verzeichnis im Root-Verzeichnis Ihres Repositories. Jede Regel ist eine .mdc-Datei mit einem kleinen Frontmatter-Block, der zusammen mit Ihrem Code versionskontrolliert wird, damit das gesamte Team das gleiche Verhalten erhält.

Erstellen Sie eine auf zwei Arten: Geben Sie /create-rule im Chat ein und beschreiben Sie, was Sie möchten, oder öffnen Sie Cursor-Einstellungen > Regeln, Befehle und klicken Sie auf + Regel hinzufügen. In beiden Fällen erhalten Sie eine Datei unter .cursor/rules.

Speichern Sie dies als .cursor/rules/apidog-cli.mdc:

---
description: How to run Apidog API tests from the terminal
alwaysApply: false
---

# Running Apidog API tests

This project has API test scenarios in Apidog. Run them with the
apidog-cli, which is installed globally and already authenticated.

- The command is `apidog run`. The binary is `apidog`.
- Run a single scenario by ID: `apidog run -t <scenarioId> -e <environmentId> -n 1 -r cli`
  - `-t` is the test scenario ID, `-e` is the environment ID.
  - `-n 1` runs it once. `-r cli` prints a readable report to the terminal.
- Do not pass `--access-token`. Auth is handled by a prior `apidog login`.
- The exit code is the source of truth: `0` means every assertion passed,
  non-zero means a failure. Report the exit code, not just a summary.
- If a flag is unknown, run `apidog run --help` and use the exact flag from there.
  Never guess at flag names.
- After changing code that touches an endpoint, run the relevant scenario
  and read the result before claiming the change works.

Das Frontmatter ist wichtig. description plus alwaysApply: false macht dies zu einer „intelligent anwenden“-Regel: Cursor zieht sie heran, wenn der Chat das Ausführen von Tests betrifft, anstatt bei jeder Konversation Kontext zu verbrennen. Setzen Sie alwaysApply: true, um sie immer im Geltungsbereich zu halten. Um sie auf einen Dateityp zu beschränken, lassen Sie die Beschreibung weg und fügen Sie eine globs-Zeile hinzu, und Cursor hängt sie automatisch an, wenn eine passende Datei geöffnet ist.

Der Inhalt erledigt die eigentliche Arbeit. Er legt die Befehlsstruktur fest, sagt, woher die Authentifizierung kommt, und gibt die Zeile an, die einen Agenten ehrlich hält: Der Exit-Code hat Vorrang vor dem Prosa-Bericht. Agenten lesen manchmal einen fehlerhaften Bericht und nennen ihn „sieht gut aus“. Diese Regel einmal festzuhalten, bedeutet, dass Sie sie nicht manuell abfangen müssen.

Schritt 2: Den Befehl von Apidog erhalten

Bevor Sie den Agenten bitten, etwas auszuführen, besorgen Sie sich einen funktionierenden Befehl. Lassen Sie Cursor die IDs nicht erraten.

Öffnen Sie Ihr Testszenario in Apidog, wechseln Sie zur Registerkarte CI/CD und wählen Sie die Befehlszeilenoption. Apidog erstellt den vollständigen apidog run-Befehl mit bereits ausgefüllter Szenario-ID, Umgebungs-ID und einem Access Token:

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

605067 ist die Testszenario-ID und 1629989 ist die Umgebungs-ID; Ihre werden abweichen. Da Sie die CLI während der Installation authentifiziert haben, lassen Sie den Teil --access-token weg und behalten Sie die IDs. Das ist der Befehl, den Ihre Regel Cursor anweisen wird zu verwenden.

Schritt 3: Lassen Sie den Agenten den Test ausführen

Öffnen Sie den Agenten von Cursor (den Chat-Modus, der Terminalbefehle ausführt, nicht die Inline-Bearbeitung). Mit der vorhandenen Regel ist die Aufforderung kurz:

Führe mein Apidog-Testszenario aus und zeige mir die vollständige Ausgabe und den Exit-Code.

Cursor schlägt den Befehl vor und führt ihn, nachdem Sie ihn genehmigt haben, im integrierten Terminal aus:

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

Standardmäßig fragt Cursor vor der Ausführung eines Terminalbefehls, sodass Sie genau sehen, was ausgeführt werden soll. Genehmigen Sie es, und der Agent führt das Szenario aus und liest dann die Ausführung und eine Zusammenfassung vor.

Ihre Prüfung: Achten Sie auf den Exit-Code, nicht auf die Zusammenfassung. apidog run beendet sich mit 0, wenn jede Assertion bestanden wird, und mit einem Wert ungleich Null, wenn eine fehlschlägt. Dieses Verhalten ist der Hauptgrund, warum dies als Gate für CI und für den Agenten funktioniert. Wenn Cursor sagt „Tests bestanden“, der Exit-Code aber ungleich Null war, ist es falsch; vertrauen Sie dem Code. Dies ist genau der Fehler, den die Regel aus Schritt 1 verhindert.

Für ein anderes Berichtsformat oder mehr Iterationen lassen Sie den Agenten apidog run --help ausführen, damit er die tatsächliche Flag-Liste für Ihre installierte Version liest. Der vollständige Apidog CLI-Leitfaden dokumentiert jedes Flag, einschließlich der html-, json- und junit-Reporter sowie datengesteuerte Iterationen.

Schritt 4: Den Bericht in Cursor lesen

Der -r cli-Reporter gibt Ergebnisse an das Terminal aus, das Cursor bereits liest, was ihn für die Arbeit des Agenten passend macht. Der Agent sieht die gleichen Zeilen wie Sie: welches Szenario ausgeführt wurde, jede Anfrage, jede Assertion und die endgültige Anzahl der erfolgreichen oder fehlgeschlagenen Durchläufe.

Wenn ein Lauf fehlschlägt, benennt der Bericht die fehlgeschlagene Assertion, den erwarteten Wert und das, was der Endpunkt zurückgegeben hat. Da dieser Text im Kontext des Agenten liegt, können Sie im selben Chat nachhaken:

Das Szenario ist fehlgeschlagen. Lies die fehlgeschlagene Assertion im Bericht, finde den Handler, der dieses Feld erzeugt, und schlage eine Lösung vor. Dann führe das Szenario erneut aus und zeige mir den neuen Exit-Code.

Jetzt ist der Test Teil des Kreislaufs. Cursor bearbeitet den Handler, führt apidog run erneut aus, liest den neuen Exit-Code und fährt entweder fort oder versucht es erneut. Ihre API-Prüfungen leben im selben Bearbeiten-Testen-Beheben-Zyklus, den Cursor für Unit-Tests verwendet, mit der Ausnahme, dass diese gegen echte Endpunkte laufen. Für das umfassendere Muster behandelt die Verwendung von KI-Agenten für API-Tests, wo es passt und wo nicht.

Optional: Den Apidog MCP-Server verbinden

Die CLI ermöglicht es Cursor, Ihre Tests auszuführen. Der Apidog MCP-Server lässt Cursor Ihre API-Spezifikation lesen, während er Code schreibt. Die beiden ergänzen sich: Der MCP-Server versorgt Cursor mit Ihrem Schema, sodass es Code generiert, der dem Vertrag entspricht, und die CLI überprüft diesen Code anhand realer Szenarien.

Cursor unterstützt MCP-Server über eine JSON-Konfiguration. Legen Sie projektbezogene Server in .cursor/mcp.json im Stammverzeichnis Ihres Repositories ab oder globale Server in ~/.cursor/mcp.json. Die Struktur ist ein mcpServers-Objekt, das nach einem Namen geschlüsselt ist, jeweils mit einem command, einem args-Array und optionalen env-Werten:

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

Zwei Hinweise. MCP ist in einigen Installationen hinter einem Schalter gesichert, öffnen Sie also die Cursor-Einstellungen, suchen Sie den Abschnitt „Model Context Protocol“ und vergewissern Sie sich, dass der Apidog-Server aktiviert ist. Und wenn Sie .cursor/mcp.json committen, kodieren Sie den Token nicht fest; verweisen Sie auf eine Umgebungsvariable. Für die vollständige Einrichtung, einschließlich der Bezugsquellen für Projekt-ID und Token, siehe den Apidog MCP-Server-Leitfaden. Für einen paketierten, wiederverwendbaren Workflow anstatt einer manuellen Einrichtung zeigt der Apidog CLI mit Claude Skills-Leitfaden die fähigkeitenbasierte Version.

Vom lokalen Kreislauf zur CI

Sobald Cursor das Szenario lokal ausgeführt und auf den Exit-Code reagiert hat, haben Sie den genauen Befehl validiert, den Ihre Pipeline verwenden wird. Der Sprung zur CI ist klein: derselbe apidog run-Befehl, wobei der Token als maskiertes Geheimnis anstelle eines gespeicherten Logins übergeben wird. Sie können Cursor sogar bitten, den Schritt zu schreiben, da es den Befehl aus Ihrer Regel kennt:

Die Mechanismen dieses Schrittes (Secrets, Reporter, Exit-Code-Gating) finden Sie in Apidog CLI in GitHub Actions. Derselbe Befehl läuft jetzt an drei Stellen: in Ihrem Terminal, im Agenten-Kreislauf von Cursor und in der CI, die alle demselben Exit-Code vertrauen.

Häufige Fallstricke

Die Regel wird nicht angewendet. Mit description und alwaysApply: false lädt Cursor die Regel nur, wenn es den Chat als relevant erachtet. Wenn eine Testsitzung die Regel nicht aufgreift, erwähnen Sie sie mit @apidog-cli im Chat oder wechseln Sie zu alwaysApply: true.

Der Agent kann den Befehl nicht ausführen. Wenn er nur Befehle vorschlägt, anstatt sie auszuführen, befinden Sie sich wahrscheinlich im Bearbeitungsmodus und nicht im Agenten, oder Sie haben die Genehmigungsaufforderung verpasst. Vergewissern Sie sich, dass Sie sich im Agenten-Chat befinden und genehmigen Sie, wenn Cursor fragt. Wenn Terminalläufe vollständig fehlschlagen, handelt es sich meist um das Problem des PATHs „apidog: command not found“, das der Installationsleitfaden behandelt.

apidog whoami zeigt an, dass Sie nicht authentifiziert sind. Der Login wird auf Ihrem Computer gespeichert, nicht in Cursor. Führen Sie apidog login --with-token selbst mit einem neuen Token von Apidog aus und bitten Sie dann den Agenten, dies mit apidog whoami zu bestätigen. Halten Sie den Token aus dem Chat fern.

Es erfindet ein Flag. Wenn ein Lauf mit einem „unbekannte Option“-Fehler fehlschlägt, hat der Agent ein Flag geraten, das in Ihrer Version nicht existiert. Lassen Sie ihn apidog run --help ausführen und kopieren Sie das genaue Flag.

Zusammenfassung

Die Cursor-Einrichtung besteht aus einer Datei und einer Gewohnheit: einer .cursor/rules/apidog-cli.mdc-Regel, die den Befehl, die Authentifizierungsquelle und die Exit-Code-Regel festlegt, sowie der Gewohnheit, den Agenten apidog run ausführen zu lassen und den Exit-Code selbst zu überprüfen. Fügen Sie den Apidog MCP-Server hinzu, und Cursor kann auch Ihre Spezifikation lesen, während es programmiert.

Sie erstellen Szenarien weiterhin visuell in Apidog; Cursor führt sie einfach aus. Von hier aus können Sie denselben Befehl mit der Apidog CLI in GitHub Actions auf Ihre Pipeline richten oder die vollständige Flag-Referenz im vollständigen Apidog CLI-Leitfaden nachlesen.