API, CLI & KI-Assistenten

Eine Oberfläche, drei Zugänge

Sie können auf drei Wegen mit CloudWady arbeiten, ohne das Dashboard zu öffnen:

• die Befehlszeile cw;
• KI-Assistenten über MCP;
• die HTTP-API, die beide verwenden.

Alle drei beantworten dieselben Fragen:

Ein Token erlaubt auch Änderungen: Backup, Neustart, Wiederholen, Update, Module aktualisieren und Wartung, und ein einstündiges Zertifikat holen, mit dem Sie sich als root an einem Server anmelden (cw ssh).

API-Token erstellen

Klicken Sie auf Neues Token und füllen Sie Folgendes aus:

• Name: wo Sie es verwenden werden, zum Beispiel "Laptop-CLI" oder "CI-Pipeline".
• Läuft ab nach: 1 Woche oder 30, 90, 180 oder 365 Tagen. Benutzerdefiniert… akzeptiert eine beliebige Zahl von 1 bis 365.
• Namespaces: die Namespaces, die das Token lesen darf.
• Darf lesen: die Arten von Daten, die es lesen darf: Apps, Backups, Protokolle, Läufe, Server und so weiter.
• Darf ändern (optional): die Änderungen, die es vornehmen darf.

Ein Token reicht nie weiter als Sie selbst. Ändert sich Ihr eigener Zugriff, folgt das Token bei seiner nächsten Anfrage.

Nachdem Sie auf Token erstellen geklickt haben, wird das Token einmal angezeigt. Es beginnt mit cwk_; bewahren Sie es wie ein Passwort auf.

Die Liste zeigt für jedes Token seine Namespaces, was es lesen darf, wann es zuletzt verwendet wurde und wann es abläuft. Name, Namespaces und Umfang eines Tokens können Sie später bearbeiten, und Sie können es jederzeit widerrufen. Alles, was ein widerrufenes Token verwendet, funktioniert sofort nicht mehr.

Ein Token liest nur, was ihm gegeben wurde. Damit ein älteres Token etwas lesen kann, das seitdem hinzugekommen ist, bearbeiten Sie es und haken Sie das neue Element an.

CLI installieren

macOS und Linux:

curl -fsSL https://www.cloudwady.com/install.sh | sh

Das Skript lädt den Build für Ihren Rechner herunter und prüft ihn anhand der Release-Prüfsummen. Es installiert cw nach /usr/local/bin oder ~/.local/bin, nie mit sudo.

Mit Homebrew unter macOS:

brew install kingswady/tap/cw

Windows, in der PowerShell:

irm https://www.cloudwady.com/install.ps1 | iex

Es prüft den Download auf dieselbe Weise und installiert cw.exe nach AppData\Local\Programs\cw. Es fügt diesen Ordner Ihrem PATH hinzu, ohne dass ein Administrator nötig ist; öffnen Sie danach ein neues Terminal.

Um stattdessen von Hand zu installieren, holen Sie sich cw_windows_amd64.zip von der neueste Version. Entpacken Sie die Datei und legen Sie cw.exe in einen Ordner in Ihrem PATH.

cw login        # paste the token; it is kept in your system keychain
cw whoami       # who the token acts as, its namespaces, and when it expires
cw namespaces   # the namespaces the token reads, and your level in each
cw use          # switch between platforms you logged in to
cw logout       # forget the token on this machine

Auf einem Rechner ohne Schlüsselbund speichert cw das Token in einer Datei, die nur Sie lesen können. In einem Skript leiten Sie das Token per Pipe ein, statt es einzutippen:

printf '%s' "$CW_TOKEN" | cw login --with-token

cw update hält cw aktuell; wenn Homebrew es installiert hat, verwenden Sie brew upgrade cw. cw bietet außerdem an, sich selbst zu aktualisieren, sobald eine neuere Version erschienen ist, und prüft vor der Installation deren Signatur.

Für die Tab-Vervollständigung gibt cw completion zsh das Skript für Ihre Shell aus. Es akzeptiert auch bash und fish; die README sagt, wohin das Skript gehört.

Alltägliche Befehle

cw attention                              # what needs attention now
cw apps --search shop                     # your apps; --env, --version, --project, --server
cw apps show shop                         # one app: URLs, repositories, deployed and newest commit
cw runs --app shop --state error          # recent runs that failed
cw runs show 4812                         # a run's steps, and why one failed
cw logs shop --since 15m --grep ERROR     # the app's Odoo log; --follow keeps it open
cw backups --app shop                     # an app's backups and their off-site copies

