rl_cli 0.2.9

Runloop CLI for interacting with the Runloop APIs.

rl-cli

A command line utility for interacting with runloop APIs.

NOTE: This project is still in early alpha release

Table of Contents

• Setup
  • Install using pipx
  • For developers
• Quick Reference
  • Devbox
  • Blueprint
  • Snapshot
• Command Reference
  • Devbox Commands
    • Create a Devbox
    • List Devboxes
    • Get Devbox Details
    • Execute Commands
    • SSH Access
    • File Transfer
    • Port Forwarding
    • Devbox Management
  • Blueprint Commands
    • Create Blueprint
    • Preview Blueprint
    • List Blueprints
    • Get Blueprint Details
    • View Blueprint Logs
  • Snapshot Commands
    • Create Snapshot
    • List Snapshots
  • Invocation Commands
    • Get Invocation Details

Setup

Install using pipx

➜  ~  pipx install rl-cli
  installed package rl-cli 0.0.1, installed using Python 3.12.6
  These apps are now globally available

For developers

# Clone the repo
mkdir -p ~/source/ && cd ~/source/
git clone https://github.com/runloopai/rl-cli.git
cd rl-cli/

# Setup the venv and dev tools
python3 -m venv .venv && source .venv/bin/activate && pip install -r dev-requirements.txt

# Install to your venv with flink
# Use 'which python3' to find your system python
flit install --symlink --python </path/to/system/python>

# Install to your venv using pip
pip install rl-cli

# In a new terminal
export RUNLOOP_API_KEY=<your-api-key>
rl --help

Quick reference

Devbox

Create a devbox and run a single command

rl devbox create --env_vars HELLO=world --entrypoint 'echo $HELLO'
>
create devbox={
    "id": "dbx_2xMDUOsKMiZBYKsvSRtMA",
    "blueprint_id": null,
    "create_time_ms": 1723229557715,
    "end_time_ms": null,
    "initiator_id": null,
    "initiator_type": "invocation",
    "name": null,
    "status": "provisioning"
}

Observe logs

rl devbox logs --id dbx_2xMDUOsKMiZBYKsvSRtMA
>
2024-08-09 12:15:01.701  Initializing devbox...
2024-08-09 12:15:01.734  Devbox setup complete
2024-08-09 12:15:01.769 [entrypoint] -> echo $HELLO
2024-08-09 12:15:01.798 [entrypoint]  world
2024-08-09 12:15:01.798  world
2024-08-09 12:15:01.800 [entrypoint] -> exit_code=0

Check the devbox status

rl devbox get --id dbx_2ws7IOtjxnJgLsBIpU9nn
>   
# Note that the devbox status="shutdown" after the entrypoint completes.
devbox={
    "id": "dbx_2xMDUOsKMiZBYKsvSRtMA",
    "blueprint_id": null,
    "create_time_ms": 1723229557715,
    "end_time_ms": 1723229561620,
    "initiator_id": null,
    "initiator_type": "invocation",
    "name": null,
    "status": "shutdown"
}

Use scp to copy files to/from the devbox

To use the SCP command:
   rl devbox scp local_file.txt :remote_file.txt --id <devbox_id>

To copy a file from the devbox to your local machine:
   rl devbox scp :remote_file.txt local_file.txt --id <devbox_id>

Use rsync to copy files to/from the devbox

To use the rsync command:
   rl devbox rsync local_file.txt :remote_file.txt --id <devbox_id>

To copy a file from the devbox to your local machine:
   rl devbox rsync :remote_file.txt local_file.txt --id <devbox_id>

Note that the rsync implementation will recurse by default and copy directory contents.

To use the rsync command:
   rl devbox rsync local_dir :remote_dir --id <devbox_id>

Use port forwarding to create a tunnel to remote devbox

To use the tunnel command:
   rl devbox tunnel --id <devbox_id> <local_port>:<remote_port>

