Apidog CLI: Der API-Client direkt im Terminal

Ihr API-Arbeitsbereich lebt in einer grafischen Benutzeroberfläche, Ihr Arbeitsalltag aber im Terminal. Jeder Wechsel kostet Zeit und Kontext; in CI-Pipelines oder KI-Agenten-Sitzungen steht eine GUI oft gar nicht zur Verfügung. Die Apidog CLI bringt Tests, Endpunkte, Schemas, Umgebungen, Mock-Erwartungen und Dokumentation direkt in Ihre Shell.

Apidog noch heute ausprobieren

Die Apidog CLI ist kein Ersatz für curl. Für einen einzelnen GET-Request oder die schnelle Prüfung einer JSON-Antwort sind curl, HTTPie und interaktive Terminal-Clients weiterhin passend. Die Übersicht zu Terminal- und TUI-REST-Clients behandelt genau diesen Anwendungsfall.

Die CLI arbeitet stattdessen auf Projektebene: Sie führt gespeicherte Testszenarien aus, liest und aktualisiert API-Verträge und importiert oder exportiert Spezifikationen. Damit eignet sie sich für Skripte, CI und Agenten-Workflows.

Was in Ihrem Terminal verfügbar ist

Die CLI stellt mehr als vierzig Befehlsgruppen bereit:

Aufgabe	Befehle
Tests ausführen	run, test-scenario, test-suite, test-case, test-data, test-report
Vertrag verwalten	endpoint, schema, folder, common-parameter, response-component, security-scheme
Dokumente und Mocks bereitstellen	doc, docs-site, shared-doc, mock
Konfigurieren und verbinden	environment, variables, vault, database-connection, websocket, socketio
Im Team arbeiten	branch, merge-request, runner, scheduled-task, audit-log, import, export

Starten Sie bei jedem unbekannten Befehl mit --help:

apidog run --help
apidog endpoint --help

Die Ausgabe ist strukturiertes JSON. Viele Antworten enthalten zusätzlich agentHints.nextSteps. Diese Hinweise eignen sich besonders für Automatisierungen: Ein Skript oder Agent kann die Antwort parsen und den nächsten vorgeschlagenen Schritt ausführen.

Installation und Anmeldung

Die CLI wird als npm-Paket apidog-cli ausgeliefert und unterstützt macOS, Linux und Windows. Voraussetzung ist Node.js 16 oder neuer.

npm install -g apidog-cli
apidog --version

Melden Sie sich anschließend mit einem API-Zugriffstoken an. Sie finden das Token in der Apidog-App unter Avatar → Kontoeinstellungen → API Access Token.

apidog login --with-token <YOUR_TOKEN>

Das Token wird in ~/.apidog/config.toml gespeichert. Committen Sie diese Datei nicht und schreiben Sie das Token nicht in Logs.

Für CI sollten Sie kein lokal gespeichertes Token verwenden, sondern ein Secret übergeben:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenario_id> \
  -e <env_id> \
  -r cli,junit

Die wichtigsten globalen Optionen:

Option	Zweck
--project	Projekt auswählen
--branch	Branch auswählen
--access-token	Gespeicherte Anmeldung für einen Lauf überschreiben
--api-base-url	Selbst gehostete Apidog-Instanz verwenden

Details zur Token-Verwendung in Pipelines finden Sie im Apidog CLI Authentifizierungsleitfaden.

Testszenarien in CI ausführen

Der typische Workflow:

1. Erstellen Sie ein Testszenario im visuellen Editor von Apidog.
2. Verketten Sie Requests und extrahieren Sie Variablen aus Antworten.
3. Definieren Sie Assertions für Statuscodes und Response-Bodies.
4. Kopieren Sie den Befehl mit Szenario- und Umgebungs-ID aus dem CI/CD-Tab.
5. Führen Sie ihn lokal oder in CI aus.

# IDs aus dem CI/CD-Tab des Szenarios übernehmen
apidog run -t <scenario_id> -e <env_id> -r cli

Der Exit-Code ist für Pipelines geeignet:

• 0: Alle Assertions waren erfolgreich.
• Ungleich 0: Mindestens ein Testschritt ist fehlgeschlagen.

Richten Sie dasselbe Szenario gegen verschiedene Umgebungen, indem Sie nur die Umgebungs-ID ändern:

# Staging
apidog run -t <scenario_id> -e <staging_env_id> -r cli

# Produktion
apidog run -t <scenario_id> -e <production_env_id> -r cli

Datengesteuerte Tests verwenden

