@runloop/rl-cli

Runloop CLI

A beautiful, interactive CLI for managing Runloop devboxes built with Ink and TypeScript.

Features

• 🎨 Beautiful terminal UI with colors and gradients
• ⚡ Fast and responsive with pagination
• 🔐 Secure API key management
• 📦 Manage devboxes, snapshots, and blueprints
• 🚀 Execute commands in devboxes
• 📤 Upload files to devboxes
• 🎯 Organized command structure with aliases

Installation

Install globally via npm:

npm install -g @runloop/rl-cli

Or install from source:

git clone https://github.com/runloop/rl-cli-node.git
cd rl-cli-node
npm install
npm run build
npm link

Setup

Configure your API key using either method:

Option 1: Environment Variable (Recommended for CI/CD)

export RUNLOOP_API_KEY=your_api_key_here

Option 2: Interactive Setup

rln auth

Get your API key from https://runloop.ai/settings

Usage

Authentication

# Interactive setup (stores API key locally)
rln auth

# Or use environment variable
export RUNLOOP_API_KEY=your_api_key_here

The CLI will automatically use RUNLOOP_API_KEY if set, otherwise it will use the stored configuration.

Devbox Commands

# Create devboxes
rln devbox create                           # Create with auto-generated name
rln devbox create --name my-devbox          # Create with custom name
rln devbox create --template nodejs         # Create from template
rln d create -n my-devbox                   # Short alias

# List devboxes (paginated)
rln devbox list                             # List all devboxes
rln devbox list --status running            # Filter by status
rln d list                                  # Short alias

# Execute commands
rln devbox exec <devbox-id> echo "Hello"    # Run a command
rln devbox exec <devbox-id> ls -la          # List files
rln d exec <id> <command>                   # Short alias

# Upload files
rln devbox upload <devbox-id> ./file.txt    # Upload to home
rln devbox upload <id> ./file.txt -p /path  # Upload to specific path
rln d upload <id> <file>                    # Short alias

# Delete devboxes
rln devbox delete <devbox-id>               # Shutdown a devbox
rln devbox rm <devbox-id>                   # Alias
rln d delete <id>                           # Short alias

Snapshot Commands

# Create snapshots
rln snapshot create <devbox-id>             # Create snapshot
rln snapshot create <id> --name backup-1    # Create with name
rln snap create <id>                        # Short alias

# List snapshots (paginated)
rln snapshot list                           # List all snapshots
rln snapshot list --devbox <id>             # Filter by devbox
rln snap list                               # Short alias

# Delete snapshots
rln snapshot delete <snapshot-id>           # Delete snapshot
rln snapshot rm <snapshot-id>               # Alias
rln snap delete <id>                        # Short alias

Blueprint Commands

# List blueprints
rln blueprint list                          # List blueprints (coming soon)
rln bp list                                 # Short alias

Command Structure

The CLI is organized into command buckets:

• devbox (alias: d) - Manage devboxes

  • create - Create new devboxes
  • list - List devboxes with pagination
  • exec - Execute commands
  • upload - Upload files
  • delete (alias: rm) - Shutdown devboxes

• snapshot (alias: snap) - Manage snapshots

  • create - Create snapshots
  • list - List snapshots with pagination
  • delete (alias: rm) - Delete snapshots

• blueprint (alias: bp) - Manage blueprints

  • list - List blueprints (coming soon)

Interactive Features

• Pagination - Lists show 10 items per page with keyboard navigation
  • n - Next page
  • p - Previous page
  • q - Quit
• Beautiful UI - Gradient text, colored borders, Unicode icons
• Real-time Status - Spinners and progress indicators
• Summary Stats - Count running, stopped, and total resources

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run CLI
npm start -- <command>

Tech Stack

• Ink - React for CLIs
• Ink Gradient - Gradient text
• Ink Big Text - ASCII art
• Commander.js - CLI framework
• @runloop/api-client - Runloop API client
• TypeScript - Type safety
• Figures - Unicode symbols

Publishing

To publish a new version to npm:

npm run build
npm publish

Note: Make sure you're logged in to npm with access to the @runloop organization.

License

MIT