Runabot CLI#

The runabot command-line tool lets you manage workloads, addons, and account usage from a terminal or script. Use it interactively, automate tasks in CI/CD pipelines, or let your AI agent manage Runabot resources on your behalf.

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://int.runa.bot/downloads/install.sh | sh

# Global system installation (installs to /usr/local/bin/):
curl -fsSL https://int.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#

Login#

Use the same command from a local or remote terminal:

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

The CLI opens your browser when available and prints a verification URL and user code. Open the URL in a browser on any device, enter the code if prompted, and approve the login. The CLI finishes automatically and saves your session credentials in your local configuration.

On the consent screen, choose which permissions to grant the CLI. Grant only the access you need; changing spending limits requires a separate optional permission.

You can revoke CLI access at any time in User Settings under Authorized Applications. Select the CLI application and click Revoke.

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://int.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, table, or text)
runabot version
runabot version -o json
runabot version -o table

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

Output Formatting#

Commands output structured JSON by default for use in scripts. For human-readable terminal output, pass -o table or --output table:

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

Account Network Usage#

# Current UTC month through now
runabot account network-usage

# A selected interval (no longer than 31 days)
runabot account network-usage --start 2026-09-01T00:00:00Z --end 2026-09-02T00:00:00Z

The command returns account upload/download byte totals, hourly workload periods, measurement freshness, and a status. Requested bounds are rounded to complete UTC hours. The default range is the current UTC month through now. Counts include internal traffic and supporting services; they are not billing totals or unique internet traffic.

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#

Addon allocation minimums are listed in the addon source catalog. The catalog also declares whether CPU, memory, disk, or network allocation is changeable. Resources marked as fixed cannot be changed.

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#

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"

Retry creation with the same key to avoid duplicate workloads. Creation responses may only acknowledge the request; use bot list or addon list to find the resource’s generated name and namespace before subsequent operations.

5. Configuration & Environment#

The CLI stores clusters, authenticated users, and named contexts in a YAML file:

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

Use runabot auth contexts to list contexts and --context <name> to select one for a command. The current context is used by default.

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.yaml bot list

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

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

Billing and purchase limits#

runabot account quota is read-only and includes current allocations, spending limits, traffic-credit balance, purchase-event history, and the monthly payment projection.

Changing limits requires the optional purchase_limits OAuth permission:

runabot account set-limits --allocation-weekly-eur 5 --traffic-weekly-eur 1

The permission is unchecked by default on the consent screen. Without it, the CLI can inspect billing information but the API rejects limit changes.