CLIとアプリが状態を共有する仕組み
Beam Benchのエージェント状態モデル。CLIから見えるもの、アプリから見えるもの、そして両者が接続する場所。
Beam Bench CLIとデスクトップアプリは、同じバックエンドを利用する2つのクライアントです。どちらからも同じプロジェクト、同じマシン接続、同じカメラ状態を確認できます。スクリプトからアプリを操作したい場合は、状態をどのように共有しているかを理解しておくと便利です。
モデル
Beam Bench内部には、次の情報を管理する単一の信頼できる情報源があります。
- アクティブなプロジェクト
- マシン接続
- カメラ状態
- エージェントの機能／状態サーフェス
デスクトップアプリのUIは、この状態の利用者の1つです。CLIも別の利用者です。HTTP / WebSocket APIも同じサーフェスです。
CLIでできること
beambench-cli agent state --jsonは、プロジェクト、マシン、選択内容、カメラの現在の状態を、安定したJSONスキーマで返します。アプリに現在読み込まれている内容を確認するには、これを使用します。
beambench-cli agent capabilities --jsonは、利用可能な操作のレジストリを返します。どのCLIサブコマンドがどのバックエンド操作に対応するかも確認できます。
beambench-cli agent guide --jsonは、外部エージェント（Claudeなど）がアプリを操作する方法について、ワークフローのヒントを返します。
CLIでできないこと
CLIには独自のUI状態がありません。ツールの選択、パネルの表示、ダイアログの表示はできません。これらはアプリ側の操作なので、CLIからではなくアプリで実行してください。
CLIの実行時にアプリが必要な場合
キャンバスをオーバーレイ付きでレンダリングしたり、カメラフレームをキャプチャしたりするなど、一部の操作ではアプリが実際の処理を行う必要があります。CLIがリクエストを送信し、アプリが処理を実行します。結果はCLIに返されます。
camera overlay renderコマンドはこの方式で動作します。アプリが完了するかタイムアウトするまで、CLIはブロックします（15 s）。
アプリが必要なコマンドとヘッドレスコマンド
| アプリの実行が必要か | 例 |
|---|---|
| いいえ（ヘッドレス） | beambench-cli design render --png、beambench-cli project save、beambench-cli export svg、beambench-cli agent state |
| はい | beambench-cli camera overlay render、beambench-cli camera capture（ネイティブカメラ使用時）、UI状態の確認全般 |