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#

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#

Git-Proxy-Verwaltung#

Git Proxy bietet unter runabot addon git-proxy eine ressourcenorientierte CLI. Jeder Befehl wählt die installierte Addon-Instanz ausdrücklich aus. Beim Lesen von Zugangsdaten werden nur Metadaten zurückgegeben; Geheimnisse werden nur beim Erstellen, Aktualisieren oder Rotieren angenommen.

Aktualisierungen und Löschungen benötigen die aktuelle --version. Mit --secret-action preserve, replace oder clear ist die Behandlung von Geheimnissen eindeutig. Mutationen unterstützen außerdem die globalen Flags --idempotency-key und --request-id.

Beachten Sie, dass access check den Repository-Pfad erwartet, wie ihn der Git Proxy sieht: <proxy-path-prefix>/<upstream-repository-path> (z. B. github_runabot/run-a-bot/mcpproxy-go). Bei exakten Pfadregeln wird direkt gegen das Pfadmuster der Regel geprüft; hängen Sie kein .git an, es sei denn, Ihr Regel-Muster enthält explizit .git.

MCPProxy-Verwaltung#

MCPProxy bietet unter runabot addon mcpproxy eine direkte Verwaltungs-CLI. Jeder Befehl nennt ausdrücklich die installierte Addon-Instanz. Die CLI verwaltet Upstream-Server, Tool-Freigaben, schreibgeschützte Geheimnisse, Zugriffsprofile, begrenzte Tokens und Bot-Zuweisungen. Lesebefehle geben niemals Header-, Umgebungs- oder Geheimniswerte zurück; neue und rotierte Tokenwerte werden einmalig ausgegeben.

runabot addon mcpproxy upstream create mcpproxy-u1a1 docs \
  --protocol streamable-http --url https://mcp.example.com/mcp
runabot addon mcpproxy profile create mcpproxy-u1a1 research \
  --upstream docs --tool docs=search
runabot addon mcpproxy assign mcpproxy-u1a1 research bot-u1b1
runabot addon mcpproxy access effective mcpproxy-u1a1 bot-u1b1

SSH-JumpHost-Verwaltung#

Der SSH JumpHost bietet unter runabot addon ssh eine ressourcenorientierte CLI. Sie akzeptiert ausschließlich öffentliche OpenSSH-Schlüssel. Runabot nimmt keine privaten Schlüssel an, erzeugt oder speichert sie nicht und gibt sie nicht zurück.

Zum Ersetzen oder Entfernen eines Schlüssels ist dessen aktuelle --version erforderlich. Beim Hinzufügen oder Ersetzen muss genau eines von --public-key oder --public-key-file angegeben werden. Vergleichen Sie vor einem unbeaufsichtigten Verbindungsaufbau einen Fingerprint aus connection mit dem Schlüssel, den der zurückgegebene knownHostsCommand ermittelt.

runabot addon ssh key add ssh-u1a1 \
  --name automation --public-key-file ~/.ssh/id_ed25519.pub
runabot addon ssh assignment assign ssh-u1a1 bot-u1b1
runabot addon ssh reachable ssh-u1a1
runabot addon ssh connection ssh-u1a1 bot-u1b1

Sicherungen & Wiederherstellung#

Cluster & Administration#

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#

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