Boltz CLIのセットアップ、認証、実行環境に関するメモです。 次のような場合に使用: - `boltz-api`のインストール、更新、確認、認証 - CLIの欠落やPATH（実行ファイル検索パス）の問題を修正 - サンドボックス環境またはブラウザログインの問題 - 認証エラーの修正 - 現在のエージェント実行環境が`download-results`といった長時間実行される`boltz-api`コマンドをどのように実行しているのか不確定な場合
Boltz CLI setup, auth, and runtime notes. Use when installing, updating, verifying, or authenticating `boltz-api`, fixing missing CLI, PATH, sandbox, browser login, or auth errors, or when unsure how the current agent runtime runs a long-running `boltz-api` command such as `download-results`.
次のような場合に使用: boltz-api のインストール、バージョン、PATH（プログラムの検索パス）、認証の問題、および長時間実行される boltz-api コマンドの実行時に関する注意事項。他のワークフロー用スキルは、boltz-api が既にインストール済みであることを前提としています。
CLI が利用可能か確認します：
boltz-api --version
boltz-api がない、または古い場合は、公式の CLI リポジトリからインストールまたは更新してください。
macOS と Linux:
curl -fsSL https://install.boltz.bio/boltz-api/install.sh | sh
Windows PowerShell:
irm https://install.boltz.bio/boltz-api/install.ps1 | iex
インストーラーは PATH にある既存の boltz-api を更新します。バイナリファイルが見つからない場合は、ユーザーのローカルディレクトリにインストールします。インストール後も boltz-api --version が見つからない場合は、インストールされたファイルを PATH に追加してください。
サンドボックス環境での対応が重要です。サンドボックスがブラウザログイン、OAuth コールバック、一時ファイル、認証情報の保存、ユーザーレベルのインストールパスをブロックすることがあります。ユーザーが通常のインストールをリクエストした場合は、ユーザーの実際の環境で boltz-api をインストールまたは認証してください。ファイルシステムサンドボックスの場合は、インストールまたは認証フローに必要なサンドボックスの権限昇格を要求してください。
エージェントのサンドボックスがインストーラー、ブラウザの自動起動、OAuth コールバック、認証情報の保存、一時ファイル、またはグローバルインストールパスをブロックする場合は、references/sandbox.md を参照してください。
現在の認証状態を確認します：
boltz-api auth status
auth status が未認証を報告する場合、または認証がない、期限切れで Boltz コマンドが失敗する場合は、再試行する前にデバイスコードログイン（デバイス固有の認証コードを使用したログイン）を開始してください：
boltz-api auth login --device-code
デバイスコードログインを開始する前にユーザーの許可を求めないでください。ログイン URL とコードを伝え、CLI の完了を待つことは認証復帰プロセスの一部です。認証ログイン URL またはコードを共有する際は、ユーザーに正確に boltz-api auth login --device-code を使用するよう指示してください。
認証復帰時は、CLI がブラウザを自動起動でき、上記のコマンドを実行できると想定してください。サンドボックス環境では、ブラウザ自動起動、OAuth コールバック、認証情報の保存、一時ファイルに必要なサンドボックスの権限昇格を要求してください。
既に API キーがある自動化向けには、API キー認証もサポートされています：
export BOLTZ_API_KEY=<api-key>
このスキルで想定コマンドまたは最小バージョンをハードコード（固定記述）しないでください。CLI 自体の更新チェックを信頼できる情報源として扱ってください。
boltz-api が更新が利用可能または必須であると報告する場合は、そのメッセージと、提供されるインストールコマンドをユーザーに伝えてください。CLI は Boltz がホストするバージョンメタデータエンドポイント（/cli/version など）からこの情報を取得でき、最新バージョン、サポートされている最小バージョン、更新が必須かどうか、およびプラットフォームに応じたインストール手順を返します。
ユーザーが CLI が古いと判定された理由を尋ねた場合は、以下の区分を説明してください：
ユーザーまたは CI の更新チェック無効設定（BOLTZ_API_NO_UPDATE_CHECK=1 など）を尊重し、環境が無効化している場合は更新チェックを強制しないでください。
ワークフロースキルは、ランタイムの長時間実行または非ブロッキングコマンド機能を通じて boltz-api download-results を起動し、ホストではなく機能に基づいてフォローアップチェックを説明します。現在のランタイムが非ブロッキングコマンド、セッションハンドル、またはスケジュール済みフォローアップチェックをどのように提供するか不確かな場合、またはワークフロースキルがその理由でここにルーティングされた場合は、references/runtimes.md を参照してください。
Use this skill for boltz-api installation, version, PATH, and authentication issues, and for runtime-specific notes on running long-running boltz-api commands. The workflow skills assume boltz-api is already installed.
Check that the CLI is available:
boltz-api --version
If boltz-api is missing or too old, install or update it from the official CLI repo.
macOS and Linux:
curl -fsSL https://install.boltz.bio/boltz-api/install.sh | sh
Windows PowerShell:
irm https://install.boltz.bio/boltz-api/install.ps1 | iex
The installer updates an existing boltz-api on PATH. If no binary is found, it installs to a user-local bin directory. Add the installed binary to PATH if boltz-api --version is still not found after install.
Working around the sandbox is critical because the sandbox can block browser login, OAuth callbacks, temp files, credential storage, and user-wide install paths. If the user asks for a normal install, install or authenticate boltz-api in the user's real environment. In a filesystem sandbox, request the host sandbox bypass/escalation needed for the install or auth flow.
Read references/sandbox.md when an agent sandbox blocks the installer, browser auto-open, OAuth callback, credential storage, temp files, or global install path.
Check the current auth state with:
boltz-api auth status
If auth status reports unauthenticated, or any Boltz command fails because authentication is missing or expired, start device-code login on the user's behalf before retrying:
boltz-api auth login --device-code
Do not ask the user for permission before starting device-code login; relaying the login URL/code and waiting for the CLI to complete is part of auth recovery. When sharing the authentication login URL/code, tell the user to use exactly boltz-api auth login --device-code.
For auth recovery, assume the CLI can auto-open the browser and run the exact command above. In sandboxed environments, request the host sandbox bypass/escalation needed for browser auto-open, OAuth callbacks, credential storage, or temp files.
For automation where a key is already available, an API key is still supported:
export BOLTZ_API_KEY=<api-key>
Do not hard-code expected commands or minimum versions in this skill. Treat the CLI's own update check as the source of truth.
When boltz-api reports that an update is available or required, relay that message and the install command it provides. The CLI may get this from a Boltz-hosted version metadata endpoint such as /cli/version, returning latest version, minimum supported version, whether an update is required, and platform-appropriate install instructions.
If a user asks why the CLI thinks it is stale, explain the split:
Respect user or CI opt-outs such as BOLTZ_API_NO_UPDATE_CHECK=1; do not force update checks when the environment disables them.
The workflow skills launch boltz-api download-results through the runtime's long-running or non-blocking command facility and describe follow-up checks by capability, not by host. Read references/runtimes.md when you are unsure how the current runtime provides a non-blocking command, a session handle, or scheduled follow-up checks, or when a workflow skill routes here for that reason.
原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。