Runloop CLI

The Runloop CLI (rli) provides both an interactive terminal UI and traditional CLI commands for managing your Runloop resources.

npm Package

@runloop/rl-cli

GitHub Repository

runloopai/rl-cli

Installation

npm install -g @runloop/rl-cli

yarn global add @runloop/rl-cli

pnpm add -g @runloop/rl-cli

Setup

Configure your API key:

export RUNLOOP_API_KEY=your_api_key_here

Get your API key from the Settings page in the Runloop Dashboard.

Quick Start

Interactive Mode
CLI Mode

Launch the interactive UI with a beautiful terminal interface:

rli

Navigate with arrow keys, select with Enter, and manage all your resources visually.

Search Devboxes

Press / to search and filter through your devboxes by name or ID.

SSH to Devbox

From the interactive menu, select a devbox and choose SSH to open a secure shell session directly into your devbox. The CLI handles all the SSH key setup and connection details automatically.

Use traditional commands for scripting and automation:

# List all devboxes
rli devbox list --output json

Example Output

[
  {
    "id": "dbx_1234567890",
    "name": "my-devbox",
    "status": "running",
    "blueprint_id": "bpt_abcdef"
  }
]

# Create a new devbox
rli devbox create --name my-devbox --blueprint my-blueprint

Example Output

dbx_1234567890

# Execute a command in a devbox
rli devbox exec dbx_1234567890 echo "Hello World"

Example Output

Hello World

# SSH into a devbox
rli devbox ssh dbx_1234567890

Command Groups

Devbox

Create, manage, and interact with devboxes

Benchmark Job

Run and manage orchestrated benchmarks

Snapshot

Create and manage devbox snapshots

Blueprint

Manage reusable devbox templates

Object

Upload and manage file objects

Command Reference

Devbox Commands

create

Create a new devbox

rli devbox create

string

Devbox name

string

Snapshot ID to use (alias: —snapshot)

string

Snapshot ID to use

string

Blueprint name or ID to use

string

Resource size (X_SMALL, SMALL, MEDIUM, LARGE, X_LARGE, XX_LARGE)

string

Architecture (arm64, x86_64)

string

Entrypoint command to run

string[]

Initialization commands to run on startup

string[]

Environment variables (format: KEY=value)

string[]

Secrets to inject as environment variables (format: ENV_VAR=SECRET_NAME)

string[]

Code mount configurations (JSON format)

string

Idle time in seconds before idle action

string

Action on idle (shutdown, suspend)

string[]

Available ports

boolean

Run as root

string

Run as this user (format: username:uid)

string

Network policy ID to apply

string

Tunnel authentication mode (open, authenticated)

string[]

Gateway configurations (format: ENV_PREFIX=gateway_id_or_name,secret_id_or_name)

string[]

MCP configurations (format: ENV_VAR_NAME=mcp_config_id_or_name,secret_id_or_name)

list

List all devboxes

rli devbox list

string

Filter by status (initializing, running, suspending, suspended, resuming, failure, shutdown)

string

default:"20"

Max results

delete

Shutdown a devbox

rli devbox delete <id>

exec

Execute a command in a devbox

rli devbox exec <id> <command...>

string

Shell name to use (optional)

upload

Upload a file to a devbox

rli devbox upload <id> <file>

string

Target path in devbox

get

Get devbox details

rli devbox get <id>

suspend

Suspend a devbox

rli devbox suspend <id>

resume

Resume a suspended devbox

rli devbox resume <id>

shutdown

Shutdown a devbox

rli devbox shutdown <id>

ssh

SSH into a devbox

rli devbox ssh <id>

boolean

Print SSH config only

boolean

Do not wait for devbox to be ready

string

default:"180"

Timeout in seconds to wait for readiness

string

default:"3"

Polling interval in seconds while waiting

scp

Copy files to/from a devbox using scp (e.g. rli devbox scp dbx_id:/remote ./local)

rli devbox scp <src> <dst>

string

Additional scp options (quoted)

rsync

Sync files to/from a devbox using rsync (e.g. rli devbox rsync dbx_id:/remote ./local)

rli devbox rsync <src> <dst>

string

Additional rsync options (quoted)

tunnel

Create a port-forwarding tunnel to a devbox

rli devbox tunnel <id> <ports>

boolean

Open the tunnel URL in browser automatically

read

Read a file from a devbox using the API

rli devbox read <id>

string

Remote file path to read from the devbox

write

Write a file to a devbox using the API

rli devbox write <id>

string

Local file path to read contents from

string

Remote file path to write to on the devbox

download

Download a file from a devbox

rli devbox download <id>

string

Path to the file in the devbox

exec-async

Execute a command asynchronously on a devbox

rli devbox exec-async <id> <command...>

string

Shell name to use (optional)

get-async

Get status of an async execution

rli devbox get-async <id> <execution-id>

send-stdin

Send stdin to a running async execution

rli devbox send-stdin <id> <execution-id>

string

Text content to send to stdin

string

Signal to send (EOF, INTERRUPT)

logs

View devbox logs

rli devbox logs <id>

