Runabot CLI#

The runabot command-line tool provides a direct, scriptable interface to the Runabot ConnectRPC API. It is designed for developers, CI/CD pipelines, and autonomous coding agents (such as Claude Code, Cursor, Codex, OpenClaw, and Hermes).

1. Download & Installation#

You can download pre-built binaries for Linux, macOS, and Windows (supporting both amd64 and arm64) directly from the Downloads Page.

Quick Install#

# User-level installation (installs to ~/.local/bin/):
curl -fsSL https://runa.bot/downloads/install.sh | sh

# Global system installation (installs to /usr/local/bin/):
curl -fsSL https://runa.bot/downloads/install.sh | sudo sh

Or download the binary manually from the Downloads Page, make it executable, and move it into your PATH:

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

2. Authentication#

Interactive Browser Login#

To log in interactively using OAuth2 (Authorization Code + PKCE against Hydra):

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

This will open your browser for authentication and store your session credentials securely in your local configuration.

Device Authorization Flow (Recommended for Headless / Remote)#

For remote SSH sessions, cloud workstations, or environments where a local browser cannot receive loopback callbacks, use the RFC 8628 Device Authorization Flow:

runabot auth login --device

The CLI prints a verification URL and an 8-character user code (e.g. WDJB-MJHT). Open the URL on any device, enter the code, and approve. The CLI will automatically receive the session tokens and finish logging in.

Manual PKCE Code Flow#

Alternatively, perform standard PKCE authorization and paste the authorization code or redirect URL manually:

runabot auth login --manual

Direct Token Login#

runabot auth login --token "<your-access-token>"

Agent / CI/CD Mode (Environment Variables)#

For automated coding agents, container workloads, or CI/CD pipelines, you can provide an access token and base URL via environment variables:

export RUNABOT_BASE_URL="https://runa.bot"
export RUNABOT_TOKEN="<your-access-token>"

Verify Authentication#

runabot auth whoami

3. Command Reference#

Version & Build Metadata#

# Print detailed version and build metadata (JSON, YAML, or text)
runabot version
runabot version -o json
runabot version -o table

# Print only the version string
runabot version --short
runabot --version

Output Formatting#

By default, all commands output structured protobuf JSON for easy parsing by AI agents and scripts. For human-readable terminal output, pass -o table or --output table:

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

Bot Management#

Declarative Workload Application (apply)#

Deploy or update bots and addons declaratively using YAML manifests:

# Apply a single or multi-document workload manifest
runabot apply -f workload.yaml

# Apply directly from standard input (e.g. generated by an agent)
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 Database"
  parameters:
    storage_size: "10Gi"
EOF

Addon Management#

Git Proxy management#

Git Proxy has a resource-oriented CLI under runabot addon git-proxy. Every command selects the installed addon instance explicitly. Credential reads return metadata only; secret values are accepted only by create, update, and rotate.

Updates and deletes require the current --version. Use --secret-action preserve, replace, or clear to make secret handling explicit. Mutations can also use the global --idempotency-key and --request-id flags. Secret values are read from files that are private to the current user. Pass - as a secret file to read that value from standard input instead.

Note that access check expects the repository path as seen by Git Proxy: <proxy-path-prefix>/<upstream-repository-path> (for example, github_runabot/run-a-bot/mcpproxy-go). For exact path rules, matching matches against the rule’s path pattern directly; do not append .git unless your path rule pattern explicitly defines .git.

umask 077
printf '%s' "$GIT_TOKEN" > ./git-token
runabot addon git-proxy profile create git-proxy-u1a1 --name automation
runabot addon git-proxy credential create git-proxy-u1a1 \
  --provider generic_https --proxy-path-prefix forgejo \
  --host git.example.com --auth-type username_token \
  --username bot --token-file ./git-token --secret-action replace
runabot addon git-proxy path-rule create git-proxy-u1a1 cred_forgejo \
  --path team/repo --pattern-type exact --grant automation=read-write
runabot addon git-proxy access check git-proxy-u1a1 bot-1 forgejo/team/repo \
  --operation write

MCPProxy management#

MCPProxy has a direct management CLI under runabot addon mcpproxy. Every command names the installed addon instance. The CLI manages upstream servers, tool approval, write-only secrets, access profiles, scoped tokens, and bot assignments. Read commands never return header, environment, or secret values; new and rotated token values are returned once.

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 management#

SSH JumpHost has a resource-oriented CLI under runabot addon ssh. It accepts OpenSSH public keys only; Runabot never accepts, generates, stores, or returns private key material.

Replacing or removing a key requires its current --version. Supply exactly one of --public-key or --public-key-file when adding or replacing a key. Before unattended use, compare a fingerprint from connection with the key collected by the returned knownHostsCommand.

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

Backups & Restores#

Cluster & Administration#

4. Idempotency & Safe Agent Retries#

Autonomous agents operating over network boundaries or timeouts can safely retry mutating operations without creating duplicate workloads by passing an idempotency key or request ID:

# Safely retry creation with a deterministic key
runabot bot create --name worker-agent --chart openclaw --idempotency-key "task-20260825-worker" --wait
runabot addon create openobserve --idempotency-key "task-20260825-logs"

If an operation with the same idempotency key was already completed or in progress, the API immediately returns the existing resource without allocating duplicate namespaces.

5. Configuration & Environment#

The CLI reads configuration and environment variables from a dotenv file:

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

You can customize the configuration path with the --config flag or the RUNABOT_CONFIG environment variable:

# Point to a custom config file
runabot --config ./staging.env bot list

# Or via environment variable
export RUNABOT_CONFIG=/path/to/my-cluster.env

Supported Configuration Variables & Flags#

6. Integration with Local Coding Agents#

Runabot CLI outputs structured JSON by default, making it easy to integrate into LLM coding agent toolchains (Claude Code, Cursor, Codex, OpenClaw, Hermes):

# Example 1: Inspect parameter schema before creating an addon
runabot addon source describe olla -o json

# Example 2: Synchronously create and await bot readiness
runabot bot create --name data-pipeline --chart openclaw --wait --timeout 3m

# Example 3: Check runtime events when diagnosing failures
runabot bot events data-pipeline