cockpit CLI

cockpitは、AIエージェントと利用者が実行中のAGI Cockpitを操作するための正式なCLIです。タスク、確認、成果表示、ブラウザー、App Surface、Autorun、Fleet、Hooks、設定を、同じ状態と権限境界で扱います。

セットアップと接続

初回セットアップまたは画面左下のアプリメニューにある「セットアップ」からCLIをインストールします。macOSとLinuxではシェルのPATH、WindowsではユーザーPATHへランチャーが追加されます。状態は次で確認できます。

cockpit setup status
cockpit doctor
cockpit help

Cockpitから起動したタスクには、正しいローカルインスタンスと呼び出し元タスクの接続情報が渡されます。別インスタンスへ誤送信しそうな場合はinstance_mismatchで停止し、接続不能時に別のローカルインスタンスへ自動で切り替えません。

ローカルCLIは認証付きloopbackへ先に接続し、sandboxがloopbackまたはプロセス確認を制限している場合は、同じCockpitが渡したディレクトリのfile IPCへ自動で切り替えます。file IPCは一つのrequest IDを一度だけ書き、同じ応答を待つため、task createやtask sendを再送して重複実行しません。権限拡張は不要です。

cockpit doctorはpidVisibility、transports.loopback、transports.fileIpc、effectiveTransportを返します。終了コード7は、利用可能な両方の経路で認証できなかったことを示します。権限エラーと推測して再実行せず、失敗理由と対象instanceを確認してください。

JSON結果を確認する

すべてのコマンドはJSONを返します。成功はok: true、失敗はok: falseとerrorを持ち、安定したエラーではcodeも返ります。終了コードだけでなく、ok、code、対象ID、状態、検証フィールドを確認します。

Cockpitから起動したタスクでは、CLIのエラーメッセージがアプリの表示言語に従います。表示言語を変更した場合は、その後に起動するタスクから新しい言語が使われます。自動処理では翻訳されたerror本文ではなく、利用できる場合は安定したcodeで分岐してください。

--jsonはすべてのコマンドで一貫して受け付けます。長い指示、Markdown、引用、バッククォート、$を含む内容はシェル引数へ埋め込まず、--stdinまたは--instruction-file、--text-fileを使います。

タスクを起動して監督する

単発作成にはtask create、別タスクを起動して最初の報告まで待つ場合はtask runを使います。turn_completeは一つの応答ターンが終わったことを示し、タスク全体の完了ではありません。親子タスク、レポート、追加指示、完了の流れはタスク管理（CLI）を参照してください。

cockpit task run --instruction "Review the change" --directory /path/to/repo
cockpit task wait <task-id> --since <report-seq>
cockpit task send <task-id> --text "Continue" --wait

readyForNextPromptがfalseの確認待ちタスクへ新しい指示を重ねず、waitingReasonを確認します。permissionやquestionは進行中の確認、usage_limitはアカウント復旧、needsResumeはプロセス再開が必要な状態です。

タスクの完了と削除は異なります。CLIのtask completeは既定でGit Worktreeを削除し、維持する場合は--keep-worktreeが必要です。削除や一括操作の前に対象IDと保存すべき成果を確認してください。

Ask、display、HTMLを使い分ける

cockpit askは人の回答を待ち、回答後に同じタスクを再開します。cockpit displayは情報を前面表示するだけで回答を待ちません。cockpit htmlは生成したHTML Surfaceをタスクへ保存します。

Askを作成した後は、そのターンを終了して回答を待ちます。回答をpollしたり、回答に依存する処理を続けたりしません。Askへの回答はOSや外部サービスの実行権限そのものではありません。

ブラウザーとApp Surfaceを操作する

Webページはcockpit browser、起動済みAndroidまたはiOS Simulatorはcockpit appを使います。ブラウザーではIdentityを確認し、クリックや送信にはURL、テキスト、要素状態、通信などの事後条件を付けます。App Surfaceではアクセシビリティラベルを優先し、操作後に新しいsnapshotまたは期待条件を確認します。

外部リンク、ファイルアップロード、物理端末、秘密入力には追加の安全境界があります。配送済みの入力を確認せず再送すると二重操作になる可能性があります。

実践手順はcockpit browser、Browser Identity、App Surfaceを参照してください。

AutorunとFleetを使う

cockpit autorunは一度、間隔、cronで新規タスクを起動するか、既存タスクへ指示を送ります。会員確認は作成時だけでなく実行時にも行われます。保存済みのランタイム設定を利用できなくなった場合、別設定へ無言で切り替えずAutorunを無効にします。

cockpit fleetは依存関係付きの複数タスクをRunとして実行します。YAMLの検証、gate、再試行、再開、Runタイトル、各ノードの進捗を扱います。単純な定期起動にはAutorun、依存する複数処理にはFleetを使います。実践手順はFleet、全構文はcockpit fleet Referenceを参照してください。

Hooksでイベントに反応する

cockpit hooksは、タスク、Ask、Autorun、Fleet Run、アプリのライフサイクル、ホットキーのイベントに対して、ローカルでシェルアクションを実行する宣言を登録します。フィルターでイベントのpayloadを絞り、hooks runsで失敗を確認し、依存する前にアクションを明示的にテストしてください。Hookの登録は任意のローカルコード実行にあたるため、このコマンド群は--hostを拒否します。イベントpayload、安全策、正確なコマンド結果はcockpit hooks Referenceを参照してください。

Hookの追加、変更、テストはCLIから行います。画面左下のアプリメニューから「設定」→「Hooks」を開くと、登録済みHookの有効化と無効化、直近の実行日時・イベント・終了コード・標準出力・標準エラーの確認、Hookの削除ができます。削除前には画面内で確認が必要です。Hookを削除しても既存の実行履歴は残るため、履歴も含めた保存境界はセキュリティとデータを確認してください。

ローカルとリモートを区別する

taskとautorunの対応コマンドは、登録済みの端末aliasまたはホストを--hostで指定できます。ホスト指定がない設定、ブラウザー、表示などのコマンドはローカルのCockpitだけを操作します。

Remote Accessの停止、Identityデータの消去、アカウント削除、CLIアンインストールなどは明示的な確認フラグを要求します。フラグがあることを実行許可の代わりにせず、利用者の指示と正確な対象を確認してください。

コマンド別Reference

以下のReferenceはelectron/cockpit-docs/helpからビルド時に自動生成され、アプリ内のcockpit help [topic]と同じ正本を使います。Creative workflowsは公式ガイドの対象外ですが、CLI正本の正確性を保つため、既存の関連コマンドも生成Referenceには含まれます。