Blaxel CLI
Blaxel CLI 是一个从命令行管理 Blaxel 云资源的工具，命令名为 bl，用于管理 agents、sandboxes、jobs、MCP servers、drives 等资源。
用途
该 CLI 的主要用途是让开发者通过命令行以声明式或命令式方式管理 Blaxel 云平台上的各类资源，包括部署智能体、创建和操作沙箱、管理 job、MCP 服务器以及 drives，并支持多工作区切换与部署。
前置条件
使用前，bl 命令必须位于 PATH 中。可通过以下命令检查：
bl version
如果尚未安装，请使用对应操作系统的官方安装程序。
macOS 或 Linux：
curl -fsSL https://blaxel.ai/install.sh | sh
Windows PowerShell：
irm https://blaxel.ai/install.ps1 | iex
按照安装程序关于 PATH 或重新加载 shell 的说明操作，然后完成设置：
bl setup
Setup 会安装 Blaxel skills 并配置受支持的编码智能体。在终端中，它还会提供浏览器登录选项。如果安装程序已完成设置，请验证结果，而不是重复执行。
在没有终端的情况下运行时，使用 bl setup --yes。该环境下 Setup 会跳过浏览器登录。如果仍需要登录，请运行 bl login，展示其安全浏览器 URL，并在用户批准后继续。从命令输出中确认所选工作区；不要猜测工作区名称，也不要要求粘贴凭据。
对于无人值守的自动化，请使用通过环境安全提供的现有 BL_API_KEY 和 BL_WORKSPACE。命令可以直接使用这些变量；不要启动浏览器登录，也不要在 agent 配置中持久保存密钥。
验证已安装的命令和当前活动工作区：
bl version bl workspaces --current
将空的工作区输出视为登录不完整。
全局标志
所有命令都支持以下标志：
标志 | 描述
-o, --output <format> | 输出格式：pretty、yaml、json、table -w, --workspace <name> | 针对此命令覆盖工作区 -v, --verbose | 启用详细输出 -u, --utc | 启用 UTC 时区 --skip-version-warning | 跳过版本警告
非交互模式
对于会提示输入（确认、选择）的命令，添加 -y 或 --yes 以自动确认。在非交互 / 无 TTY 环境（脚本、CI、智能体）中运行时，这是必需的。
可用命令
bl apply # 使用 YAML 文件以声明式方式将配置更改应用到资源。 bl chat # 启动与已部署智能体的交互式聊天会话。 bl connect # 打开到沙箱的交互式终端会话 bl delete # 从工作区删除 Blaxel 资源。 bl deploy # 将 Blaxel 项目部署到云端。 bl drive # 管理沙箱上的 drives 和 drive mounts。 bl fork # 通过 fork 现有沙箱创建新的沙箱或应用。 bl get # 检索工作区中 Blaxel 资源的信息。 bl login # 通过 Blaxel 进行身份验证以访问工作区。 bl logout # 删除工作区存储的凭据。 bl logs # 查看 Blaxel 资源的日志。 bl mcp # 使用现有 bl 登录，通过 stdio 提供托管的 Blaxel MCP 工具。 bl new # 从模板创建新的 Blaxel 资源。 bl push # 构建容器镜像并推送到 Blaxel registry，但不创建部署。 bl run # 使用自定义输入数据执行 Blaxel 资源。 bl serve # 为 Blaxel 项目启动本地开发服务器。 bl setup # 在此机器上设置 Blaxel 所需的一切，然后登录。 bl share # 将 Blaxel 资源共享到账户中的其他工作区。 bl skills # 管理用于编码智能体的 Blaxel skills bl token # 检索指定工作区的身份验证令牌。 bl unshare # 从其他工作区移除共享的 Blaxel 资源。 bl upgrade # 将 Blaxel CLI 升级到最新版本。 bl version # 打印版本号 bl workspaces # 列出并管理工作区。
参考文档
apply - 使用 YAML 文件以声明式方式将配置更改应用到资源。
chat - 启动与已部署智能体的交互式聊天会话。
connect - 打开到沙箱的交互式终端会话
delete - 从工作区删除 Blaxel 资源。
deploy - 将 Blaxel 项目部署到云端。
drive - 管理沙箱上的 drives 和 drive mounts。
fork - 通过 fork 现有沙箱创建新的沙箱或应用。
get - 检索工作区中 Blaxel 资源的信息。
login - 通过 Blaxel 进行身份验证以访问工作区。
logout - 删除工作区存储的凭据。
logs - 查看 Blaxel 资源的日志。
mcp - 使用现有 bl 登录，通过 stdio 提供托管的 Blaxel MCP 工具。
new - 从模板创建新的 Blaxel 资源。
push - 构建容器镜像并推送到 Blaxel registry，但不创建部署。
run - 使用自定义输入数据执行 Blaxel 资源。
serve - 为 Blaxel 项目启动本地开发服务器。
setup - 在此机器上设置 Blaxel 所需的一切，然后登录。
share - 将 Blaxel 资源共享到账户中的其他工作区。
skills - 管理用于编码智能体的 Blaxel skills
token - 检索指定工作区的身份验证令牌。
unshare - 从其他工作区移除共享的 Blaxel 资源。
upgrade - 将 Blaxel CLI 升级到最新版本。
version - 打印版本号
workspaces - 列出并管理工作区。
发现选项
要查看任何命令可用的子命令和标志，请运行 --help：
bl --help bl deploy --help bl get --help bl get agents --help
常见工作流
创建沙箱、运行命令并获取其日志
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
2. 检索沙箱配置
bl get sandbox my-sandbox
3. 在沙箱中执行命令并获取命令的 stdout
bl run sandbox my-sandbox --path /process --data '{"command": "echo hello world", "name": "my-cmd", "waitForCompletion": true}'
4. 如果 stdout 不足，检索该命令的日志
bl logs sandbox my-sandbox my-cmd
在沙箱中运行复杂命令（智能体指南）
bl run sandbox ... --path /process --data '<json>' 要求 JSON 负载能通过 shell 引号处理。一旦命令嵌入嵌套引号、反斜杠、多行或 sh -lc / python3 -c 之类的解释器，内联 --data 就会变得脆弱，API 会以 400 Bad Request: invalid character ... in string escape code 拒绝请求。
面向智能体的决策规则：
命令没有单引号、没有反斜杠、没有换行 → 直接使用 --data '{"command": "...", "waitForCompletion": true}'。
任何更复杂的情况（嵌套引号、转义、多行、脚本）→ 使用 Write/文件创建工具将 JSON 负载写入文件（这完全绕过 shell），然后使用 --file 运行。
步骤 1 — 智能体写入 /tmp/process.json，内容类似：
{
"command": "sh -lc 'python3 -c "print(\"hello\")"'",
"name": "cve-check",
"waitForCompletion": true
}
步骤 2 — 执行它
bl run sandbox my-sandbox --path /process --file /tmp/process.json
部署智能体
bl new agent my-agent cd my-agent bl serve --hotreload # 本地测试 bl deploy # 部署到云端 bl chat my-agent # 与其聊天
管理沙箱
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 # 清理
多工作区部署
bl workspaces dev # 切换到 dev bl deploy # 部署到 dev bl workspaces prod # 切换到 prod bl deploy # 部署到 prod