Übergeben Sie eine CSV- oder JSON-Datei, damit die CLI das Szenario für jeden Datensatz ausführt. So vermeiden Sie duplizierte Testschritte und variieren nur die Eingabedaten. Der Beitrag zum datengesteuerten Testen beschreibt diesen Ablauf.

Wenn Sie mit dem ersten Szenario beginnen, nutzen Sie die Schritt-für-Schritt-Anleitung für REST APIs.

Reports als CI-Artefakte speichern

apidog run kann Ergebnisse in mehreren Formaten ausgeben:

• cli: Schritt-für-Schritt-Ausgabe im Terminal
• html: HTML-Bericht
• json: Maschinenlesbarer Bericht
• junit: Format für CI-Dashboards und Test-Reporter

Kombinieren Sie mehrere Formate:

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

Dateibasierte Reports landen in apidog-reports/. Beispiele für die Ausgabeformate zeigt der Leitfaden für Testberichte.

Für unabhängig von Ihrem Laptop ausgeführte Jobs stehen runner und scheduled-task bereit. Damit verwalten Sie selbst gehostete Runner und zeitgesteuerte Läufe, wie bei geplanten API-Tests in Apidog.

API-Verträge über die CLI verwalten

Neben dem Ausführen von Tests kann die CLI Projektressourcen abfragen und bearbeiten.

# Endpunkte eines Projekts auflisten
apidog endpoint list --project <project_id>

# Schema abrufen
apidog schema get <schema_id>

# Umgebungen auflisten
apidog environment list

# Mock-Erwartungen auflisten
apidog mock list

Verfügbar sind unter anderem:

• Endpunkte und Ordner
• Datenschemas
• Umgebungen und Variablen
• Sicherheitsschemas und wiederverwendbare Komponenten
• Mock-Erwartungen
• Dokumentationsressourcen mit doc und docs-site
• WebSocket- und Socket.IO-Endpunkte
• Datenbankkonfigurationen über database-connection

Mock-Erwartungen definieren feste Request-Response-Paare, die der Mock-Server zurückgeben soll.

OpenAPI, Swagger und Postman importieren oder exportieren

Die CLI unterstützt OpenAPI 3.x, Swagger 2.0 und Postman Collections. Das ist praktisch für Migrationen und automatisierte Synchronisationen.

# OpenAPI-Spezifikation importieren
apidog import openapi.json --project <project_id>

# Projekt als OpenAPI exportieren
apidog export --format openapi

Swagger 2.0 basiert auf der Swagger-Spezifikation, die in vielen API-Toolchains verwendet wird.

Sichere Schreiboperationen für KI-Agenten

Die CLI-Versionen von 2026 legen einen Schwerpunkt auf die Nutzung durch KI-Code-Agenten. Dafür sind vier Mechanismen relevant.

1. Strukturierte JSON-Ausgabe

Jeder Befehl liefert JSON zurück. Agenten können die Antwort direkt parsen und mithilfe von agentHints.nextSteps den nächsten Schritt bestimmen, einschließlich möglicher Fehlerbehebung.

2. Eingabeschema vor dem Schreiben prüfen

Mit cli-schema können Sie die erwartete JSON-Struktur eines Schreibbefehls abrufen und eine Nutzlast validieren.

# Verfügbare Schemas anzeigen
apidog cli-schema list

# Schema für einen konkreten Befehl abrufen
apidog cli-schema get <schema_id>

# Lokale JSON-Nutzlast vor dem Schreiben validieren
apidog cli-schema validate <payload.json>

Verwenden Sie für automatisierte Änderungen immer diesen Ablauf:

1. Schema abrufen.
2. JSON-Nutzlast erzeugen.
3. Nutzlast validieren.
4. Erst danach create oder update ausführen.

Damit prüfen Sie die Struktur, bevor eine Änderung das Projekt erreicht.

3. CLI-Wissen über skill bereitstellen

Der Befehl skill liefert Betriebswissen in einem Format, das Agenten direkt laden können. Hintergrund und Einsatz beschreibt der Beitrag zur Apidog CLI Skill.

Laut der verlinkten Analyse benötigten Agenten mit CLI-Schema etwa 30 % weniger Tool-Aufrufe und 25 % weniger Tokens als Agenten, die Nutzlasten erraten mussten. Die Methodik und Zahlen stehen in dieser Analyse.

4. Änderungen über Berechtigungen und Branches isolieren

Standardmäßig sind von KI stammende Schreibzugriffe auf einen Branch blockiert, bis ein Mensch External AI Edit Permissions aktiviert. Die Einstellung ist in Apidog Client 2.8.32 oder neuer unter Projekt-Einstellungen → Feature-Einstellungen → KI-Feature-Einstellungen verfügbar.

