cli-anything-iterm2
用于 iTerm2 的有状态 CLI 工具。通过 WebSocket 借助 iTerm2 Python API 控制正在运行的 iTerm2 进程。
前提条件
- macOS + iTerm2 正在运行：
brew install --cask iterm2 - 启用 Python API：iTerm2 → 偏好设置 → 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. 定位——快照每个会话：名称、路径、进程、角色、最后输出行
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