Jeder Befehl akzeptiert --json, das die eigene Antwort der API für jq ausgibt, und --namespace acme. Listenbefehle akzeptieren außerdem --limit und --offset. Die CLI-Referenz führt jeden Befehl und jedes Flag auf.

Änderungen vornehmen

Ein Token kann die Änderungen vornehmen, die Sie unter Darf ändern angehakt haben. Das sind die eigenen Aktionen des Dashboards, mit denselben Prüfungen. Ihre Ebene in der Umgebung der App muss es erlauben (siehe Zugriff nach Umgebung), und ebenso der Tarif des Projekts.

cw backup shop --wait                     # a backup now; --format dump for the database alone
cw restart shop --wait
cw runs retry 4812 --wait                 # --now retries even when an automatic retry is due
cw apps update shop --wait                # latest code, rebuilt, the changed modules updated
cw apps update shop --quick               # pull and restart on the same image
cw apps update-modules shop sale stock    # update these modules on the app's database
cw maintenance shop on                    # and off again

Ein Update oder ein Modul-Update einer Produktions-App erstellt zuerst ein Backup, außer Sie fügen --no-backup hinzu. In anderen Umgebungen fügen Sie --backup hinzu, um eines zu erhalten.

cw fragt nach, bevor es handelt, und nennt die App, ihr Projekt und ihre Umgebung. Um eine Produktions-App zu ändern, geben Sie deren Namen ein; ein Backup lässt die App, wie sie ist, daher antworten Sie mit y. Fügen Sie in einem Skript --yes hinzu.

--wait verfolgt den Lauf bis zu seinem Ende, einschließlich des Backups, wenn vorher eines erstellt wird. Während ein Backup läuft, zeigt es, was auf dem Server geschieht, etwa das Dumpen der Datenbank oder das Packen des Archivs. cw backup nennt am Ende die Größe des Backups und wo es liegt.

Ein Token, das Änderungen vornehmen kann, gilt höchstens 30 Tage. Zeigt der Dialog „Neues Token“ keinen Abschnitt Darf ändern, sind Änderungen über die API für Ihr Konto noch nicht freigeschaltet; wenden Sie sich an den Support.

Eine Änderung, die gerade nicht ausgeführt werden kann, wird mit einem Grund abgelehnt, zum Beispiel während ein anderer Lauf auf der App aktiv ist. Die Fehlercodes führen jeden Grund auf und was zu tun ist.

Als root an einem Server anmelden

cw ssh öffnet eine Shell als root auf einem Ihrer Server, von Ihrem eigenen Rechner aus und mit Ihrem eigenen SSH-Schlüssel. CloudWady signiert für diesen Schlüssel ein Zertifikat, das eine Stunde gilt; cw behält es und holt ein neues, sobald es abläuft. Auf root wird nichts hinzugefügt, und das Anmeldeprotokoll des Servers nennt Sie.

cw ssh web-1                      # a root shell on the server web-1
cw ssh web-1 -- df -h             # run one command and come back
cw ssh web-1 --key ~/.ssh/work    # sign in with another of your keys

Voraussetzungen:

• Ihren öffentlichen Schlüssel unter Meine Einstellungen → SSH-Schlüssel (siehe SSH-Schlüssel);
• die Ebene Maintainer oder Admin und Terminalzugriff auf den Server;
• ein Token, bei dem unter Darf ändern das Feld SSH-Zertifikat angekreuzt ist;
• einen mit Härtung anwenden eingerichteten Server, der damit Zertifikate annimmt.

Ab cw 0.13.0 funktioniert ein Schlüssel auch ohne seine .pub-Datei daneben: cw liest den öffentlichen Schlüssel mit ssh-keygen -y, und ein verschlüsselter Schlüssel fragt nach seiner Passphrase.

Ohne --key nimmt cw den ersten von ~/.ssh/id_ed25519, id_ecdsa und id_rsa. Dasselbe Zertifikat bekommen Sie auch im Dashboard: siehe Root-Zugriff. Über MCP verbundene Assistenten bekommen nie eines: Ein Agent erhält nie root.

KI-Assistenten verbinden (MCP)

Mit MCP kann ein Assistent wie Claude, Cursor oder Codex CloudWady selbst aufrufen. cw mcp verbindet ihn mit dem Token, mit dem Sie sich angemeldet haben.

