blaxel-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Blaxel CLI

A CLI to manage Blaxel cloud resources from the command line: agents, sandboxes, jobs, MCP servers, drives, and more.

一款用于从命令行管理Blaxel云资源的CLI工具：可管理Agent、沙箱、任务、MCP服务器、存储驱动器等。

Prerequisites

前提条件

The

bl

command must be available on PATH. To check:

bash

bl version

If not installed, install via the official install script:

bash

curl -fsSL https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh | sh

Or via Homebrew:

bash

brew tap blaxel-ai/blaxel && brew install blaxel

After installation, log in to your workspace:

bash

bl login my-workspace

bl

命令必须已添加到系统PATH中。可通过以下命令检查：

bash

bl version

如果未安装，可通过官方安装脚本进行安装：

bash

curl -fsSL https://raw.githubusercontent.com/blaxel-ai/toolkit/main/install.sh | sh

或通过Homebrew安装：

bash

brew tap blaxel-ai/blaxel && brew install blaxel

安装完成后，登录到你的工作区：

bash

bl login my-workspace

Global Flags

全局标志

All commands support these flags:

Flag	Description
`-o, --output <format>`	Output format: pretty, yaml, json, table
`-w, --workspace <name>`	Override workspace for this command
`-v, --verbose`	Enable verbose output
`-u, --utc`	Enable UTC timezone
`--skip-version-warning`	Skip version warning

所有命令均支持以下标志：

标志	描述
`-o, --output <format>`	输出格式：pretty、yaml、json、table
`-w, --workspace <name>`	覆盖当前命令使用的工作区
`-v, --verbose`	启用详细输出
`-u, --utc`	使用UTC时区
`--skip-version-warning`	跳过版本警告

Non-Interactive Mode

非交互模式

For commands that prompt for input (confirmations, selections), add

-y

--yes

to auto-confirm. This is required when running in non-interactive / no-TTY environments (scripts, CI, agents).

对于需要输入（确认、选择）的命令，添加

-y

或

--yes

参数可自动确认。在非交互/无TTY环境（脚本、CI、Agent）中运行时，此参数为必填项。

Available Commands

可用命令

bl apply       # Apply configuration changes to resources declaratively using YAML files.
bl chat        # Start an interactive chat session with a deployed agent.
bl connect     # Open an interactive terminal session to a sandbox
bl delete      # Delete Blaxel resources from your workspace.
bl deploy      # Deploy your Blaxel project to the cloud.
bl drive       # Manage drives and drive mounts on sandboxes.
bl get         # Retrieve information about Blaxel resources in your workspace.
bl login       # Authenticate with Blaxel to access your workspace.
bl logout      # Remove stored credentials for a workspace.
bl logs        # View logs for Blaxel resources.
bl new         # Create a new Blaxel resource from templates.
bl push        # Build and push a container image to the Blaxel registry without creating a deployment.
bl run         # Execute a Blaxel resource with custom input data.
bl serve       # Start a local development server for your Blaxel project.
bl share       # Share Blaxel resources with other workspaces in your account.
bl token       # Retrieve the authentication token for the specified workspace.
bl unshare     # Remove shared Blaxel resources from other workspaces.
bl upgrade     # Upgrade the Blaxel CLI to the latest version.
bl version     # Print the version number
bl workspaces  # List and manage Blaxel workspaces.

bl apply       # 使用YAML文件声明式地将配置变更应用到资源。
bl chat        # 与已部署的Agent启动交互式聊天会话。
bl connect     # 打开到沙箱的交互式终端会话
bl delete      # 从工作区中删除Blaxel资源。
bl deploy      # 将你的Blaxel项目部署到云端。
bl drive       # 管理沙箱上的存储驱动器和驱动器挂载。
bl get         # 获取工作区中Blaxel资源的信息。
bl login       # 通过Blaxel认证以访问你的工作区。
bl logout      # 删除工作区的存储凭据。
bl logs        # 查看Blaxel资源的日志。
bl new         # 从模板创建新的Blaxel资源。
bl push        # 构建容器镜像并推送到Blaxel镜像仓库，无需创建部署。
bl run         # 使用自定义输入数据执行Blaxel资源。
bl serve       # 为你的Blaxel项目启动本地开发服务器。
bl share       # 与账户中的其他工作区共享Blaxel资源。
bl token       # 获取指定工作区的认证令牌。
bl unshare     # 从其他工作区移除已共享的Blaxel资源。
bl upgrade     # 将Blaxel CLI升级到最新版本。
bl version     # 打印版本号
bl workspaces  # 列出并管理Blaxel工作区。

