blaxel-cli

Blaxel CLI

コマンドラインから Blaxel クラウドリソース（エージェント、サンドボックス、 ジョブ、MCP サーバー、ドライブなど）を管理する CLI です。

前提条件

bl コマンドが PATH 上で使用できる必要があります。確認するには、次を実行します。

bl version

インストールされていない場合は、このオペレーティングシステム向けの公式インストーラーを使用します。

macOS または Linux：

curl -fsSL https://blaxel.ai/install.sh | sh

Windows PowerShell：

irm https://blaxel.ai/install.ps1 | iex

インストーラーの PATH またはシェルの再読み込みに関する指示に従い、その後セットアップを完了します。

bl setup

セットアップでは Blaxel スキルをインストールし、サポートされているコーディングエージェントを設定します。ターミナルでは、ブラウザーでのログインも案内されます。インストーラーですでにセットアップが完了している場合は、繰り返すのではなく、結果を確認してください。

ターミナルを使用せずに実行する場合は、bl setup --yes を使用します。この環境では、セットアップ中のブラウザーログインは省略されます。それでもサインインが必要な場合は、bl login を実行して、安全なブラウザー URL を提示し、ユーザーの承認後に続行してください。コマンド出力から選択されたワークスペースを確認してください。ワークスペース名を推測したり、認証情報を貼り付けるよう求めたりしないでください。

無人自動化では、環境経由で安全に渡された既存の BL_API_KEY と BL_WORKSPACE を使用してください。コマンドはこれらを直接使用できます。ブラウザーログインを開始したり、エージェント設定にキーを保存したりしないでください。

インストールされたコマンドとアクティブなワークスペースを確認します。

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       # 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 - デプロイ済みのエージェントとの対話型チャット セッションを開始します。
• connect - サンドボックスへの対話型ターミナル セッションを開きます。
• delete - ワークスペースから Blaxel リソースを削除します。
• deploy - Blaxel プロジェクトをクラウドにデプロイします。
• drive - サンドボックス上のドライブとドライブのマウントを管理します。
• fork - 既存のサンドボックスをフォークして、新しいサンドボックスまたはアプリケーションを 作成します。
• get - ワークスペース内の Blaxel リソースに関する情報を 取得します。
• login - ワークスペースにアクセスするため、Blaxel で認証します。
• logout - ワークスペースの保存済み認証情報を削除します。
• logs - Blaxel リソースのログを表示します。
• mcp - 既存の bl login を使って、ホストされた Blaxel MCP ツールを stdio 経由で 提供します。
• new - テンプレートから新しい Blaxel リソースを作成します。
• push - デプロイを作成せずに、コンテナイメージをビルドして Blaxel レジストリにプッシュします。
• run - カスタム入力データを使って Blaxel リソースを実行します。
• serve - Blaxel プロジェクト用のローカル開発サーバーを 起動します。
• setup - このマシンで Blaxel に必要なものをすべてセットアップし、 ログインします。
• share - アカウント内の他のワークスペースと Blaxel リソースを 共有します。
• skills - コーディングエージェント用の 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

サンドボックスで複雑なコマンドを実行する（エージェント向けガイドライン）

bl run sandbox ... --path /process --data '<json>' では、JSON ペイロードが シェルのクォーティングを通過する必要があります。コマンドに入れ子の引用符、 バックスラッシュ、複数行、または sh -lc / python3 -c のようなインタープリターが 含まれるとすぐに、インラインの --data は扱いにくくなり、API は 400 Bad Request: invalid character ... in string escape code というエラーでリクエストを拒否します。

エージェント向けの判断基準：

1. コマンドにシングルクォート、バックスラッシュ、改行がない → そのまま --data '{"command": "...", "waitForCompletion": true}' を使います。
2. それより複雑なもの（入れ子の引用符、エスケープ、複数行、スクリプト）→ JSON ペイロードを Write／ファイル作成ツールでファイルに書き込みます（これによりシェルを完全に迂回できます）。その後、 --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

エージェントをデプロイする

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