Runabot CLI#

Das Kommandozeilenwerkzeug runabot bietet eine direkte, skriptfähige Schnittstelle zur ConnectRPC-API von Runabot. Es ist für Entwickler, CI/CD-Pipelines und autonome Coding-Agenten (wie Claude Code, Cursor, Codex, OpenClaw und Hermes) konzipiert.

1. Download & Installation#

Vorkompilierte Binärdateien für Linux, macOS und Windows (jeweils für amd64 und arm64) stehen direkt auf der Downloads-Seite zur Verfügung.

Schnellinstallation#

# Benutzerinstallation (installiert nach ~/.local/bin/):
curl -fsSL https://runa.bot/downloads/install.sh | sh

# Globale Systeminstallation (installiert nach /usr/local/bin/):
curl -fsSL https://runa.bot/downloads/install.sh | sudo sh

Alternativ können Sie die Datei manuell von der Downloads-Seite herunterladen und ausführbar machen:

chmod +x runabot
sudo mv runabot /usr/local/bin/

2. Authentifizierung#

Interaktive Browser-Anmeldung#

Für die interaktive Anmeldung mittels OAuth2 (Authorization Code + PKCE gegen Hydra):

runabot auth login --base-url https://runa.bot

Hierbei öffnet sich Ihr Standardbrowser zur Bestätigung. Die Sitzungsdaten werden lokal sicher gespeichert.

Geräte-Autorisierungs-Flow (Empfohlen für Headless / Remote)#

Für Remote-SSH-Sitzungen, Cloud-Workstations oder Umgebungen ohne lokalen Browser verwenden Sie den RFC 8628 Device Authorization Flow:

runabot auth login --device

Die CLI gibt eine Bestätigungs-URL und einen 8-stelligen Benutzercode aus (z. B. WDJB-MJHT). Öffnen Sie die URL auf einem beliebigen Gerät, geben Sie den Code ein und bestätigen Sie. Die CLI empfängt die Token automatisch.

Manuelle PKCE-Code-Anmeldung#

Alternativ können Sie die Standard-PKCE-Autorisierung durchführen und den Code bzw. die Redirect-URL manuell einfügen:

runabot auth login --manual

Direkte Token-Anmeldung#

runabot auth login --token "<ihr-zugriffstoken>"

Agenten- & CI/CD-Modus (Umgebungsvariablen)#

Für automatisierte Coding-Agenten oder CI/CD-Pipelines können Zugriffstoken und Basis-URL über Umgebungsvariablen übergeben werden:

export RUNABOT_BASE_URL="https://runa.bot"
export RUNABOT_TOKEN="<ihr-zugriffstoken>"

Anmeldestatus prüfen#

runabot auth whoami

3. Befehlsübersicht#

Version & Build-Metadaten#

# Detaillierte Versions- und Build-Informationen (JSON, YAML oder Text) ausgeben
runabot version
runabot version -o json
runabot version -o table

# Nur die Versionsnummer ausgeben
runabot version --short
runabot --version

Ausgabeformatierung#

Standardmäßig liefern alle Befehle strukturiertes Protobuf-JSON für die problemlose Verarbeitung durch KI-Agenten und Skripte. Für eine übersichtliche Konsolentabelle übergeben Sie -o table oder --output table:

runabot addon list -o table
runabot bot list -o table

Bot-Verwaltung#

Befehl	Beschreibung
`runabot bot list`	Alle Bots im eigenen Account auflisten
`runabot bot status <name> [--namespace <ns>]`	Detaillierten Status, Lifecycle, Helm-Status und Addon-Bindungen eines Bots anzeigen
`runabot bot create --name <name> --chart <chart> [--wait] [--timeout 5m]`	Neue Bot-Instanz bereitstellen (z. B. `openclaw` oder `ironclaw`); optional auf Bereitschaft warten
`runabot bot wait <name> [--for ready\|running\|stopped\|deleted] [--timeout 5m]`	Synchron blockieren, bis ein Bot den gewünschten Zustand erreicht
`runabot bot events <name> [--namespace <ns>]`	Kubernetes-Ereignisse eines Bots auflisten
`runabot bot shell <name> --namespace <ns>`	Interaktives Terminal im Bot-Pod öffnen
`runabot bot upgrade <name> --namespace <ns>`	Aktualisierung auf die neueste Chart-Version ausführen
`runabot bot delete <name> --namespace <ns>`	Bot-Instanz löschen

Deklarative Bereitstellung (`apply`)#

Bots und Addons deklarativ mittels YAML-Manifesten erstellen oder aktualisieren:

# Manifest (einzelnes oder mehrere Dokumente) anwenden
runabot apply -f workload.yaml

