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#

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

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#

Command	Description
`runabot bot list`	List all running bots in your account
`runabot bot status <name> [--namespace <ns>]`	Show detailed health, lifecycle, Helm status, and addon bindings for a bot
`runabot bot create --name <name> --chart <chart> [--wait] [--timeout 5m]`	Deploy a new bot instance; optionally wait for ready state
`runabot bot wait <name> [--for ready\|running\|stopped\|deleted] [--timeout 5m]`	Block synchronously until a bot reaches the target condition
`runabot bot events <name> [--namespace <ns>]`	Stream/list Kubernetes deployment and runtime events for a bot
`runabot bot shell <name> --namespace <ns>`	Open an interactive raw WebSocket terminal inside a bot pod
`runabot bot upgrade <name> --namespace <ns>`	Trigger an upgrade to the latest chart version
`runabot bot delete <name> --namespace <ns>`	Terminate and remove a bot instance

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#

Command	Description
`runabot addon source list`	List available addon sources in the catalog
`runabot addon source describe <name>`	Show full details, parameter schema (types, defaults, resource references), and UI features
`runabot addon list`	List installed addons in your account (sensitive fields omitted)
`runabot addon create <source_ref> --param key=value`	Install and configure an addon
`runabot addon update <name> --param key=value`	Update configuration parameters, display name, or firewall settings
`runabot addon upgrade <name>`	Upgrade an installed addon
`runabot addon delete <name>`	Delete an installed addon

Backups & Restores#

Command	Description
`runabot backup list`	List Velero backups
`runabot backup create --namespace <ns>`	Create a snapshot backup of a bot or addon namespace
`runabot backup delete <name>`	Delete a backup

Cluster & Administration#

Command	Description
`runabot cluster info`	View cluster infrastructure status
`runabot admin users list`	(Admins only) List registered users and permissions

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#

Variable / Flag	Description	Default
`RUNABOT_BASE_URL` / `--base-url`	API base URL for your Runabot cluster	`https://runa.bot`
`RUNABOT_PROFILE` / `--profile`	Default profile name to use	Active profile in `config.json`
`RUNABOT_OUTPUT` / `-o, --output`	Default output format (`json`, `table`, `text`)	`json`
`--idempotency-key`	Stable idempotency key for mutations	Optional
`--request-id`	Tracking UUID for requests	Optional

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