Installation and Update
# 安装
bash -c "$(curl -fsSL http://xrl.alibaba-inc.com/install.sh)"
# 升级（推荐）
rockcli update
After installation, you can use rockcli or rc. Minor versions are upgraded automatically; major/minor versions require manual upgrade.
Authentication Configuration
export ROCK_API_KEY=your-api-key # 方式一：环境变量（优先级最高）
rockcli --api-key your-key <command> # 方式二：全局参数
# 方式三：配置文件 ~/.rock/setting.json
Scenario Guide
For detailed parameters, see references/sandbox.md。
Scenario 1: Quick Start / One-off Tasks
Applicable: temporarily execute scripts, verify the environment, run a piece of code
rockcli sandbox start --wait-for-alive # 启动并阻塞等待 alive
rockcli sandbox <id> exec 'python -c "print(1+1)"'
rockcli sandbox <id> stop
Scenario 2: Upload Code → Execute → Download Results
Applicable: run local projects in the sandbox, batch processing tasks
rockcli sandbox start --memory 16g --cpus 4 --wait-for-alive
# 递归上传（注意：-r 短参数无效，必须用 --recursive）
rockcli sandbox <id> upload --dir ./my-project --target-path /app --recursive
# 包含隐藏文件（如 .env）加 -a
rockcli sandbox <id> upload --dir ./my-project --target-path /app --recursive -a
rockcli sandbox <id> exec 'cd /app && python main.py'
rockcli sandbox <id> download --file /app/output.csv # 下载到当前目录
rockcli sandbox <id> stop
Scenario 3: Interactive Development (attach REPL)
Applicable: debugging, exploring the environment, requiring multiple rounds of interaction (the sandbox must be in alive state)
rockcli sandbox <id> attach
For built-in REPL commands, see references/sandbox.md - attach. Key difference:
/exit— disconnect, the sandbox and session are retained and can be reconnected/close— permanently close the session
Scenario 4: Troubleshooting / Viewing Logs
Applicable: command execution fails, need to locate the cause of the error
# 搜索所有日志（默认最近 15 分钟）
rockcli sandbox <id> log search -k "error"
# 指定日志文件（必须用 --log-file，位置参数无效）
rockcli sandbox <id> log search --log-file command.log -k "error"
rockcli sandbox <id> log search --log-file access.log -k "500"
# 显示上下文 / 扩大时间范围 / 字段过滤
rockcli sandbox <id> log search --log-file command.log -k "error" -C 5
rockcli sandbox <id> log search -m 60 -k "OOM"
rockcli sandbox <id> log search -f "level=ERROR"
# 实时追踪
rockcli sandbox <id> log tail -k "error"
Supported log files：command.log(command output),access.log(HTTP access),rocklet.log(system components),rocklet_uvicorn.log
Scenario 5: View Historical Operation Records
Applicable: trace back all API operations of the sandbox (complete HTTP request history such as start/exec/upload)
rockcli sandbox <id> history
Scenario 6: Replay Requests
Applicable: reproduce historical request sequences, for testing or reproducing issues
# 自动从该沙箱的日志历史中拉取请求并回放
rockcli sandbox <id> replay
Scenario 7: View Sandbox Status
rockcli sandbox <id> status
Status transitions:pending → alive → stopping → stopped
Global Options
| Option | Description |
|---|---|
--verbose, -v |
Log level (-v: warning, -vv: info, -vvv: debug) |
--base-url <url> |
Server address (default http://xrl.alibaba-inc.com） |
--api-key <key> |
API key |
--cluster <id> |
Cluster identifier |
-H, --extra-header |
Additional HTTP request headers (format:Key=Value） |