Benchmark Job Commands

Run orchestrated benchmarks at cloud scale. See Orchestrated Benchmarks for detailed usage.

run

Run a benchmark job with one or more agents

rli benchmark-job run \
  --agent "claude-code:claude-sonnet-4-6" \
  --benchmark "terminal-bench-2" \
  --n-concurrent-trials 100 \
  -n "my-benchmark-run"

string[]

required

Agent(s) to run. Format: agent:model (e.g., claude-code:claude-sonnet-4-6). Can specify multiple.

string

Benchmark ID or name to run

string[]

Scenario IDs to run (alternative to —benchmark)

string

Name for this job

string[]

Environment variables (format: KEY=value)

string[]

Secrets to inject (format: ENV_VAR=SECRET_NAME)

string

default:"7200"

Agent timeout in seconds

string

default:"1"

Number of attempts per scenario

string

default:"10"

Number of concurrent trials

string

default:"1.0"

Timeout multiplier

Supported public agents: claude-code, codex, opencode, goose, gemini-cli

watch

Watch benchmark job progress in real-time (full-screen)

rli benchmark-job watch <job_id>

summary

Get benchmark job summary and results

rli benchmark-job summary <job_id>

boolean

Show individual scenario results

list

List benchmark jobs

rli benchmark-job list

string

default:"1"

Show jobs from the last N days

boolean

Show all jobs (no time filter)

string

Filter by status (comma-separated). Valid: initializing, queued, running, completed, failed, cancelled, timeout

logs

Download devbox logs for all scenario runs in a benchmark job

rli benchmark-job logs <job_id>

string

Output directory for logs

string

Download logs for a specific benchmark run only

string

Download logs for a specific scenario run only

Snapshot Commands

list

List all snapshots

rli snapshot list

string

Filter by devbox ID

string

default:"20"

Max results

create

Create a snapshot of a devbox

rli snapshot create <devbox-id>

string

Snapshot name

delete

Delete a snapshot

rli snapshot delete <id>

get

Get snapshot details

rli snapshot get <id>

prune

Delete old snapshots for a devbox, keeping only recent ready ones

rli snapshot prune <devbox-id>

boolean

Show what would be deleted without actually deleting

boolean

Skip confirmation prompt

string

default:"1"

Number of ready snapshots to keep

status

Get snapshot operation status

rli snapshot status <snapshot-id>

Blueprint Commands

list

List all blueprints

rli blueprint list

string

Filter by blueprint name

string

default:"20"

Max results

create

Create a new blueprint

rli blueprint create

string

required

Blueprint name (required)

string

Dockerfile contents

string

Dockerfile path

string[]

System setup commands

string

Resource size (X_SMALL, SMALL, MEDIUM, LARGE, X_LARGE, XX_LARGE)

string

Architecture (arm64, x86_64)

string[]

Available ports

boolean

Run as root

string

Run as this user (format: username:uid)

string[]

Metadata tags (format: key=value)

get

Get blueprint details by name or ID (IDs start with bpt_)

rli blueprint get <name-or-id>

logs

Get blueprint build logs by name or ID (IDs start with bpt_)

rli blueprint logs <name-or-id>

delete

Delete a blueprint by ID

rli blueprint delete <id>

prune

Delete old blueprint builds, keeping only recent successful ones

rli blueprint prune <name>

boolean

Show what would be deleted without actually deleting

boolean

Skip confirmation prompt

string

default:"1"

Number of successful builds to keep

from-dockerfile

Create a blueprint from a Dockerfile with build context support

rli blueprint from-dockerfile

string

required

Blueprint name (required)

string

Build context directory (default: current directory)

string

Dockerfile path (default: Dockerfile in build context)

string[]

System setup commands

string

Resource size (X_SMALL, SMALL, MEDIUM, LARGE, X_LARGE, XX_LARGE)

string

Architecture (arm64, x86_64)

string[]

Available ports

boolean

Run as root

string

Run as this user (format: username:uid)

string[]

Metadata tags (format: key=value)

string

TTL in seconds for the build context object (default: 3600)

Object Commands

list

List objects

rli object list

string

default:"20"

Max results

string

Starting point for pagination

string

Filter by name (partial match supported)

string

Filter by content type

string

Filter by state (UPLOADING, READ_ONLY, DELETED)

string

Search by object ID or name

boolean

List public objects only

get

Get object details

rli object get <id>

download

Download object to local file

rli object download <id> <path>

boolean

Extract downloaded archive after download

string

default:"3600"

Duration in seconds for the presigned URL validity

upload

Upload a file as an object

rli object upload <path>

string

Object name (required)

string

boolean

Make object publicly accessible

delete

Delete an object (irreversible)

rli object delete <id>

Network-policy Commands

list

List network policies

rli network-policy list

string

default:"20"

Max results

string

Starting point for pagination

string

Filter by name

get

Get network policy details

rli network-policy get <id>

create

Create a new network policy

rli network-policy create

string

required

Policy name (required)

string

Policy description

boolean

Allow all egress traffic

boolean

Allow devbox-to-devbox communication

