RunOS CLI

The RunOS CLI provides a powerful command-line interface for managing your clusters, services, and infrastructure. It communicates with the same REST API used by the RunOS Console, giving you full control over your infrastructure from the terminal.

Installation

Download and install the CLI for your platform:

# macOS / Linux
curl -fsSL https://get.beta.runos.com/cli.sh | bash

# Windows
irm https://get.beta.runos.com/cli.ps1 | iex

After installation, the runos command will be available in your terminal.

Authentication

Before using the CLI, you need to authenticate with your RunOS account:

runos login

This opens your browser for authentication via Google, GitHub, or email/password. The CLI securely stores your credentials locally at ~/.runos/config.json.

Dynamic Commands

CLI commands are dynamically generated and automatically kept in sync with the RunOS API. New commands and features become available automatically as the CLI updates its local cache.

If you're missing a command, you can force an update:

runos manifest update

Note that documentation may occasionally lag behind the latest available commands.

Command Structure

Commands follow a hierarchical pattern:

runos <resource> <subresource> <action> [flags]

Examples

List all clusters:

runos clusters list

Show a specific service:

runos services postgresql show --id abc12

Create a PostgreSQL instance with a read replica and follow the job:

runos services postgresql add --name my-database-2 --replicas 2 --follow

Delete a service:

runos services valkey delete --id xyz99

Common Flags

These flags are available across most commands:

Flag	Description
--cid	Specify cluster ID (overrides default)
--json	Output in JSON format
--follow	Follow job progress until completion
--help	Show help for command

Setting a Default Cluster

Instead of passing --cid with every command, set a default cluster:

runos clusters default i4y

View your current default by running the command without arguments:

runos clusters default

Output Formats

Table Output (Default)

The CLI formats output as readable tables:

runos services postgresql list

ID     NAME             TYPE        VERSION  REPLICAS  RESOURCEREQUIREMENTCLASSID  CREATEDAT
-------------------------------------------------------------------------------------------------------------
eu7gd  System Instance  postgresql  17.6     1         postgresql.c0.tiny          2026-02-04T07:27:18.724Z

JSON Output

For scripting or programmatic access, use the --json flag:

runos services postgresql list --json

[
  {
    "aid": "f2c7v",
    "cid": "kea",
    "cpuLimitMc": 200,
    "cpuRequestMc": 100,
    "createdAt": "2026-02-04T07:27:18.724Z",
    "flags": {
      "apacheAge": false,
      "documentDBExtension": false,
      "hasFerretDBData": false,
      "vector": false
    },
    "id": "eu7gd",
    "isSystemInstance": false,
    "memoryLimitMb": 512,
    "memoryRequestMb": 256,
    "name": "System Instance",
    "nodeAffinityTagIds": [],
    "osid": "postgresql-eu7gd",
    "replicas": 1,
    "resourceRequirementClassId": "postgresql.c0.tiny",
    "type": "postgresql",
    "updatedAt": "2026-02-04T07:27:18.724Z",
    "version": "17.6"
  }
]

Long-Running Operations

Operations like creating services or modifying clusters may take time to complete. These operations return a job ID that you can monitor.

Follow job progress:

runos services postgresql add --name my-db --follow

The --follow flag streams the job's progress in real-time until the operation completes.

List recent jobs:

runos jobs list

ID                                    NAME               TYPE               STATUS     PROGRESS  CURRENTSTEP                           CREATEDAT
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
3f1b0efc-3fa7-49aa-a797-c0b11859f4f6  Delete PostgreSQL  postgresql.delete  completed  3/3       Delete PostgreSQL from database       2026-02-04T12:46:48.543Z
676cb03a-9ea9-46fd-aabb-dfae61e4f68e  Create PostgreSQL  postgresql.create  completed  6/6       Apply PostgreSQL manifest to cluster  2026-02-04T12:44:10.292Z

Check job status:

runos jobs show 3f1b0efc-3fa7-49aa-a797-c0b11859f4f6

id         : 3f1b0efc-3fa7-49aa-a797-c0b11859f4f6
name       : Delete PostgreSQL
type       : postgresql.delete
status     : completed
progress   : 3/3
currentStep: Delete PostgreSQL from database

Available Services

The CLI currently supports:

• PostgreSQL - Managed PostgreSQL databases
• MySQL - MySQL-compatible databases
• Valkey - Redis-compatible caching
• MinIO - S3-compatible object storage

We're actively working on migrating all RunOS services available in the Console to the CLI and MCP.

Cluster Management

Manage your Kubernetes clusters:

# List clusters
runos clusters list

# Show cluster details
runos clusters show --cid <cluster-id>

# Set default cluster
runos clusters default <cluster-id>

Node Management

Manage nodes within your clusters:

# List nodes
runos nodes list

# Show node details
runos nodes show <node-id>

Configuration

The CLI stores configuration in ~/.runos/:

File	Purpose
config.json	Authentication tokens and settings
manifest.json	Cached command definitions

Troubleshooting

Command Not Found

If a command isn't available, update your manifest:

runos manifest update

Authentication Errors

Re-authenticate if your session has expired:

runos login

Best Practices

1. Use --json for scripts - JSON output is stable and parseable
2. Set a default cluster - Avoid repeating --cid in every command
3. Update manifest regularly - Get access to new commands and features

Note on Documentation Currency

Because CLI commands are dynamically generated from the manifest, the available commands may change as RunOS evolves. If you encounter a command that isn't documented here, use:

runos <command> --help

Or explore the manifest directly:

cat ~/.runos/manifest.json | jq '.commands[].command'