Reference Documentation

参考文档

apply - Apply configuration changes to resources declaratively using YAML files.
chat - Start an interactive chat session with a deployed agent.
connect - Open an interactive terminal session to a sandbox
delete - Delete Blaxel resources from your workspace.
deploy - Deploy your Blaxel project to the cloud.
drive - Manage drives and drive mounts on sandboxes.
get - Retrieve information about Blaxel resources in your workspace.
login - Authenticate with Blaxel to access your workspace.
logout - Remove stored credentials for a workspace.
logs - View logs for Blaxel resources.
new - Create a new Blaxel resource from templates.
push - Build and push a container image to the Blaxel registry without creating a deployment.
run - Execute a Blaxel resource with custom input data.
serve - Start a local development server for your Blaxel project.
share - Share Blaxel resources with other workspaces in your account.
token - Retrieve the authentication token for the specified workspace.
unshare - Remove shared Blaxel resources from other workspaces.
upgrade - Upgrade the Blaxel CLI to the latest version.
version - Print the version number
workspaces - List and manage Blaxel workspaces.

apply - 使用YAML文件声明式地将配置变更应用到资源。
chat - 与已部署的Agent启动交互式聊天会话。
connect - 打开到沙箱的交互式终端会话
delete - 从工作区中删除Blaxel资源。
deploy - 将你的Blaxel项目部署到云端。
drive - 管理沙箱上的存储驱动器和驱动器挂载。
get - 获取工作区中Blaxel资源的信息。
login - 通过Blaxel认证以访问你的工作区。
logout - 删除工作区的存储凭据。
logs - 查看Blaxel资源的日志。
new - 从模板创建新的Blaxel资源。
push - 构建容器镜像并推送到Blaxel镜像仓库，无需创建部署。
run - 使用自定义输入数据执行Blaxel资源。
serve - 为你的Blaxel项目启动本地开发服务器。
share - 与账户中的其他工作区共享Blaxel资源。
token - 获取指定工作区的认证令牌。
unshare - 从其他工作区移除已共享的Blaxel资源。
upgrade - 将Blaxel CLI升级到最新版本。
version - 打印版本号
workspaces - 列出并管理Blaxel工作区。

Discovering Options

查看选项详情

To see available subcommands and flags, run

--help

on any command:

bash

bl --help
bl deploy --help
bl get --help
bl get agents --help

要查看可用的子命令和标志，可在任意命令后添加

--help

：

bash

bl --help
bl deploy --help
bl get --help
bl get agents --help

Common Workflows

常见工作流

Create a sandbox, run a command, and get its logs

创建沙箱、运行命令并获取日志

bash

undefined

bash

undefined

1. Create a sandbox with bl apply

1. 使用bl apply创建沙箱

bl apply -f - <<EOF apiVersion: blaxel.ai/v1alpha1 kind: Sandbox metadata: name: my-sandbox spec: runtime: image: blaxel/base-image:latest memory: 2048 lifecycle: expirationPolicies: - type: ttl-idle value: 1h # Delete after 1 hour of inactivity. Units: h, d, w action: delete EOF

bl apply -f - <<EOF apiVersion: blaxel.ai/v1alpha1 kind: Sandbox metadata: name: my-sandbox spec: runtime: image: blaxel/base-image:latest memory: 2048 lifecycle: expirationPolicies: - type: ttl-idle value: 1h # 闲置1小时后删除。单位：h、d、w action: delete EOF