boolean

Allow Agent gateway access

boolean

Allow MCP gateway access

string[]

List of allowed hostnames for egress

delete

Delete a network policy

rli network-policy delete <id>

Secret Commands

create

Create a new secret. Value can be piped via stdin (e.g., echo ‘val’ | rli secret create name) or entered interactively with masked input for security.

rli secret create <name>

list

List all secrets

rli secret list

string

default:"20"

Max results

get

Get secret metadata by name

rli secret get <name>

update

Update a secret value (value from stdin or secure prompt)

rli secret update <name>

delete

Delete a secret

rli secret delete <name>

boolean

Skip confirmation prompt

Gateway-config Commands

list

List gateway configurations

rli gateway-config list

string

Filter by name

string

default:"20"

Max results

create

Create a new gateway configuration

rli gateway-config create

string

required

Gateway config name (required)

string

required

Target endpoint URL (required)

boolean

Use Bearer token authentication (default)

string

Use custom header authentication (specify header key name)

string

Description

get

Get gateway configuration details

rli gateway-config get <id>

update

Update a gateway configuration

rli gateway-config update <id>

string

New name

string

New endpoint URL

boolean

Use Bearer token authentication

string

Use custom header authentication (specify header key name)

string

New description

delete

Delete a gateway configuration

rli gateway-config delete <id>

Mcp-config Commands

list

List MCP configurations

rli mcp-config list

string

Filter by name

string

default:"20"

Max results

create

Create a new MCP configuration

rli mcp-config create

string

required

MCP config name (required)

string

required

Target endpoint URL (required)

string

required

Allowed tool patterns, comma-separated (required, e.g. '' or ‘github.search_,github.get_*’)

string

Description

get

Get MCP configuration details

rli mcp-config get <id>

update

Update an MCP configuration

rli mcp-config update <id>

string

New name

string

New endpoint URL

string

New allowed tool patterns, comma-separated

string

New description

delete

Delete an MCP configuration

rli mcp-config delete <id>

Mcp Commands

start

Start the MCP server

rli mcp start

boolean

Use HTTP/SSE transport instead of stdio

string

Port to listen on for HTTP mode (default: 3000)

install

Install Runloop MCP server configuration in Claude Desktop

rli mcp install

Scenario Commands

info

Display scenario definition details

rli scenario info <id>

MCP Server (AI Integration)

The CLI includes a Model Context Protocol (MCP) server that allows AI assistants like Claude to interact with your devboxes.

Quick Setup for Claude Desktop

# Install MCP configuration
rli mcp install

After installation, restart Claude Desktop and ask Claude to “List my devboxes” or “Create a new devbox”.

Server Modes

Stdio (Claude Desktop)
HTTP (Web/Remote)

rli mcp start

Standard input/output mode for Claude Desktop integration.

rli mcp start --http
rli mcp start --http --port 8080

HTTP/SSE mode for web applications and remote access.

Output Formats

All commands support multiple output formats via the --output flag:

flag

JSON output for programmatic parsing

flag

YAML output for configuration files

flag

Plain text output for human readability

rli devbox list --output json
rli devbox list --output yaml
rli devbox list --output text

Contributing

The Runloop CLI is open-source. We welcome contributions!

GitHub Repository

View source code and submit PRs

Report Issues

Report bugs or request features

Overview

Tools

Components

Benchmarks & Evals

Debugging

npm Package

GitHub Repository

Installation

Setup

Quick Start

Search Devboxes

SSH to Devbox

Command Groups

Devbox

Benchmark Job

Snapshot

Blueprint

Object

Command Reference

Devbox Commands

Benchmark Job Commands

Snapshot Commands

Blueprint Commands

Object Commands

Network-policy Commands

Secret Commands

Gateway-config Commands

Mcp-config Commands

Mcp Commands

Scenario Commands

MCP Server (AI Integration)

Quick Setup for Claude Desktop

Server Modes

Output Formats

Contributing

GitHub Repository

Report Issues

npm Package

GitHub Repository

​Installation

​Setup

​Quick Start

​Search Devboxes

​SSH to Devbox

​Command Groups

Devbox

Benchmark Job

Snapshot

Blueprint

Object

​Command Reference

​Devbox Commands

​Benchmark Job Commands

​Snapshot Commands

​Blueprint Commands

​Object Commands

​Network-policy Commands

​Secret Commands

​Gateway-config Commands

​Mcp-config Commands

​Mcp Commands

​Scenario Commands

​MCP Server (AI Integration)

​Quick Setup for Claude Desktop

​Server Modes

​Output Formats

​Contributing

GitHub Repository

Report Issues

Installation

Setup

Quick Start

Search Devboxes

SSH to Devbox

Command Groups

Command Reference

Devbox Commands

Benchmark Job Commands

Snapshot Commands

Blueprint Commands

Object Commands

Network-policy Commands

Secret Commands

Gateway-config Commands

Mcp-config Commands

Mcp Commands

Scenario Commands

MCP Server (AI Integration)

Quick Setup for Claude Desktop

Server Modes

Output Formats

Contributing