cockpit CLI

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

セットアップと接続

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

macOSとLinuxのインストールとアンインストールは、Cockpitが管理するブロックだけを変更します。それ以外のシェル設定、既存のPATH行、空行、行末は維持されます。~/.agi-tools/binがすでに利用者管理の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を確認してください。

タスクlistenerが初回起動中または復旧中の場合、task、talk、HTML、side-panelなどのコマンドは、共有する20秒の認証期限内でlistenerの準備を待ちます。portが変わっても、PID、token、IPC directoryが同じinstanceであると確認できる場合だけ新しいportへ追従し、古いportへ資格情報を送信しません。期限内に復旧しなければ終了コード7で失敗するため、cockpit doctorでlistenerStateと経路ごとの理由を確認してから同じコマンドを再実行してください。

JSON結果を確認する

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

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

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

Windowsで実行する

PowerShellのcockpitランチャーは、応答をUTF-8として読み取り、成功・失敗ともJSONを一行だけ出力します。HTTPエラーではサーバーのJSON本文とcodeを維持し、JSONではないHTTPエラーにはhttp_error、予期しない失敗にはunexpected_errorを付けます。PowerShellのエラー表示を解析せず、ほかのOSと同じくJSONのok、code、errorを確認できます。

--stdinはPowerShellのパイプ入力を受け取ります。PowerShellがファイルを文字列へ変換してからCLIへ渡すため、Get-Contentでは文字コードを明示してください。複数の文字列は改行で結合されます。ファイル本文をそのまま渡す必要がある場合は、対応する--*-fileオプションを使います。空のパイプ入力はstdin_no_inputで失敗します。

Get-Content report.html -Raw -Encoding UTF8 | cockpit html show --stdin

Windows版CLIの内部処理にNode.jsを別途インストールする必要はありません。ランチャーはAGI Cockpitの実行ファイルをランタイムとして使い、アプリを閉じている場合もインストール済みのMicrosoft Store版を検出できます。cockpit doctorのnodeRuntimeで、実際に使ったpathとsourceを確認できます。利用可能なランタイムがない場合はnode_runtime_unavailable、ランタイムがJSONを返さない場合はnode_runtime_failedになります。

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

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

親タスクと子タスクの状態だけをまとめて確認する場合はcockpit task list --parent <id>を使い、全子孫には--recursive、完了済みを含める場合は--allを追加します。親指定の応答と通常一覧の--summaryは、会話やモデル設定を除いた軽量summaryとsnapshot時刻generatedAtを返します。

AGIラボ会員としてサインインしているローカルCockpitでは、task create|run --smart-routingが登録済み方針からエージェント、モデル、推論レベルと、未指定の場合は作業場所を選びます。cockpit settingsではsmartRouting.enabledとsmartRouting.policyを読み書きでき、新規タスク画面と同じアカウント別設定を扱います。方針の複数行入力には--stdinまたは--fileを使います。--smart-routingは--hostと、選択対象を手動で固定するオプションには対応しません。手順と失敗条件はタスク管理（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" --media ./evidence.png --wait
cockpit task retry-start <task-id>
cockpit task goal start <task-id> --objective-file goal.md

作成時の表示モードは対応エージェントで--ui-mode visual|terminal、作成時と追加指示のローカル添付は繰り返し指定できる--mediaで設定します。retry-startは起動失敗、resumeは停止済みプロセス、reconnectは既存ビジュアルセッションへの再接続に使い分けます。Goal対応中のビジュアルタスクだけがgoal startを受け付けます。

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

task getのturnRequestsで保留中のツール承認や質問を確認し、task approve、deny、answerで対象へ応答できます。task cancelはタスクを残して現在のターンだけを中断し、compactは会話を圧縮します。task clear --confirmは会話を破棄するため、対象タスクと必要な履歴を確認してから実行します。task approval-modeは、そのタスクの承認モードを読み取りまたは変更します。対応範囲と手順はタスク管理（CLI）を参照してください。

タスクの完了と削除は異なります。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 secret requestは、DesktopまたはHTTPS接続のPWAへ、指定したブラウザーのパスワード欄へ一度だけ入力する依頼を作ります。CLIは目的と入力先を指定し、statusとcancelで状態を扱いますが、値を受け取る引数、標準入力、取得コマンドはありません。値は利用者がCockpitの画面へ入力します。成功と失敗の応答には接続先のinstanceが含まれ、失敗時は固定のcodeと説明用のerrorを返します。自動処理は翻訳される説明文ではなくcodeで分岐し、再送前にinstanceと失敗理由を確認してください。利用条件と境界はセキュリティとデータ、正確なコードと復旧方法はcockpit secretリファレンスを参照してください。

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

