blaxel-cli

Blaxel CLI

用于从命令行管理 Blaxel 云资源的 CLI：Agent、沙箱、 作业、MCP 服务、驱动器等。

前置条件

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

设置过程会安装 Blaxel 技能并配置受支持的编码 Agent。在终端中，它还会提供浏览器登录选项。如果安装程序已完成设置，请验证结果，而不要重复操作。

在没有终端的环境中运行时，请使用 bl setup --yes。在此环境中，设置过程会跳过浏览器登录。如果仍需登录，请运行 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、Agent）中运行时，必须使用此选项。

可用命令

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 fork        # Create a new sandbox or application by forking an existing sandbox.
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 mcp         # Serve the hosted Blaxel MCP tools over stdio using your existing bl login.
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 setup       # Set up everything Blaxel needs on this machine, then log in.
bl share       # Share Blaxel resources with other workspaces in your account.
bl skills      # Manage Blaxel skills for coding agents
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.

参考文档

• apply - 使用 YAML 文件以声明式方式应用配置更改 到资源。
• chat - 与已部署的 Agent 启动交互式聊天会话。
• connect - 打开与沙盒的交互式终端会话
• delete - 从工作区删除 Blaxel 资源。
• deploy - 将 Blaxel 项目部署到云端。
• drive - 管理沙盒上的驱动器和驱动器挂载。
• fork - 通过分叉现有沙盒来创建新的沙盒或应用。
• get - 获取工作区中 Blaxel 资源的信息。
• login - 通过 Blaxel 进行身份验证，以访问工作区。
• logout - 删除工作区的已存储凭据。
• logs - 查看 Blaxel 资源的日志。
• mcp - 使用现有的 bl login，通过 stdio 提供托管的 Blaxel MCP 工具。
• new - 根据模板创建新的 Blaxel 资源。
• push - 构建容器映像并推送到 Blaxel 注册表，但不创建部署。
• run - 使用自定义输入数据执行 Blaxel 资源。
• serve - 为 Blaxel 项目启动本地开发服务器。
• setup - 在此计算机上设置 Blaxel 所需的一切，然后登录。
• share - 与账户中的其他工作区共享 Blaxel 资源。
• skills - 管理编码 Agent 的 Blaxel 技能
• token - 获取指定工作区的身份验证令牌。
• unshare - 从其他工作区移除共享的 Blaxel 资源。
• upgrade - 将 Blaxel CLI 升级到最新版本。
• version - 打印版本号
• workspaces - 列出并管理 Blaxel 工作区。

查找选项

要查看可用的子命令和标志，请对任意命令运行 --help：

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

常见工作流

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

# 1. Create a sandbox with 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. Retrieve sandbox configuration
bl get sandbox my-sandbox

# 3. Execute a command in the sandbox and get stdout of the command
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
bl logs sandbox my-sandbox my-cmd

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

bl run sandbox ... --path /process --data '<json>' 要求 JSON 负载在命令行引号处理后仍保持完整。一旦命令包含嵌套引号、反斜杠、多行内容，或 sh -lc / python3 -c 这样的解释器，内联 --data 就容易出错，API 会以 400 Bad Request: invalid character ... in string escape code 拒绝请求。

Agent 的判断规则：

1. 命令中没有单引号、反斜杠或换行符 → 直接使用 --data '{"command": "...", "waitForCompletion": true}'。
2. 更复杂的情况（嵌套引号、转义字符、多行内容、脚本） → 使用 Write/文件创建工具将 JSON 负载写入文件（这样可以完全绕过 shell），然后使用 --file 运行。

# Step 1 — agent writes /tmp/process.json with content like:
# {
#   "command": "sh -lc 'python3 -c \"print(\\\"hello\\\")\"'",
#   "name": "cve-check",
#   "waitForCompletion": true
# }
#
# Step 2 — execute it
bl run sandbox my-sandbox --path /process --file /tmp/process.json

部署 Agent

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

管理沙盒

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

多工作区部署

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