turbopress CLI installieren und einrichten
Mit der turbopress CLI steuerst du die Hosting-API vom Terminal oder aus deiner CI-Pipeline: Websites auflisten, Backups anstoßen, Caches leeren und statische AI-Launch-Sites veröffentlichen. Die CLI ist ein Node.js-Programm und läuft unter Linux, macOS und Windows.
Voraussetzungen
- Node.js 22 oder neuer. Prüfe die Version mit
node --version. Ist sie älter oder Node.js fehlt, installiere die aktuelle LTS-Version von nodejs.org oder über einen Versionsmanager wie nvm. - Ein API-Token mit den Rechten, die du brauchst. Wie du es erstellst, steht in API-Token für dein Hosting erstellen und widerrufen.
Installieren
Das Paket heißt @turbopress-de/cli und liegt auf npm. Installiere es global:
npm install --global @turbopress-de/cli
turbopress --version
Die Ausgabe zeigt die installierte Version, zum Beispiel 0.5.0. Der Befehl heißt turbopress.
Ohne globale Installation startest du die CLI direkt mit npx:
npx @turbopress-de/cli sites list --json
Für CI und reproduzierbare Läufe gibst du die Version fest an, zum Beispiel npx @turbopress-de/cli@0.5.0 …. Zum Aktualisieren nutzt du npm update --global @turbopress-de/cli, zum Entfernen npm uninstall --global @turbopress-de/cli.
Die Veröffentlichung auf npm ist mit einer Herkunftsbestätigung (Provenance) aus dem öffentlichen Build signiert. Der Quellcode liegt unter MIT-Lizenz auf GitHub.
Token bereitstellen
Die CLI liest das Token ausschließlich aus der Umgebungsvariable TURBOPRESS_API_TOKEN. Es gibt bewusst keine Option, kein Token-File und keinen anderen Endpunkt. So landet das Secret nicht in der Befehlszeile, im Shell-Verlauf oder in Logs.
Unter Linux und macOS fragst du das Token verdeckt ab:
read -r -s -p 'API-Token: ' TURBOPRESS_API_TOKEN && export TURBOPRESS_API_TOKEN
In PowerShell 7 geht das so:
$env:TURBOPRESS_API_TOKEN = Read-Host -MaskInput 'API-Token'
Die Variable gilt nur für das aktuelle Terminalfenster. Schreibe das Token nicht in Skripte, Repositories oder Dotfiles. In CI legst du es als maskiertes Secret des Dienstes an und gibst es nur dem Schritt mit, der es braucht.
Erster Aufruf
turbopress sites list --json
Die Antwort listet deine Websites mit ihrer site_id. Diese ID brauchst du für alle weiteren Befehle. Mit --json gibt die CLI genau einen JSON-Wert aus, den du mit Werkzeugen wie jq weiterverarbeiten kannst. Ohne --json erscheint die Antwort in lesbarer Form.
Wichtige Befehle
| Befehl | Zweck |
|---|---|
turbopress sites list |
Websites auflisten |
turbopress sites show --site ID |
Details zu einer Website |
turbopress backups create --site ID --wait |
WordPress-Backup anstoßen und abwarten |
turbopress cache purge --site ID --scope page --wait |
Cache leeren (page, object oder all) |
turbopress deployments create --site ID |
Deployment für eine AI-Launch-Site beginnen |
turbopress operations get ID |
Status eines Jobs lesen |
turbopress operations list |
Deine letzten Jobs auflisten, auch wenn du eine Job-ID verloren hast |
turbopress backups list --site ID |
Backups mit Datum und Größe anzeigen |
turbopress backups delete --site ID --backup BACKUP_ID --wait |
Ein Backup dauerhaft löschen (eigenes Recht backups:delete, siehe Backups anzeigen und löschen) |
turbopress updates list --site ID |
Offene Plugin- und Theme-Updates anzeigen (Recht updates:read) |
turbopress updates run --site ID --plugin SLUG --wait |
Plugins und Themes mit Sicherheitsbackup aktualisieren (bis zu fünf, Recht updates:run), siehe Updates und Staging |
turbopress staging delete --site LIVE_ID --confirm STAGING_HOST --wait |
Die Staging-Kopie einer Live-Site dauerhaft löschen (Recht staging:delete) |
turbopress token |
Rechte, Sites und Ablauf deines Tokens anzeigen (praktisch bei einem 403) |
turbopress status |
Zeigt, ob die API erreichbar ist oder im Wartungsfenster steht. Braucht kein Token. |
Alle Befehle und Optionen listet das README im GitHub-Repository. Mit --wait wartet die CLI, bis der Job succeeded meldet. Der Standard-Timeout beträgt 600 Sekunden, mit --timeout SEKUNDEN änderst du ihn.
Rückgabecodes
Die CLI beendet sich mit einem Code, den du in Skripten und CI auswerten kannst:
| Code | Bedeutung |
|---|---|
| 0 | Erfolg |
| 1 | API- oder Netzwerkfehler oder fehlgeschlagener Job |
| 2 | Ungültiger Befehl oder ungültige Option |
| 3 | Token fehlt oder abgelehnt, oder keine Berechtigung |
| 4 | Zeitüberschreitung oder unklarer Jobausgang |
Bei Code 1 oder 4 nach einem Schreibaufruf nennt die CLI den verwendeten Idempotency-Key und, falls bekannt, die Job-ID. Wiederhole den Befehl mit demselben Key und denselben Parametern, wenn du nicht weißt, ob der Aufruf angekommen ist. Mit einem neuen Key kann eine zweite Wirkung entstehen.
Schreibaufrufe wiederholt die CLI ab Version 0.2.0 nur in drei Fällen selbst, in denen die API garantiert nichts angelegt hat: bei 429 mit rate_limited oder queue_full und bei 503 mit api_draining (Wartungsfenster). Sie wartet dann die Zeit aus Retry-After ab (höchstens 300 Sekunden je Wartezeit), versucht es bis zu dreimal mit demselben Key und meldet jede Wartezeit auf stderr. Ohne --wait begrenzt die CLI die Wartezeit insgesamt auf 600 Sekunden, mit --wait gilt dein --timeout. Alle anderen Fehler, etwa das Tageslimit, andere 503-Antworten oder Netzwerkfehler, wiederholt sie nicht.
Häufige Probleme
command not found: turbopress: Der npm-Ordner für globale Programme liegt nicht in deinemPATH.npm config get prefixzeigt den Ordner an; das Unterverzeichnisbin(unter Windows der Ordner selbst) muss imPATHstehen. Alternativ nutzt dunpx.- Fehlermeldung zur Node-Version: Aktualisiere Node.js auf Version 22 oder neuer.
- Exit-Code 3: Das Token fehlt in der Umgebungsvariable, ist abgelaufen oder widerrufen oder hat das Recht für diese Aktion nicht. Prüfe das unter API & KI-Zugriff im Panel.
- Weitere Fehler: Fehler und Timeouts
Weitere Anleitungen
API-Token erstellen · Backups anzeigen und löschen · Updates und Staging per API · WordPress-Cache per API leeren · Statische AI-Launch-Site bereitstellen · OpenAPI-Referenz