cli-anything-iterm2
有狀態的 iTerm2 命令列工具。透過 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 指令（引導、傳送、分頁、建立視窗、設定可見） |
references/tmux-guide.md | 完整的 tmux -CC 工作流程、面板→工作階段 ID 對應 |
references/json-session.md | 工作階段、視窗、分頁、螢幕、回滾、注入的 --json 結構定義 |
references/json-tmux-app.md | tmux、應用程式對話框、偏好設定、錯誤的 --json 結構定義 |
REPL 模式
不帶參數執行以啟動互動式 REPL，可在指令間維持上下文：
cli-anything-iterm2