Note that this is a blocking command that will block for duration of tunnel.

Blueprint

Create a Blueprint with setup commands

rl blueprint create --name=<blueprint_name> --system_setup_commands "<setup commands>"

Snapshot

Create a Snapshot of devbox

rl devbox snapshot create --devbox_id=<devbox_id>

Command Reference

Devbox Commands

Create a Devbox

rl devbox create [options]

Options:
  --launch_commands      Devbox initialization commands (can be specified multiple times)
  --entrypoint          Devbox entrypoint command
  --blueprint_id        ID of the blueprint to use
  --blueprint_name      Name of the blueprint to use
  --snapshot_id         ID of the snapshot to use
  --env_vars           Environment variables in key=value format (can be specified multiple times)
  --code_mounts        Code mount configuration in JSON format
  --idle_time          Time in seconds after which idle action will be triggered
  --idle_action        Action to take when devbox becomes idle (shutdown/suspend)
  --prebuilt           Use a non-standard prebuilt image
  --resources          Devbox resource specification (SMALL/MEDIUM/LARGE/X_LARGE/XX_LARGE)

List Devboxes

rl devbox list [options]

Options:
  --status             Filter by devbox status (initializing/running/suspending/suspended/resuming/failure/shutdown)

Get Devbox Details

rl devbox get --id <devbox_id>

Execute Commands

Synchronous Execution

rl devbox exec --id <devbox_id> --command "<command>"

Asynchronous Execution

# Start async execution
rl devbox exec_async --id <devbox_id> --command "<command>"

# Get execution status
rl devbox get_async --id <devbox_id> --execution_id <execution_id>

SSH Access

# SSH into devbox
rl devbox ssh --id <devbox_id>

# Print SSH config only
rl devbox ssh --id <devbox_id> --config-only

File Transfer

SCP

# Copy to devbox
rl devbox scp local_file.txt :remote_file.txt --id <devbox_id>

# Copy from devbox
rl devbox scp :remote_file.txt local_file.txt --id <devbox_id>

# Additional options
rl devbox scp --scp-options "-r" local_dir :remote_dir --id <devbox_id>

Rsync

# Copy to devbox
rl devbox rsync local_dir :remote_dir --id <devbox_id>

# Copy from devbox
rl devbox rsync :remote_dir local_dir --id <devbox_id>

# Additional options
rl devbox rsync --rsync-options "-avz" local_dir :remote_dir --id <devbox_id>

Port Forwarding

rl devbox tunnel --id <devbox_id> <local_port>:<remote_port>

Devbox Management

Suspend Devbox

rl devbox suspend --id <devbox_id>

Resume Devbox

rl devbox resume --id <devbox_id>

Shutdown Devbox

rl devbox shutdown --id <devbox_id>

View Logs

rl devbox logs --id <devbox_id>

Blueprint Commands

Create Blueprint

rl blueprint create [options]

Options:
  --name               Blueprint name (required)
  --system_setup_commands  System initialization commands (can be specified multiple times)
  --dockerfile        Dockerfile contents as text
  --dockerfile_path   Path to Dockerfile
  --resources         Resource specification (SMALL/MEDIUM/LARGE/X_LARGE/XX_LARGE)
  --available_ports   List of available ports (can be specified multiple times)

Preview Blueprint

rl blueprint preview [options]

Options:
  --name               Blueprint name (required)
  --dockerfile        Dockerfile contents as text
  --system_setup_commands  System initialization commands (can be specified multiple times)

List Blueprints

rl blueprint list [options]

Options:
  --name              Filter by blueprint name

Get Blueprint Details

rl blueprint get --id <blueprint_id>

View Blueprint Logs

rl blueprint logs --id <blueprint_id>

Snapshot Commands

Create Snapshot

rl devbox snapshot create --devbox_id <devbox_id>

List Snapshots

rl devbox snapshot list

Invocation Commands

Get Invocation Details

rl invocation get --id <invocation_id>