CLI Reference

Runra CLI command reference — manage sandboxes, execute code, run agents, configure authentication, and export observability data from the terminal

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

CLI Reference

Installation

Global Flags

Authentication

runra auth login

runra auth status

runra auth logout

runra auth create-key

runra auth list-keys

runra auth revoke-key

Sandbox Management

runra sandbox create

runra sandbox list

runra sandbox get

runra sandbox pause

runra sandbox resume

runra sandbox delete

Code Execution

runra exec

runra exec stream

File Operations

runra files ls

runra files read

runra files write

runra files delete

runra files exists