cli-anything-iterm2 是做什么的？
用于 iTerm2 的状态化 CLI 工具。通过 WebSocket 使用 iTerm2 Python API 控制活动的 iTerm2 进程。
前置条件
- macOS + iTerm2 正在运行：
brew install --cask iterm2 - 启用 Python API：iTerm2 → 偏好设置 → 通用 → 魔法 → 启用 Python API
- 安装：
pip install cli-anything-iterm2（或从源码pip install -e .）
基本语法
cli-anything-iterm2 [--json] <组> <命令> [选项] [参数]
始终使用 --json 获取机器可读的输出（Agent 使用时必需）。
命令组
| 组 | 用途 |
|---|---|
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 将把这些角色与进程和路径一同展示，一次调用即可获得全貌。
典型 Agent 工作流
# 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；可靠的发送→等待→读取模式 |
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 | session、window、tab、screen、scrollback、inject 的 --json 模式 |
references/json-tmux-app.md | tmux、app 对话框、偏好设置、错误的 --json 模式 |
REPL 模式
不带参数运行可进入交互式 REPL，在命令之间维持上下文：
cli-anything-iterm2