> ## Documentation Index > Fetch the complete documentation index at: https://docs.runloop.ai/llms.txt > Use this file to discover all available pages before exploring further. # Runloop CLI > Explore, experiment with, and test the Runloop API using the Runloop CLI. The Runloop CLI (`rli`) provides both an interactive terminal UI and traditional CLI commands for managing your Runloop resources. @runloop/rl-cli runloopai/rl-cli ## Installation ```bash npm theme={null} npm install -g @runloop/rl-cli ``` ```bash yarn theme={null} yarn global add @runloop/rl-cli ``` ```bash pnpm theme={null} pnpm add -g @runloop/rl-cli ``` ## Setup Configure your API key: ```bash theme={null} export RUNLOOP_API_KEY=your_api_key_here ``` Get your API key from the [Settings page](https://platform.runloop.ai/settings#api-keys) in the Runloop Dashboard. ## Quick Start Launch the interactive UI with a beautiful terminal interface: ```bash theme={null} rli ``` Navigate with arrow keys, select with Enter, and manage all your resources visually. Runloop CLI Interactive Mode ### Search Devboxes Press `/` to search and filter through your devboxes by name or ID. Search devboxes in interactive mode ### 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. SSH into a Devbox Use traditional commands for scripting and automation: ```bash theme={null} # List all devboxes rli devbox list --output json ``` ```json Example Output theme={null} [ { "id": "dbx_1234567890", "name": "my-devbox", "status": "running", "blueprint_id": "bpt_abcdef" } ] ``` ```bash theme={null} # Create a new devbox rli devbox create --name my-devbox --blueprint my-blueprint ``` ```text Example Output theme={null} dbx_1234567890 ``` ```bash theme={null} # Execute a command in a devbox rli devbox exec dbx_1234567890 echo "Hello World" ``` ```text Example Output theme={null} Hello World ``` ```bash theme={null} # SSH into a devbox rli devbox ssh dbx_1234567890 ``` ## Command Groups Create, manage, and interact with devboxes Run and manage orchestrated benchmarks Create and manage devbox snapshots Manage reusable devbox templates Upload and manage file objects ## Command Reference ### Devbox Commands Create a new devbox ```bash theme={null} rli devbox create ``` Devbox name Snapshot ID to use (alias: --snapshot) Snapshot ID to use Blueprint name or ID to use Resource size (X\_SMALL, SMALL, MEDIUM, LARGE, X\_LARGE, XX\_LARGE) Architecture (arm64, x86\_64) Entrypoint command to run Initialization commands to run on startup Environment variables (format: KEY=value) Secrets to inject as environment variables (format: ENV\_VAR=SECRET\_NAME) Code mount configurations (JSON format) Idle time in seconds before idle action Action on idle (shutdown, suspend) Available ports Run as root Run as this user (format: username:uid) Network policy ID to apply Tunnel authentication mode (open, authenticated) Gateway configurations (format: ENV\_PREFIX=gateway\_id\_or\_name,secret\_id\_or\_name) MCP configurations (format: ENV\_VAR\_NAME=mcp\_config\_id\_or\_name,secret\_id\_or\_name) List all devboxes ```bash theme={null} rli devbox list ``` Filter by status (initializing, running, suspending, suspended, resuming, failure, shutdown) Max results Shutdown a devbox ```bash theme={null} rli devbox delete ``` Execute a command in a devbox ```bash theme={null} rli devbox exec ``` Shell name to use (optional) Upload a file to a devbox ```bash theme={null} rli devbox upload ``` Target path in devbox Get devbox details ```bash theme={null} rli devbox get ``` Suspend a devbox ```bash theme={null} rli devbox suspend ``` Resume a suspended devbox ```bash theme={null} rli devbox resume ``` Shutdown a devbox ```bash theme={null} rli devbox shutdown ``` SSH into a devbox ```bash theme={null} rli devbox ssh ``` Print SSH config only Do not wait for devbox to be ready Timeout in seconds to wait for readiness Polling interval in seconds while waiting Copy files to/from a devbox using scp (e.g. rli devbox scp dbx\_id:/remote ./local) ```bash theme={null} rli devbox scp ``` Additional scp options (quoted) Sync files to/from a devbox using rsync (e.g. rli devbox rsync dbx\_id:/remote ./local) ```bash theme={null} rli devbox rsync ``` Additional rsync options (quoted) Create a port-forwarding tunnel to a devbox ```bash theme={null} rli devbox tunnel ``` Open the tunnel URL in browser automatically Read a file from a devbox using the API ```bash theme={null} rli devbox read ``` Remote file path to read from the devbox Write a file to a devbox using the API ```bash theme={null} rli devbox write ``` Local file path to read contents from Remote file path to write to on the devbox Download a file from a devbox ```bash theme={null} rli devbox download ``` Path to the file in the devbox Execute a command asynchronously on a devbox ```bash theme={null} rli devbox exec-async ``` Shell name to use (optional) Get status of an async execution ```bash theme={null} rli devbox get-async ``` Send stdin to a running async execution ```bash theme={null} rli devbox send-stdin ``` Text content to send to stdin Signal to send (EOF, INTERRUPT) View devbox logs ```bash theme={null} rli devbox logs ``` ### Benchmark Job Commands Run orchestrated benchmarks at cloud scale. See [Orchestrated Benchmarks](/docs/benchmarks/orchestrated-benchmarks) for detailed usage. Run a benchmark job with one or more agents ```bash theme={null} rli benchmark-job run \ --agent "claude-code:claude-sonnet-4-6" \ --benchmark "terminal-bench-2" \ --n-concurrent-trials 100 \ -n "my-benchmark-run" ``` Agent(s) to run. Format: `agent:model` (e.g., `claude-code:claude-sonnet-4-6`). Can specify multiple. Benchmark ID or name to run Scenario IDs to run (alternative to --benchmark) Name for this job Environment variables (format: KEY=value) Secrets to inject (format: ENV\_VAR=SECRET\_NAME) Agent timeout in seconds Number of attempts per scenario Number of concurrent trials Timeout multiplier **Supported public agents:** `claude-code`, `codex`, `opencode`, `goose`, `gemini-cli` Watch benchmark job progress in real-time (full-screen) ```bash theme={null} rli benchmark-job watch ``` Get benchmark job summary and results ```bash theme={null} rli benchmark-job summary ``` Show individual scenario results List benchmark jobs ```bash theme={null} rli benchmark-job list ``` Show jobs from the last N days Show all jobs (no time filter) Filter by status (comma-separated). Valid: initializing, queued, running, completed, failed, cancelled, timeout Download devbox logs for all scenario runs in a benchmark job ```bash theme={null} rli benchmark-job logs ``` Output directory for logs Download logs for a specific benchmark run only Download logs for a specific scenario run only ### Snapshot Commands List all snapshots ```bash theme={null} rli snapshot list ``` Filter by devbox ID Max results Create a snapshot of a devbox ```bash theme={null} rli snapshot create ``` Snapshot name Delete a snapshot ```bash theme={null} rli snapshot delete ``` Get snapshot details ```bash theme={null} rli snapshot get ``` Delete old snapshots for a devbox, keeping only recent ready ones ```bash theme={null} rli snapshot prune ``` Show what would be deleted without actually deleting Skip confirmation prompt Number of ready snapshots to keep Get snapshot operation status ```bash theme={null} rli snapshot status ``` ### Blueprint Commands List all blueprints ```bash theme={null} rli blueprint list ``` Filter by blueprint name Max results Create a new blueprint ```bash theme={null} rli blueprint create ``` Blueprint name (required) Dockerfile contents Dockerfile path System setup commands Resource size (X\_SMALL, SMALL, MEDIUM, LARGE, X\_LARGE, XX\_LARGE) Architecture (arm64, x86\_64) Available ports Run as root Run as this user (format: username:uid) Metadata tags (format: key=value) Get blueprint details by name or ID (IDs start with bpt\_) ```bash theme={null} rli blueprint get ``` Get blueprint build logs by name or ID (IDs start with bpt\_) ```bash theme={null} rli blueprint logs ``` Delete a blueprint by ID ```bash theme={null} rli blueprint delete ``` Delete old blueprint builds, keeping only recent successful ones ```bash theme={null} rli blueprint prune ``` Show what would be deleted without actually deleting Skip confirmation prompt Number of successful builds to keep Create a blueprint from a Dockerfile with build context support ```bash theme={null} rli blueprint from-dockerfile ``` Blueprint name (required) Build context directory (default: current directory) Dockerfile path (default: Dockerfile in build context) System setup commands Resource size (X\_SMALL, SMALL, MEDIUM, LARGE, X\_LARGE, XX\_LARGE) Architecture (arm64, x86\_64) Available ports Run as root Run as this user (format: username:uid) Metadata tags (format: key=value) TTL in seconds for the build context object (default: 3600) ### Object Commands List objects ```bash theme={null} rli object list ``` Max results Starting point for pagination Filter by name (partial match supported) Filter by content type Filter by state (UPLOADING, READ\_ONLY, DELETED) Search by object ID or name List public objects only Get object details ```bash theme={null} rli object get ``` Download object to local file ```bash theme={null} rli object download ``` Extract downloaded archive after download Duration in seconds for the presigned URL validity Upload a file as an object ```bash theme={null} rli object upload ``` Object name (required) Content type: unspecified|text|binary|gzip|tar|tgz Make object publicly accessible Delete an object (irreversible) ```bash theme={null} rli object delete ``` ### Network-policy Commands List network policies ```bash theme={null} rli network-policy list ``` Max results Starting point for pagination Filter by name Get network policy details ```bash theme={null} rli network-policy get ``` Create a new network policy ```bash theme={null} rli network-policy create ``` Policy name (required) Policy description Allow all egress traffic Allow devbox-to-devbox communication Allow Agent gateway access Allow MCP gateway access List of allowed hostnames for egress Delete a network policy ```bash theme={null} rli network-policy delete ``` ### Secret Commands 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. ```bash theme={null} rli secret create ``` List all secrets ```bash theme={null} rli secret list ``` Max results Get secret metadata by name ```bash theme={null} rli secret get ``` Update a secret value (value from stdin or secure prompt) ```bash theme={null} rli secret update ``` Delete a secret ```bash theme={null} rli secret delete ``` Skip confirmation prompt ### Gateway-config Commands List gateway configurations ```bash theme={null} rli gateway-config list ``` Filter by name Max results Create a new gateway configuration ```bash theme={null} rli gateway-config create ``` Gateway config name (required) Target endpoint URL (required) Use Bearer token authentication (default) Use custom header authentication (specify header key name) Description Get gateway configuration details ```bash theme={null} rli gateway-config get ``` Update a gateway configuration ```bash theme={null} rli gateway-config update ``` New name New endpoint URL Use Bearer token authentication Use custom header authentication (specify header key name) New description Delete a gateway configuration ```bash theme={null} rli gateway-config delete ``` ### Mcp-config Commands List MCP configurations ```bash theme={null} rli mcp-config list ``` Filter by name Max results Create a new MCP configuration ```bash theme={null} rli mcp-config create ``` MCP config name (required) Target endpoint URL (required) Allowed tool patterns, comma-separated (required, e.g. '*' or 'github.search\_*,github.get\_\*') Description Get MCP configuration details ```bash theme={null} rli mcp-config get ``` Update an MCP configuration ```bash theme={null} rli mcp-config update ``` New name New endpoint URL New allowed tool patterns, comma-separated New description Delete an MCP configuration ```bash theme={null} rli mcp-config delete ``` ### Mcp Commands Start the MCP server ```bash theme={null} rli mcp start ``` Use HTTP/SSE transport instead of stdio Port to listen on for HTTP mode (default: 3000) Install Runloop MCP server configuration in Claude Desktop ```bash theme={null} rli mcp install ``` ### Scenario Commands Display scenario definition details ```bash theme={null} rli scenario info ``` ## 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 ```bash theme={null} # 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 ```bash theme={null} rli mcp start ``` Standard input/output mode for Claude Desktop integration. ```bash theme={null} 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: JSON output for programmatic parsing YAML output for configuration files Plain text output for human readability ```bash theme={null} 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! View source code and submit PRs Report bugs or request features