cli-anything-iterm2 是做什麼的？
用於 iTerm2 的狀態化 CLI 工具。透過 WebSocket 經由 iTerm2 Python API 控制正在執行中的 iTerm2 程序。
必要條件
- macOS + iTerm2 正在執行：
brew install --cask iterm2 - 啟用 Python API：iTerm2 → 偏好設定 → 一般 → Magic → 啟用 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. 導向 —— 快照每個工作階段：名稱、路徑、程序、角色、最後一行輸出
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 指令（啟動、傳送、分頁、建立視窗、set-visible） |
references/tmux-guide.md | 完整的 tmux -CC 工作流程、窗格到工作階段 ID 對應 |
references/json-session.md | 工作階段、視窗、分頁、螢幕、捲動歷史、注入的 --json 結構描述 |
references/json-tmux-app.md | tmux、應用程式對話框、偏好設定、錯誤的 --json 結構描述 |
REPL 模式
不加任何引數執行，即可進入互動式 REPL，維持各指令之間的情境：
cli-anything-iterm2