Die WebAPI CLI ermöglicht den Zugriff auf die von einem i-net-Server bereitgestellten WebAPI-Operationen über die Kommandozeile. Die CLI verbindet sich mit dem MCP-Endpunkt des Servers, liest die für das Benutzerkonto verfügbaren Tools und kann diese interaktiv, in Skripten oder aus KI-gestützten Entwicklungsumgebungen heraus verwenden.
Die verfügbaren Tools hängen vom Produkt, den installierten Erweiterungen, der Serverkonfiguration und den Berechtigungen des verwendeten Kontos ab.
Voraussetzungen
- i-net-Server mit aktiviertem WebAPI-Core-MCP-Endpunkt
- Server-URL einschließlich eines eventuell verwendeten Anwendungskontexts
- Bearer-Token mit WebAPI-Zugriff und den erforderlichen API-Berechtigungen
uvund Python 3.10 oder höher
Die CLI ergänzt automatisch den Pfad /mcp. Geben Sie /mcp daher nicht selbst in der Server-URL an. Bei einem Anwendungskontext verwenden Sie zum Beispiel https://server.example.com/helpdesk.
Installation
Installieren Sie uv zunächst nach der Anleitung für Ihr Betriebssystem. Danach installieren Sie die CLI dauerhaft:
Die CLI ist als Projekt auf GitHub verfügbar.
uv tool install webapi-cli
webapi --help
Für eine einmalige Verwendung ohne dauerhafte Installation:
uvx webapi-cli login
uvx webapi-cli discover
Mit einem Server verbinden
Erstellen Sie im i-net-Server einen Bearer-Token mit WebAPI-Zugriff und den Berechtigungen für die benötigten API-Kontexte. Starten Sie anschließend die Anmeldung:
webapi login
Die CLI fragt interaktiv nach Server-URL und Token. Das Token wird bei der Eingabe nicht angezeigt.
Für ein benanntes Profil können Sie Server und Profil direkt angeben:
webapi login --server https://server.example.com --profile production
Tools entdecken und prüfen
Verfügbare Tools anzeigen:
webapi discover
Die Liste wird vom Server bereitgestellt und kann sich je nach Produkt, Erweiterungen, Serverversion und Benutzerrechten unterscheiden. Für eine erneute Abfrage verwenden Sie webapi discover --refresh.
Prüfen Sie vor einem Aufruf Beschreibung, Pflichtparameter und Schema:
webapi describe TOOL_NAME
webapi describe --pretty-print TOOL_NAME
Tool-Namen werden aus API-Pfad und HTTP-Methode gebildet. Verwenden Sie immer exakt den Namen, den webapi discover ausgibt. Ein API-Aufruf wie GET /api/cowork/teams/{team}/channels kann beispielsweise als cowork__teams__team__channels__get erscheinen.
Tools ausführen
Parameter werden mit --params, ein Request-Body mit --body übergeben:
webapi call TOOL_NAME --params '{"id":"123","limit":5}'
webapi call TOOL_NAME --body '{"name":"Example"}'
webapi call TOOL_NAME --params '{"id":"123"}' --body '{"name":"Example"}'
Für Skripte empfiehlt sich JSON-Ausgabe:
webapi call --pretty-print TOOL_NAME --params '{"id":"123"}' | jq .
Prüfen Sie vor jedem Aufruf das Schema. Einige Operationen lesen nur Daten, andere können Tickets, Benutzer, Konfigurationen oder andere Serverdaten verändern.
Profile für mehrere Umgebungen
webapi login --server https://dev.example.com --profile dev
webapi login --server https://staging.example.com --profile staging
webapi login --server https://production.example.com --profile production
webapi profiles
webapi profiles use production
webapi whoami
Ein einzelner Aufruf kann gegen einen anderen Server erfolgen:
webapi discover --server https://staging.example.com
Abmelden und den Token des aktiven Profils entfernen:
webapi logout
Verwendung in Skripten und KI-Workflows
Die CLI liest Tool-Beschreibungen und Schemas zur Laufzeit vom Server. Dadurch müssen keine produktspezifischen Clients generiert werden. KI-gestützte Entwicklungsumgebungen können zunächst Tools entdecken, anschließend das Schema prüfen und danach nur freigegebene Operationen ausführen.
Die KI erhält dadurch keine zusätzlichen Rechte. Jeder Aufruf wird weiterhin mit dem Konto und den Berechtigungen des aktiven WebAPI-Profils ausgeführt.
Weitere Informationen zu MCP-Tools finden Sie in der MCP-Tools-Dokumentation.
Profile, Tokens und Sicherheit
Profile und Tokens werden standardmäßig unter ~/.config/webapi-cli/config.json gespeichert. Für getrennte Umgebungen kann XDG_CONFIG_HOME gesetzt werden.
- Verwenden Sie getrennte Profile für Entwicklung, Test und Produktion.
- Speichern Sie Produktionstokens nicht in Skripten, Tickets oder Versionskontrolle.
- Verwenden Sie für Automatisierungen eigene Konten mit minimalen Berechtigungen.
- Prüfen Sie Tools immer mit
discoverunddescribe, bevor Sie sie ausführen. - MCP-Tools können abhängig von ihrer Konfiguration Aktionen auf dem Server ausführen. Verwenden Sie deshalb nur vertrauenswürdige Tools und Skripte.
Typische Anwendungsszenarien
Lesende HelpDesk-Recherche
Ein Supportmitarbeiter entdeckt die Ticket-Tools, prüft das Schema und führt anschließend eine Suche mit einem Konto aus, das nur lesende Berechtigungen besitzt.
Automatisierte Auswertung
Ein Skript ruft regelmäßig Daten ab und verarbeitet die JSON-Ausgabe mit jq oder einem anderen Kommandozeilenwerkzeug.
KI-gestützte Recherche
Eine KI-Anwendung führt zuerst discover und describe aus und verwendet anschließend ein für den jeweiligen Zweck freigegebenes Tool. Das vom Server gelieferte Schema ist die verbindliche Grundlage für Parameter und Datentypen.
Test, Staging und Produktion
Mit getrennten Profilen können dieselben Abfragen zunächst in der Entwicklungs- und Staging-Umgebung geprüft werden, bevor sie ausdrücklich gegen Produktion ausgeführt werden.
Fehlerbehebung
| Problem | Lösung |
|---|---|
| Kein Profil vorhanden | webapi login ausführen. |
| Verbindung fehlgeschlagen | Server-URL, Netzwerkzugriff, Anwendungskontext und Verfügbarkeit von /mcp prüfen. |
| HTTP 401 oder 403 | Token, WebAPI-Zugriff sowie Berechtigungen des API-Kontexts prüfen. |
| Tool nicht gefunden | webapi discover --refresh ausführen und den exakten Tool-Namen übernehmen. |
| Parameterfehler | webapi describe TOOL_NAME prüfen. |
| Antwort schwer lesbar | --pretty-print verwenden. |
| Aufruf funktioniert nur in einer Umgebung | Profil, Server, installierte Erweiterungen und Benutzerberechtigungen vergleichen. |
Kurzfassung: Anmelden, Tools entdecken, Schema prüfen und erst danach den eigentlichen Aufruf ausführen.