2. Retrieve sandbox configuration

2. 获取沙箱配置

bl get sandbox my-sandbox

3. Execute a command in the sandbox and get stdout of the command

3. 在沙箱中执行命令并获取命令的标准输出

bl run sandbox my-sandbox --path /process --data '{"command": "echo hello world", "name": "my-cmd", "waitForCompletion": true}'

4. Retrieve the logs for that command in case stdout was not sufficient

4. 如果标准输出不够详细，获取该命令的日志

bl logs sandbox my-sandbox my-cmd

undefined

bl logs sandbox my-sandbox my-cmd

undefined

Run a complex command in a sandbox (agent guideline)

在沙箱中运行复杂命令（Agent指南）

bl run sandbox ... --path /process --data '<json>'

requires the JSON payload to survive shell quoting. As soon as the command embeds nested quotes, backslashes, multiple lines, or interpreters like

sh -lc

python3 -c

, inline

--data

becomes brittle and the API rejects the request with

400 Bad Request: invalid character ... in string escape code

Decision rule for an agent:

Command has no single quotes, no backslashes, no newlines → use
```
--data '{"command": "...", "waitForCompletion": true}'
```
directly.
Anything more complex (nested quotes, escapes, multiline, scripts) → write the JSON payload to a file with your Write/file-creation tool (this bypasses the shell entirely), then run with
```
--file
```
.

bash

undefined

bl run sandbox ... --path /process --data '<json>'

要求JSON负载必须能通过shell引号的解析。一旦命令包含嵌套引号、反斜杠、多行内容或

sh -lc

python3 -c

这类解释器，直接使用

--data

会变得不稳定，且API会返回

400 Bad Request: invalid character ... in string escape code

错误。

Agent决策规则：

命令无单引号、无反斜杠、无换行 → 直接使用
```
--data '{"command": "...", "waitForCompletion": true}'
```
。
任何更复杂的情况（嵌套引号、转义符、多行内容、脚本）→ 使用文件写入工具将JSON负载写入文件（这完全绕过了shell），然后使用
```
--file
```
参数运行。

bash

undefined

Step 1 — agent writes /tmp/process.json with content like:

步骤1 — Agent将如下内容写入/tmp/process.json：

{

"command": "sh -lc 'python3 -c "print(\"hello\")"'",

"name": "cve-check",

"waitForCompletion": true

}

Step 2 — execute it

步骤2 — 执行命令

bl run sandbox my-sandbox --path /process --file /tmp/process.json

undefined

bl run sandbox my-sandbox --path /process --file /tmp/process.json

undefined

Deploy an agent

部署Agent

bash

bl new agent my-agent
cd my-agent
bl serve --hotreload    # Test locally
bl deploy               # Deploy to cloud
bl chat my-agent        # Chat with it

bash

bl new agent my-agent
cd my-agent
bl serve --hotreload    # 本地测试
bl deploy               # 部署到云端
bl chat my-agent        # 与Agent聊天

Manage sandboxes

管理沙箱

bash

bl get sandboxes                    # List all
bl get sandbox my-sandbox --watch   # Watch status
bl connect sandbox my-sandbox       # Interactive terminal
bl logs sandbox my-sandbox --follow # Stream logs
bl delete sandbox my-sandbox        # Clean up

bash

bl get sandboxes                    # 列出所有沙箱
bl get sandbox my-sandbox --watch   # 监控状态
bl connect sandbox my-sandbox       # 打开交互式终端
bl logs sandbox my-sandbox --follow # 流式查看日志
bl delete sandbox my-sandbox        # 清理资源

Multi-workspace deployment

多工作区部署

bash

bl workspaces dev     # Switch to dev
bl deploy             # Deploy to dev
bl workspaces prod    # Switch to prod
bl deploy             # Deploy to prod

bash

bl workspaces dev     # 切换到dev工作区
bl deploy             # 部署到dev环境
bl workspaces prod    # 切换到prod工作区
bl deploy             # 部署到prod环境