cli-anything-iterm2 は何をしますか？
iTerm2 を制御するための状態管理型 CLI ツール。WebSocket 経由で iTerm2 Python API を使用して、動作中の iTerm2 プロセスを操作します。
前提条件
- macOS + iTerm2 が動作していること:
brew install --cask iterm2 - Python API が有効であること: iTerm2 → Preferences → General → Magic → Enable Python API
- インストール:
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. オリエンテーション — 全セッションのスナップショット: 名前、パス、プロセス、ロール、最終出力行
cli-anything-iterm2 --json app snapshot
# 2. コンテキスト確立（後続コマンドのためにウィンドウ/タブ/セッションIDを保存）
cli-anything-iterm2 app current
# 3. 操作 — コンテキスト設定後は --session-id 不要
cli-anything-iterm2 session send "git status"
cli-anything-iterm2 --json session scrollback --tail 200 --strip
# 4. マルチペインワークスペースの作成 — ペインにラベルを付けてスナップショットで識別
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"
リファレンスファイル
タスクに必要なものだけを読んでください — 各ファイルは狭い関心事に特化しています（約10〜30行）:
| ファイル | 必要なとき |
|---|---|
references/session-io.md | テキスト送信、バイト注入、画面/スクロールバック読み取り、選択範囲取得 |
references/session-control.md | ペイン分割、セッションのアクティブ化/閉じる、リサイズ、名前変更、セッション変数 |
references/session-shell-integration.md | wait-prompt、wait-command-end、get-prompt; 信頼性の高い send→wait→read パターン |
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 コマンド（ブートストラップ、送信、タブ、ウィンドウ作成、可視設定） |
references/tmux-guide.md | tmux -CC ワークフロー全体、ペイン→セッションID マッピング |
references/json-session.md | session、window、tab、screen、scrollback、inject の --json スキーマ |
references/json-tmux-app.md | tmux、app ダイアログ、設定、エラーの --json スキーマ |
REPL モード
引数なしで実行するとインタラクティブ REPL が起動し、コマンド間でコンテキストを維持します:
cli-anything-iterm2