Claude Code:

claude mcp add -s user cloudwady -- cw mcp

Claude Desktop, Cursor und die meisten anderen Assistenten, in ihrer JSON-Konfiguration:

{ "mcpServers": { "cloudwady": { "command": "cw", "args": ["mcp"] } } }

Codex, in seiner TOML-Konfiguration:

[mcp_servers.cloudwady]
command = "cw"
args = ["mcp"]

Ein Assistent, der sich über HTTP verbindet, kann https://www.cloudwady.com/mcp mit dem Header Authorization: Bearer cwk_… verwenden.

Fragen Sie dann in einfachen Worten, zum Beispiel „Was braucht auf CloudWady Aufmerksamkeit?“ oder „Warum ist das letzte Deployment von shop fehlgeschlagen?“. Sie können auch mit den angebotenen Prompts beginnen: triage, why_failed und app_health. Ein Prompt erscheint, wenn Ihr Token lesen darf, was er benötigt.

Der Assistent darf lesen, was Ihr Token lesen darf. Die Änderungen, die Ihr Token erlaubt, erhält er nur, wenn er Ihnen die Frage stellen kann: Bevor etwas läuft, zeigt er Ihnen, was sich ändern wird, und wartet auf Ihre Antwort. Ein Assistent, der Sie nicht fragen kann, erhält nur die Lese-Tools.

Siehe die Referenz der MCP-Tools für jedes Tool.

In Skripten und CI

CW_TOKEN ersetzt das gespeicherte Token und CW_URL die gespeicherte Plattform:

export CW_TOKEN=cwk_…      # aus dem Secret-Speicher Ihrer CI
cw runs --app shop --state error --json
cw attention --json > attention.json || ./notify-team.sh attention.json

Die HTTP-API

Jede Anfrage geht an https://www.cloudwady.com/api/v1/… mit dem Header Authorization: Bearer cwk_…. Eine Antwort ist {"data": …}. Eine Ablehnung ist {"error": {"code": …, "message": …}}, mit einem passenden HTTP-Status.

curl -H "Authorization: Bearer $CW_TOKEN" https://www.cloudwady.com/api/v1/attention

Lesezugriffe verwenden GET. Eine Änderung verwendet POST und benötigt einen Idempotency-Key-Header: einen beliebigen eigenen Wert aus bis zu 100 Buchstaben, Ziffern oder . _ : -.

curl -X POST -H "Authorization: Bearer $CW_TOKEN" \
     -H "Idempotency-Key: backup-shop-2026-10-19" \
     https://www.cloudwady.com/api/v1/apps/1331/backup

Die Antwort ist 202, wenn die Ausführung startet, sonst 200. Senden Sie denselben Schlüssel innerhalb von 24 Stunden erneut, erhalten Sie dieselbe Antwort zurück; nichts läuft doppelt. Die HTTP-API selbst fragt nie nach einer Bestätigung; eine Anfrage läuft, sobald sie angenommen ist.

Die API-Referenz führt jeden Endpunkt auf, und die Fehlercodes jede Ablehnung. Das OpenAPI-Dokument finden Sie unter /api/v1/openapi.json. Erfolgreiche Antworten enthalten X-Token-Expires-At, sodass ein Skript warnen kann, bevor sein Token nicht mehr gilt.

Limits & Sicherheit

• Ihr Zugriff, nicht mehr. Ein Token liest nur die Namespaces, die Sie ihm gegeben haben, und sieht dort, was das Dashboard Ihrer Stufe zeigt.
• Nur lesend, sofern Sie nichts anderes festlegen. Ein Token nimmt nur Änderungen vor, die Sie dafür angehakt haben, und gilt dann höchstens 30 Tage.
• Secrets bleiben draußen. Passwörter, Schlüssel und Zugangsdaten sind nie Teil einer Antwort, und Protokollzeilen werden maskiert.
• Ratenlimits.
  • 120 Anfragen pro Minute je Token und 300 je Benutzer;
  • höchstens 10 Änderungen pro Minute und Token.
  Jenseits eines Limits lautet die Antwort 429 mit Retry-After; cw logs --follow wartet und macht dann weiter.
• Tokens. Gehasht gespeichert, nur einmal angezeigt und mit Ablauf zu dem von Ihnen gewählten Datum. Wenn eines möglicherweise offengelegt wurde, widerrufen Sie es in Meine Einstellungen.