Runloop CLI - Runloop AI Docs

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

name

string

Devbox name

template

string

Snapshot ID to use (alias: —snapshot)

snapshot

string

Snapshot ID to use

blueprint

string

Blueprint name or ID to use

resources

string

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

architecture

string

Architecture (arm64, x86_64)

entrypoint

string

Entrypoint command to run

launch-commands

string[]

Initialization commands to run on startup

env-vars

string[]

Environment variables (format: KEY=value)

secrets

string[]

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

code-mounts

string[]

Code mount configurations (JSON format)

idle-time

string

Idle time in seconds before idle action

idle-action

string

Action on idle (shutdown, suspend)

available-ports

string[]

Available ports

root

boolean

Run as root

user

string

Run as this user (format: username:uid)

network-policy

string

Network policy ID to apply

tunnel

string

Tunnel authentication mode (open, authenticated)

gateways

string[]

Gateway configurations (format: ENV_PREFIX=gateway_id_or_name,secret_id_or_name)

mcp

string[]

MCP configurations (format: ENV_VAR_NAME=mcp_config_id_or_name,secret_id_or_name)

list

List all devboxes

rli devbox list

status

string

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

limit

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...>

shell-name

string

Shell name to use (optional)

upload

Upload a file to a devbox

rli devbox upload <id> <file>

path

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>

config-only

boolean

Print SSH config only

no-wait

boolean

Do not wait for devbox to be ready

timeout

string

default:"180"

Timeout in seconds to wait for readiness

poll-interval

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>

scp-options

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>

rsync-options

string

Additional rsync options (quoted)

tunnel

Create a port-forwarding tunnel to a devbox

rli devbox tunnel <id> <ports>

open

boolean

Open the tunnel URL in browser automatically

read

Read a file from a devbox using the API

rli devbox read <id>

remote

string

Remote file path to read from the devbox

write

Write a file to a devbox using the API

rli devbox write <id>

input

string

Local file path to read contents from

remote

string

Remote file path to write to on the devbox

download

Download a file from a devbox

rli devbox download <id>

file-path

string

Path to the file in the devbox

exec-async

Execute a command asynchronously on a devbox

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

shell-name

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>

text

string

Text content to send to stdin

signal

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"

agent

string[]

required

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

benchmark

string

Benchmark ID or name to run

scenarios

string[]

Scenario IDs to run (alternative to —benchmark)

job-name

string

Name for this job

env-vars

string[]

Environment variables (format: KEY=value)

secrets

string[]

Secrets to inject (format: ENV_VAR=SECRET_NAME)

timeout

string

default:"7200"

Agent timeout in seconds

n-attempts

string

default:"1"

Number of attempts per scenario

n-concurrent-trials

string

default:"10"

Number of concurrent trials

timeout-multiplier

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>

extended

boolean

Show individual scenario results

list

List benchmark jobs

rli benchmark-job list

days

string

default:"1"

Show jobs from the last N days

all

boolean

Show all jobs (no time filter)

status

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>

output-dir

string

Output directory for logs

run

string

Download logs for a specific benchmark run only

scenario

string

Download logs for a specific scenario run only

Snapshot Commands

list

List all snapshots

rli snapshot list

devbox

string

Filter by devbox ID

limit

string

default:"20"

Max results

create

Create a snapshot of a devbox

rli snapshot create <devbox-id>

name

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>

dry-run

boolean

Show what would be deleted without actually deleting

yes

boolean

Skip confirmation prompt

keep

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

name

string

Filter by blueprint name

limit

string

default:"20"

Max results

create

Create a new blueprint

rli blueprint create

name

string

required

Blueprint name (required)

dockerfile

string

Dockerfile contents

dockerfile-path

string

Dockerfile path

system-setup-commands

string[]

System setup commands

resources

string

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

architecture

string

Architecture (arm64, x86_64)

available-ports

string[]

Available ports

root

boolean

Run as root

user

string

Run as this user (format: username:uid)

metadata

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>

dry-run

boolean

Show what would be deleted without actually deleting

yes

boolean

Skip confirmation prompt

keep

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

name

string

required

Blueprint name (required)

build-context

string

Build context directory (default: current directory)

dockerfile

string

Dockerfile path (default: Dockerfile in build context)

system-setup-commands

string[]

System setup commands

resources

string

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

architecture

string

Architecture (arm64, x86_64)

available-ports

string[]

Available ports

root

boolean

Run as root

user

string

Run as this user (format: username:uid)

metadata

string[]

Metadata tags (format: key=value)

ttl

string

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

Object Commands

list

List objects

rli object list

limit

string

default:"20"

Max results

starting-after

string

Starting point for pagination

name

string

Filter by name (partial match supported)

content-type

string

Filter by content type

state

string

Filter by state (UPLOADING, READ_ONLY, DELETED)

string

Search by object ID or name

public

boolean

List public objects only

get

Get object details

rli object get <id>

download

Download object to local file

rli object download <id> <path>

extract

boolean

Extract downloaded archive after download

duration-seconds

string

default:"3600"

Duration in seconds for the presigned URL validity

upload

Upload a file as an object

rli object upload <path>

name

string

Object name (required)

content-type

string

public

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

limit

string

default:"20"

Max results

starting-after

string

Starting point for pagination

name

string

Filter by name

get

Get network policy details

rli network-policy get <id>

create

Create a new network policy

rli network-policy create

name

string

required

Policy name (required)

description

string

Policy description

allow-all

boolean

Allow all egress traffic

allow-devbox-to-devbox

boolean

Allow devbox-to-devbox communication

allow-agent-gateway

boolean

Allow Agent gateway access

allow-mcp-gateway

boolean

Allow MCP gateway access

allowed-hostnames

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

limit

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>

yes

boolean

Skip confirmation prompt

Gateway-config Commands

list

List gateway configurations

rli gateway-config list

name

string

Filter by name

limit

string

default:"20"

Max results

create

Create a new gateway configuration

rli gateway-config create

name

string

required

Gateway config name (required)

endpoint

string

required

Target endpoint URL (required)

bearer-auth

boolean

Use Bearer token authentication (default)

header-auth

string

Use custom header authentication (specify header key name)

description

string

Description

get

Get gateway configuration details

rli gateway-config get <id>

update

Update a gateway configuration

rli gateway-config update <id>

name

string

New name

endpoint

string

New endpoint URL

bearer-auth

boolean

Use Bearer token authentication

header-auth

string

Use custom header authentication (specify header key name)

description

string

New description

delete

Delete a gateway configuration

rli gateway-config delete <id>

Mcp-config Commands

list

List MCP configurations

rli mcp-config list

name

string

Filter by name

limit

string

default:"20"

Max results

create

Create a new MCP configuration

rli mcp-config create

name

string

required

MCP config name (required)

endpoint

string

required

Target endpoint URL (required)

allowed-tools

string

required

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

description

string

Description

get

Get MCP configuration details

rli mcp-config get <id>

update

Update an MCP configuration

rli mcp-config update <id>

name

string

New name

endpoint

string

New endpoint URL

allowed-tools

string

New allowed tool patterns, comma-separated

description

string

New description

delete

Delete an MCP configuration

rli mcp-config delete <id>

Mcp Commands

start

Start the MCP server

rli mcp start

http

boolean

Use HTTP/SSE transport instead of stdio

port

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:

--output json

flag

JSON output for programmatic parsing

--output yaml

flag

YAML output for configuration files

--output text

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

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