Alternativ verwenden Sie einen KI-Branch:

1. Agent importiert oder erstellt die benötigten Ressourcen im isolierten Branch.
2. Agent führt seine Änderungen aus.
3. Agent erstellt einen Merge Request.
4. Ein Mensch prüft und führt die Änderung zusammen.

Unberührte KI-Branches werden nach 24 Stunden automatisch archiviert. Dadurch bleiben Experimente getrennt, während Änderungen am API-Vertrag überprüfbar bleiben.

Was die Apidog CLI nicht ist

Kein interaktiver Request-Client

Es gibt keinen Befehl für einen beliebigen Ad-hoc-POST-Request mit formatiert ausgegebener Antwort. Nutzen Sie dafür curl, HTTPie oder TUI-Clients. Die Apidog CLI ist für gespeicherte Szenarien und Projektressourcen gedacht.

Nicht Open Source

Das Paket ist proprietär und npm ist der Installationskanal. Funktionen über --help hinaus benötigen ein Apidog-Konto. Der kostenlose Tarif deckt den hier beschriebenen Workflow ab. Wenn eine auditierbare Open-Source-Lizenz zwingend ist, ist ein Open-Source-Runner die passendere Wahl.

Nicht eigenständig

Szenarien, Endpunkte und Umgebungen liegen im Apidog-Projekt, nicht in lokalen Dateien. Dieser Plattformbezug ermöglicht eine gemeinsame Quelle der Wahrheit für API-Design, Tests, Mocks und Dokumentation.

Einordnung in Ihre Terminal-Toolbox

Der zentrale Unterschied zu anderen Test-Runnern ist der Ort, an dem Tests erstellt werden:

Tool	Testquelle
Newman / Postman CLI	Postman Collections
Hurl / Bruno	Textdateien
Apidog CLI	Szenarien aus dem visuellen Editor, verbunden mit Vertrag, Mocks und Dokumentation

Eine ausführlichere Gegenüberstellung finden Sie in Apidog CLI vs. Newman sowie in der Übersicht der Top-Terminal-basierten API-Testtools.

Ein pragmatisches Setup für viele Teams:

• Verwenden Sie curl oder xh für schnelle Einzelanfragen.
• Nutzen Sie apidog run für wiederholbare Test-Suiten.
• Speichern Sie JUnit-Reports als CI-Artefakte.
• Übergeben Sie Tokens ausschließlich als CI-Secrets.

Eine startfertige Pipeline liefert die GitHub-Actions-Anleitung.

FAQ

Ist die Apidog CLI kostenlos nutzbar?

Ja. Das Paket kann kostenlos über npm installiert werden. Der kostenlose Apidog-Tarif deckt das Erstellen und Ausführen von Szenarien über die CLI ab. Kostenpflichtige Pläne betreffen Funktionen für Teamgrößen, nicht den grundlegenden CLI-Zugriff.

Ersetzt die CLI curl oder HTTPie?

Nein. curl und HTTPie sind für Ad-hoc-Requests geeignet. Die Apidog CLI führt gespeicherte Szenarien aus und verwaltet Projektressourcen. In der Praxis ergänzen sich beide Kategorien.

Kann die CLI vollständig headless in CI laufen?

Ja. Übergeben Sie --access-token aus einem CI-Secret, führen Sie apidog run mit Szenario-ID aus und steuern Sie den Build über den Exit-Code. Auf dem Runner ist keine Desktop-App erforderlich.

Welche Formate unterstützt Import und Export?

OpenAPI 3.x, Swagger 2.0 und Postman Collections. Damit lassen sich APIs migrieren oder mit anderen Toolchains austauschen.

Wie verwenden KI-Agenten die CLI sicher?

Validieren Sie Nutzlasten mit cli-schema validate, bevor Sie Schreiboperationen ausführen. Verwenden Sie außerdem Berechtigungsschranken oder isolierte KI-Branches, bis ein Mensch einen Merge Request prüft. Ein Beispiel in einem Agenten-Workflow zeigt die Verwendung der Apidog CLI in Claude Code.

Das Terminal ist bereits der Ort für Tests, CI und Agenten. Mit der CLI können Sie auch Ihren API-Arbeitsbereich aus diesem Kontext bedienen. Laden Sie Apidog herunter, installieren Sie die CLI über npm und führen Sie ein Szenario Ende-zu-Ende aus. Die Apidog CLI-Seite enthält die vollständige Befehlsreferenz.