cli-anything-iterm2-ctl

cli-anything-iterm2

iTerm2 用のステートフルな CLI ハーネスです。WebSocket 経由で iTerm2 Python API を使用して、稼働中の iTerm2 プロセスを制御します。

前提条件

1. macOS + iTerm2 が稼働していること: brew install --cask iterm2
2. Python API が有効であること: iTerm2 → Preferences → General → Magic → Enable Python API
3. インストール: pip install cli-anything-iterm2（またはソースから pip install -e .）

基本構文

cli-anything-iterm2 [--json] <group> <command> [OPTIONS] [ARGS]

機械可読な出力には常に --json を使用してください（エージェントでの使用に必須）。

コマンドグループ

グループ	目的
app	アプリのステータス、ワークスペースのスナップショット、コンテキスト管理、アプリレベルの変数、モーダルダイアログ、ファイルパネル
window	ウィンドウの作成、一覧表示、クローズ、リサイズ、フルスクリーン化
tab	タブの作成、一覧表示、クローズ、アクティブ化、方向指定による分割ペインの移動
session	テキストの送信、生バイトの注入、画面の読み取り、スクロールバック全体、ペインの分割、プロンプト検出
profile	プロファイルの一覧表示、プロファイル詳細の取得、カラープリセットの一覧表示/適用
arrangement	ウィンドウレイアウトの保存と復元
tmux	完全な tmux -CC 統合: ブートストラップ、接続、ウィンドウ、コマンド
broadcast	ブロードキャストドメインによるペイン間のキーストローク同期
menu	任意の iTerm2 メニュー項目をプログラムから呼び出し
pref	グローバルな iTerm2 設定の読み取り/書き込み、有効なすべてのキーの一覧表示、tmux 設定

既存のワークスペースでの状況把握

既存のペインがあるセッションに入り、各ペインの画面内容をすべて読むことなく何が実行されているかを把握する必要がある場合は、app snapshot を使用します:

cli-anything-iterm2 --json app snapshot

すべてのウィンドウにわたる各セッションの名前、現在のディレクトリ、フォアグラウンドプロセス、user.role ラベル、最後に表示された出力行を返します。

命名規則 — 後で見つけられるように、ワークスペースのセットアップ時にペインにラベルを付けます:

cli-anything-iterm2 session set-var user.role "api-server"
cli-anything-iterm2 session set-var user.role "log-tail"
cli-anything-iterm2 session set-var user.role "editor"

app snapshot はこれらのロールをプロセスやパスとともに表示するため、1 回の呼び出しで全体像を把握できます。

典型的なエージェントのワークフロー

# 1. Orient — snapshot every session: name, path, process, role, last output line
cli-anything-iterm2 --json app snapshot

# 2. Establish context (saves window/tab/session IDs for subsequent commands)
cli-anything-iterm2 app current

# 3. Interact — no --session-id needed once context is set
cli-anything-iterm2 session send "git status"
cli-anything-iterm2 --json session scrollback --tail 200 --strip

# 4. Create a multi-pane workspace — label panes so snapshot identifies them later
cli-anything-iterm2 session split --vertical --use-as-context
cli-anything-iterm2 session send "python3 -m http.server 8000"
cli-anything-iterm2 session set-var user.role "http-server"

リファレンスファイル

タスクに必要なものだけを読んでください — 各ファイルは 1 つの狭い関心事項のみを扱っています（約 10〜30 行）:

ファイル	次の場合に読む...
references/session-io.md	テキストの送信、バイトの注入、画面/スクロールバックの読み取り、選択範囲の取得
references/session-control.md	ペインの分割、セッションのアクティブ化/クローズ、リサイズ、名前変更、セッション変数
references/session-shell-integration.md	wait-prompt、wait-command-end、get-prompt。信頼性の高い送信→待機→読み取りパターン
references/layout-window-tab.md	ウィンドウとタブの作成/クローズ/リサイズ、分割ペインの移動
references/layout-arrangement.md	ウィンドウレイアウトの保存と復元
references/app-context.md	スナップショット（状況把握）、ステータス、コンテキスト管理、アプリ変数、モーダルダイアログ、ファイルパネル
references/profile-pref.md	プロファイルの一覧表示/取得/プリセット、設定の読み取り/書き込み、tmux 設定ショートカット
references/broadcast-menu.md	複数のペインへのキーストロークのブロードキャスト、メニュー項目の呼び出し
references/tmux-commands.md	すべての tmux CLI コマンド（bootstrap、send、tabs、create-window、set-visible）
references/tmux-guide.md	完全な tmux -CC ワークフロー、ペイン→セッション ID のマッピング
references/json-session.md	session、window、tab、screen、scrollback、inject の --json スキーマ
references/json-tmux-app.md	tmux、アプリダイアログ、設定、エラーの --json スキーマ

REPL モード

引数なしで実行すると、コマンド間でコンテキストを保持する対話型 REPL が起動します:

cli-anything-iterm2