AutorunとFleetを使う

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

cockpit fleetは依存関係付きの複数タスクをRunとして実行します。YAMLの検証、gate、再試行、再開、Runタイトル、各ノードの進捗を扱います。完了・失敗・停止・一時停止したRunでは、complete-tasks --dry-runで対象を確認してから残るタスクをまとめて完了できます。単純な定期起動にはAutorun、依存する複数処理にはFleetを使います。実践手順はFleet、全構文はcockpit fleet Referenceを参照してください。

認証情報とCockpitプロバイダーを設定する

名前付きエージェントアカウントの表示名は、現在の名前またはプロファイルIDを指定して変更できます。

cockpit accounts rename work "Work (EU)" --agent-type codex

変更されるのは表示名だけで、ID、認証情報、タスクとAutorunの割り当ては維持されます。defaultアカウントは変更できません。Fleet YAMLは実行時にaccount: <name>を名前で解決するため、変更前の名前を参照するFleetも更新してください。名前の制約と画面からの操作はアカウントとAutoを参照してください。

cockpit settingsはOpenRouter、OpenCode Go、OpenCode Zen、AnthropicのAPIキーを暗号化ストレージへ保存・削除できます。キーはコマンド引数へ書かず、--stdinまたは--key-fileだけで渡します。取得結果は設定の有無だけを返し、値は返しません。

cockpit settings set agents.credential.openrouter --stdin
cockpit settings reset agents.credential.openrouter
cockpit settings set agents.provider.cockpit openrouter

Cockpit Agentのプロバイダーはopenrouter、opencode-go、opencode、lmstudioから選べます。キーを必要とするプロバイダーは、対応する認証情報が保存済みの場合だけ選択または既定値へリセットできます。これらの設定はローカルCockpitだけを対象にします。

cockpit settings refresh-models lmstudioは、保存済みのLM Studio URLを使ってキャッシュを迂回し、新しいモデル一覧を読み取ります。モデルを起動、停止、再読み込みせず、設定値も変更しません。接続できない場合はvalidation_unavailableを返します。

Hooksでイベントに反応する

cockpit hooksは、タスク完了、Ask、Autorun、Fleet、アプリの起動・終了、ホットキーをきっかけにローカルの処理を実行します。登録・テスト・対象の絞り込みと、設定画面での管理はHooksを参照してください。全イベント、オプション、実行結果はcockpit hooks Referenceにあります。

使用量を確認し、Codexの利用枠をリセットする

cockpit usageは対応プロバイダーとアカウントの使用量を読み取ります。Codexのリセットクレジットと有効期限も表示しますが、読み取りだけでは消費しません。cockpit usage reset --agent-type codex [--account <name>] --confirmは、有限のクレジットを一つ消費して、そのアカウントの現在のレート制限枠を解除します。取り消しも返金もできないため、--confirmを付ける前に対象アカウントと残数を確認してください。結果と終了コードはcockpit usage Referenceを参照してください。

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

cockpit devicesは、この端末と、同じtailnet上でCockpitのhealth checkに応答した端末をOS付きで一覧にします。Tailscale上でonlineでもCockpitが応答しない端末は一覧に含まれず、diagnostics.unreachableに理由が表示されます。Tailscaleがofflineまたはaddress未取得の端末はdiagnostics.notProbedへ集計されるため、空のdevicesだけでほかのCockpitがないと判断しないでください。cockpit devices selfは探索せず、この端末とaliasだけを返します。

対応するtask、autorun、accounts、fleet、hooksコマンドは、--hostでdeviceのhostまたは保存済みaliasを指定できます。ask list、ask answer、ask closeもリモートに対応しますが、Askの作成とrelay設定はローカル専用です。browser、App Surface、display、settings、usage、updateなど、host指定に対応しない操作はローカルのCockpitだけを対象にします。

リモート制御は、同じtailnetで、Tailscaleの所有者が同じコンピューターからならtokenなしで使えます。それ以外の接続はペアリング済みBearer tokenを使います。接続先がTailscale限定の場合、Tailscale peerでもloopbackでもない接続は拒否されます。ファイルパスとディレクトリは接続先コンピューターで解決されます。リモート応答にはdevice identityが含まれ、ローカルfile IPCへfallbackしません。

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

コマンド別Reference

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