# Direkt über Standardeingabe übergeben (z. B. durch KI-Agenten generiert)
cat <<EOF | runabot apply -f -
apiVersion: runabot.runabot.de/v1
kind: BotInstance
metadata:
  name: clawdius-dev
spec:
  displayName: "Clawdius Developer Agent"
  chartName: openclaw
---
apiVersion: runabot.runabot.de/v1
kind: Addon
metadata:
  name: main-db
spec:
  sourceRef: cnpg
  displayName: "PostgreSQL Datenbank"
  parameters:
    storage_size: "10Gi"
EOF

Addon-Verwaltung#

Befehl	Beschreibung
`runabot addon source list`	Verfügbare Addon-Quellen im Katalog auflisten
`runabot addon source describe <name>`	Vollständige Parameter-Schemas (Typen, Standardwerte, Ressourcen-Referenzen) und UI-Features einsehen
`runabot addon list`	Installierte Addons im Account anzeigen (sensible Zugangsdaten ausgeblendet)
`runabot addon create <source_ref> --param key=value`	Addon installieren und konfigurieren
`runabot addon update <name> --param key=value`	Parameter, Anzeigenamen oder Firewall-Freigaben aktualisieren
`runabot addon upgrade <name>`	Installiertes Addon aktualisieren
`runabot addon delete <name>`	Installiertes Addon entfernen

Sicherungen & Wiederherstellung#

Befehl	Beschreibung
`runabot backup list`	Velero-Sicherungen anzeigen
`runabot backup create --namespace <ns>`	Snapshot-Sicherung eines Bot- oder Addon-Namespaces erstellen
`runabot backup delete <name>`	Sicherung löschen

Cluster & Administration#

Befehl	Beschreibung
`runabot cluster info`	Status der Cluster-Infrastruktur einsehen
`runabot admin users list`	(Nur Administratoren) Registrierte Benutzer auflisten

4. Idempotenz & Ausfallsichere Wiederholungen#

Autonome Agenten können bei Netzwerk-Timeouts fehlgeschlagene oder unterbrochene Operationen gefahrlos mit einem Idempotenz-Schlüssel wiederholen, ohne doppelte Ressourcen zu erzeugen:

# Sichere Wiederholung mit deterministischem Schlüssel
runabot bot create --name worker-agent --chart openclaw --idempotency-key "task-20260825-worker" --wait
runabot addon create openobserve --idempotency-key "task-20260825-logs"

Wenn eine Operation mit demselben Idempotenz-Schlüssel bereits ausgeführt wurde oder aktiv ist, gibt die API sofort die bestehende Ressource zurück.

5. Konfiguration & Umgebung#

Das CLI liest Konfigurations- und Umgebungsvariablen aus einer Dotenv-Datei:

Linux / macOS: ~/.config/runabot/runabot.env (oder $XDG_CONFIG_HOME/runabot/runabot.env)
Windows: %APPDATA%\runabot\runabot.env

Sie können den Konfigurationspfad mit dem Flag --config oder der Umgebungsvariablen RUNABOT_CONFIG anpassen:

# Benutzerdefinierte Konfigurationsdatei verwenden
runabot --config ./staging.env bot list

# Oder über Umgebungsvariable
export RUNABOT_CONFIG=/pfad/zu/mein-cluster.env

Unterstützte Variablen & Flags#

Variable / Flag	Beschreibung	Standard
`RUNABOT_BASE_URL` / `--base-url`	API-Basis-URL für Ihren Runabot-Cluster	`https://runa.bot`
`RUNABOT_PROFILE` / `--profile`	Zu verwendender Standard-Profilname	Aktives Profil in `config.json`
`RUNABOT_OUTPUT` / `-o, --output`	Standard-Ausgabeformat (`json`, `table`, `text`)	`json`
`--idempotency-key`	Stabiler Idempotenz-Schlüssel für Mutationen	Optional
`--request-id`	Tracking-UUID für API-Aufrufe	Optional

6. Integration mit lokalen Coding-Agenten#

Die Runabot CLI liefert standardmäßig strukturiertes JSON, was die Integration in LLM-Coding-Agenten (Claude Code, Cursor, Codex, OpenClaw, Hermes) erleichtert:

# Beispiel 1: Parameter-Schema vor dem Erstellen eines Addons prüfen
runabot addon source describe olla -o json

# Beispiel 2: Bot synchron erstellen und auf Betriebsbereitschaft warten
runabot bot create --name data-pipeline --chart openclaw --wait --timeout 3m

# Beispiel 3: Laufzeitereignisse bei Fehlersuche abfragen
runabot bot events data-pipeline