CLI Reference

The Runra CLI (runra) provides a terminal interface for managing sandboxes, running AI agents, and interacting with the Runra platform. Install it alongside the SDK.

Installation

# Install globally
npm install -g @runra/cli

# Or run via npx
npx @runra/cli sandbox list

# Verify installation
runra --version

Global Flags

All commands accept these global flags:

Flag	Env Variable	Description
--api-key <key>	RUNRA_API_KEY	Runra API key
--api-url <url>	RUNRA_API_URL	API base URL (default: https://api.box.runra.dev)
--json	—	Output as JSON (for scripting)
--verbose	—	Show debug output
--help	—	Show help for any command

Authentication

runra auth login

Authenticate with Runra and store credentials locally.

runra auth login

Prompts for your API key interactively. Credentials are stored in ~/.runra/credentials.json.

runra auth status

Check authentication status.

runra auth status

{
  "authenticated": true,
  "workspace": "my-org",
  "apiUrl": "https://api.box.runra.dev"
}

runra auth logout

Remove stored credentials.

runra auth logout

runra auth create-key

Create a new API key.

runra auth create-key \
  --name "production-ci" \
  --scope "sandbox:create,sandbox:execute,sandbox:delete" \
  --expires-in 90d

# Output
# Created API key: rra_live_x7k2m9p4q1w3v5b8n6c0d2a4f
# Name: production-ci
# Scopes: sandbox:create, sandbox:execute, sandbox:delete
# Expires: 2026-09-13
# Save this key — it will not be shown again.

Flag	Description
--name <name>	Key name (required)
--scope <scopes>	Comma-separated scopes (default: sandbox:*)
--expires-in <duration>	Key lifetime: 30d, 90d, 365d, never

runra auth list-keys

List all API keys for your account.

runra auth list-keys

runra auth revoke-key

Revoke an API key.

runra auth revoke-key --key-id "key_abc123def456"

Sandbox Management

runra sandbox create

Create a new sandbox.

runra sandbox create \
  --image node:22 \
  --cpu 2 \
  --memory 4096 \
  --disk 10240 \
  --env NODE_ENV=production \
  --env CI=true \
  --timeout 300000 \
  --idle-timeout 120000 \
  --metadata userId=user_123 \
  --label "build-sandbox"

Flag	Description	Default
--image <name>	Base image	node:22
--cpu <count>	vCPUs (2, 4, 8)	2
--memory <mb>	Memory in MB	4096
--disk <mb>	Disk in MB	10240
--env <KEY=VALUE>	Environment variable (repeatable)	—
--workdir <path>	Working directory	/workspace
--timeout <ms>	Max lifetime in ms	300000
--idle-timeout <ms>	Auto-pause after idle ms	120000
--metadata <KEY=VALUE>	Custom tags (repeatable)	—
--label <name>	Friendly label	—
--wait	Wait for sandbox to be ready	false

runra sandbox list

List sandboxes.

runra sandbox list                    # All sandboxes
runra sandbox list --state running    # Only running
runra sandbox list --limit 10         # Paginate
runra sandbox list --json             # JSON output

runra sandbox get

Get a single sandbox.

runra sandbox get sb_x7k2m9p4q1w3v5b8n

runra sandbox pause

Pause a running sandbox.

runra sandbox pause sb_x7k2m9p4q1w3v5b8n

runra sandbox resume

Resume a paused sandbox.

runra sandbox resume sb_x7k2m9p4q1w3v5b8n

runra sandbox delete

Terminate a sandbox.

runra sandbox delete sb_x7k2m9p4q1w3v5b8n

# Force delete without confirmation
runra sandbox delete sb_x7k2m9p4q1w3v5b8n --force

Code Execution

runra exec

Execute a command in a sandbox.

# Simple command
runra exec sb_x7k2m9p4q1w3v5b8n "npm install && npm run build"

# With options
runra exec sb_x7k2m9p4q1w3v5b8n "npm test" \
  --cwd /workspace/packages/core \
  --env CI=true \
  --timeout 120000

# Execute from stdin
echo "console.log('hello')" | runra exec sb_x7k2m9p4q1w3v5b8n "node -"

Flag	Description	Default
--cwd <path>	Working directory	Sandbox workdir
--env <KEY=VALUE>	Environment variable (repeatable)	—
--timeout <ms>	Command timeout	60000
--stdin <text>	Text to pipe to stdin	—

runra exec stream

Execute with streaming output.

runra exec stream sb_x7k2m9p4q1w3v5b8n "for i in 1 2 3; do echo Line \$i; sleep 1; done"

File Operations

runra files ls

List files in a sandbox.

runra files ls sb_x7k2m9p4q1w3v5b8n /workspace
runra files ls sb_x7k2m9p4q1w3v5b8n /workspace/src --recursive

runra files read

Read a file from a sandbox.

runra files read sb_x7k2m9p4q1w3v5b8n /workspace/package.json

runra files write

Write content to a sandbox file.

runra files write sb_x7k2m9p4q1w3v5b8n /workspace/app.ts ./local-file.ts

# Write from stdin
echo "export const hello = 'world'" | runra files write sb_x7k2m9p4q1w3v5b8n /workspace/hello.ts --stdin

runra files delete

Delete a file or directory.

runra files delete sb_x7k2m9p4q1w3v5b8n /workspace/temp.log
runra files delete sb_x7k2m9p4q1w3v5b8n /workspace/old-build --recursive

runra files exists

Check if a path exists.

runra files exists sb_x7k2m9p4q1w3v5b8n /workspace/package.json
# Exit code: 0 (exists) or 1 (not found)

Port Management

runra port expose

Expose a port for public access.

runra port expose sb_x7k2m9p4q1w3v5b8n 3000

# Output
# Port 3000 exposed at https://3000-ab12cd.box.runra.dev

runra port list

List exposed ports.

runra port list sb_x7k2m9p4q1w3v5b8n

runra port close

Close an exposed port.

runra port close sb_x7k2m9p4q1w3v5b8n 3000

Agent Management

runra agent run

Run an AI agent in a sandbox.

runra agent run \
  --provider claude-code \
  --model claude-sonnet-4-20250514 \
  --image node:22 \
  --prompt "Create a React component for a signup form"

# Use an existing sandbox
runra agent run \
  --provider codex \
  --sandbox sb_x7k2m9p4q1w3v5b8n \
  --prompt "Add validation to the signup form"

Flag	Description	Default
--provider <name>	Agent adapter	claude-code
--model <name>	LLM model	Agent default
--sandbox <id>	Existing sandbox ID	—
--image <name>	Sandbox image (creates new)	node:22
--cpu <count>	Sandbox vCPUs	2
--memory <mb>	Sandbox memory MB	4096
--max-turns <n>	Maximum agent loops	50
--permission <mode>	auto-approve, prompt, plan	auto-approve

Observability

runra events tail

Stream live runtime events.

runra events tail --sandbox sb_x7k2m9p4q1w3v5b8n

# Filter by type
runra events tail --type exec.completed

# Output as JSON
runra events tail --json

runra events export

Export events to a file.

# Export to JSONL
runra events export \
  --sandbox sb_x7k2m9p4q1w3v5b8n \
  --output ./events.jsonl

# Filter and export
runra events export \
  --type "exec.completed" \
  --after 2026-06-15T00:00:00Z \
  --limit 1000 \
  --output ./exec-events.jsonl

Configuration

runra config set

Set configuration values.

runra config set defaults.image node:22
runra config set defaults.resources.cpu 4
runra config set sandbox.provider runra-sandbox
runra config set observability.provider axiom

runra config get

Get configuration values.

runra config get defaults.image
runra config get --all

runra config unset

Remove a configuration value.

runra config unset defaults.image

Utility Commands

runra health

Check API health.

runra health

# Output
# ✓ API: healthy (v1)
# ✓ Authentication: valid
# latency: 45ms

runra version

Show CLI version.

runra version

# Output
# runra CLI 1.2.0
# @runra/sdk 1.2.0
# @runra/runtime 1.2.0

runra completion

Generate shell completion scripts.

# Bash
source <(runra completion bash)

# Zsh
source <(runra completion zsh)

# Fish
runra completion fish > ~/.config/fish/completions/runra.fish

Scripting with --json

The --json flag outputs structured JSON for use in scripts:

# Create sandbox and capture ID
SANDBOX_ID=$(runra sandbox create --json | jq -r '.id')

# Execute and capture result
RESULT=$(runra exec "$SANDBOX_ID" "npm test" --json)
EXIT_CODE=$(echo "$RESULT" | jq -r '.exitCode')

# List sandboxes with jq
runra sandbox list --json | jq '.data[] | {id, state, image}'

Environment Variables

The CLI reads configuration from these environment variables:

Variable	Description
RUNRA_API_KEY	API key for authentication
RUNRA_API_URL	API base URL
RUNRA_CONFIG_PATH	Config file location (default: ~/.runra/config.json)

Exit Codes

Code	Meaning
0	Success
1	General error
2	Authentication error
3	Network error
4	Invalid arguments
5	Sandbox not found
6	Execution failed (non-zero exit code)

Next Steps

• SDK Reference — programmatic API
• Configuration Reference — all config options
• Quick Start — first sandbox