cli-anything-iterm2 实战指南用 CLI 全面控制 iTerm2构建 Agent 原生终端工作流【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything导读本指南以 skills/cli-anything-iterm2-ctl/SKILL.md 为核心骨架完整讲解cli-anything-iterm2这一有状态StatefuliTerm2 CLI 工具链的安装、九大命令组、app snapshot工作区感知、send→wait→read 可靠执行模式、tmux -CC 集成与广播同步等能力。读完本文你将能通过一行命令让 AI Agent 向 iTerm2 会话发送文本、读取实时输出与滚动历史、管理窗口/标签/分屏、弹出 macOS 对话框、读写偏好设置把 iTerm2 变成完全可编程、可观测、可自动化的Agent 原生终端。背景为什么要用 CLI 控制 iTerm2iTerm2 是 macOS 上功能最丰富的终端模拟器之一它自带一套完整的 Python API可通过 WebSocketws://localhost:1912与运行中的 iTerm2 进程通信。传统上Agent 只能通过 AppleScript、模拟键击等方式盲操作终端既脆弱又不可观测。cli-anything-iterm2正是为此设计的有状态 CLI 封装它以 Click 命令行的形式把 iTerm2 Python API 的全部异步能力桥接为同步的、可脚本化的一次性命令和交互式 REPL。其设计目标非常明确——让 AI Agent 真正地向 iTerm2 会话发送文本、读取实时输出与滚动历史、管理窗口/标签/分屏、运行 tmux -CC 工作流、向多个面板广播按键、弹出 macOS 对话框、读写 iTerm2 偏好设置。从仓库中的架构文档 iterm2/agent-harness/ITERM2.md 可以看到其分层结构┌─────────────────────────────────┐ │ cli-anything-iterm2 (Click) │ ← CLI harness └──────────────┬──────────────────┘ │ iterm2 Python API (async/websocket) ┌──────────────▼──────────────────┐ │ iTerm2.app (running macOS) │ ← 真实软件 └─────────────────────────────────┘核心桥接层位于 utils/iterm2_backend.py由于 iTerm2 API 全部为异步协程而 Click 命令是同步模型该模块通过iterm2.run_until_complete()将二者衔接并负责连接失败时的友好报错提示检查 iTerm2 是否运行、Python API 是否开启。iTerm2 的对象模型为App → Window → Tab → Session其中Session 是真正的终端模拟器实例一个 Tab 内可含多个 Session即分屏面板。cli-anything-iterm2的每个命令组都围绕这一模型设计。安装与前置条件使用前需要满足三个条件对应 SKILL.md 的 Prerequisites 章节macOS iTerm2 正在运行brew install --cask iterm2开启 Python APIiTerm2 → Preferences → General → Magic → Enable Python API未开启时后端会抛出明确错误提示见 iterm2_backend.py安装 CLIpip install cli-anything-iterm2或从源码目录执行pip install -e .。后端依赖iterm2Python 包连接时依赖 iTerm2 自动注入的ITERM2_COOKIE与ITERM2_KEY环境变量完成鉴权。基础语法与命令组总览CLI 的基本语法为cli-anything-iterm2 [--json] group command [OPTIONS] [ARGS]重要约定面向 Agent 使用时务必加--json输出为机器可读的 JSON在 iterm2_ctl_cli.py 中通过output()统一处理--json时json.dumps输出否则输出人类可读文本。不带子命令直接运行时则进入交互式 REPL。九个命令组覆盖了 iTerm2 的全部可编程面组用途app应用状态、工作区快照、上下文管理、应用级变量、模态对话框、文件面板window创建、列出、关闭、调整大小、全屏窗口tab创建、列出、关闭、激活标签按方向在分屏面板间移动焦点session发送文本、注入原始字节、读取屏幕、完整滚动历史、分屏、提示符检测profile列出配置、获取配置详情、列出/应用配色预设arrangement保存与恢复窗口布局tmux完整 tmux -CC 集成引导、连接、窗口、命令broadcast通过广播域在多个面板间同步按键menu以编程方式调用任意 iTerm2 菜单项pref读写全局 iTerm2 偏好tmux 设置这些组的命令定义全部集中在 iterm2_ctl_cli.py每个命令通过handle_iterm2_error装饰器L90-L110统一捕获RuntimeError/ValueError在--json模式下输出{error: ...}并退出码为 1保证 Agent 可以结构化识别失败原因。场景一进入既有工作区——app snapshot一呼百应当 Agent 进入一个已有多个面板的 iTerm2 工作区时首要任务是快速搞清每个面板在干什么而不是逐个读取全屏内容。这正是app snapshot的设计初衷iterm2_ctl_cli.py L355-L376cli-anything-iterm2 --json app snapshot底层实现见 core/session.py 的 workspace_snapshot它对所有窗口、所有标签、所有会话遍历通过 iTerm2 会话变量读取path当前目录、pid、user.role通过ps反查前台进程名再读取屏幕内容取最后一行非空输出。返回的 JSON 形如{session_count: 3, sessions: [ {session_id: ..., name: api-server, window_id: ..., tab_id: ..., path: /Users/alex/project, pid: 12345, process: node, role: api-server, last_line: Server listening on :3000}, {session_id: ..., name: shell, window_id: ..., tab_id: ..., path: /Users/alex, pid: 67890, process: zsh, role: null, last_line: $ } ]}命名约定推荐搭建工作区时就给面板打上角色标签这样app snapshot会在返回中带上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 editoruser.role属于自定义会话变量遵循 iTerm2 的命名空间规则内置变量hostname、username、path、pid、columns、rows只读自定义变量必须使用user.前缀详见 references/session-control.md。场景二典型 Agent 工作流SKILL.md 给出了一套完整、可直接落地的 Agent 工作流模板核心是定向 → 建上下文 → 交互 → 搭多面板工作区四步# 1. 定向——一次拿到所有会话的名称、路径、进程、角色、最后输出行 cli-anything-iterm2 --json app snapshot # 2. 建立上下文保存 window/tab/session ID后续命令免带 --session-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. 创建多面板工作区——给面板打标签便于 snapshot 后续识别 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其中第 2 步的上下文context是本工具有状态的核心app current会把当前焦点窗口/标签/会话的 ID 持久化保存状态落盘实现见 core/session_state.py对应测试覆盖了状态读写与损坏恢复。之后session send、session scrollback、session split等命令省略--session-id时自动回退到上下文--use-as-context则把新建的面板设为后续命令的默认目标。会话 I/O 深度剖析发送、注入、读取、选中session组是最常用的命令组围绕向会话写入与从会话读取两条主线展开详见 references/session-io.md。发送文本cli-anything-iterm2 session send echo hello # 发送文本 回车 cli-anything-iterm2 session send text --session-id id cli-anything-iterm2 session send text --no-newline # 不附加换行底层通过session.async_send_text()实现core/session.py L50-L73返回{session_id: ..., text_length: N, sent: true}。默认附加\n--no-newline可关闭--suppress-broadcast用于在广播模式下跳过向广播域的发送。注入原始字节cli-anything-iterm2 session inject $\x1b[2J # 清屏转义序列 (ESC[2J) cli-anything-iterm2 session inject 1b5b324a --hex # 同样的十六进制写法 cli-anything-iterm2 session inject $\x07 # 响铃inject模拟的是从 shell 收到数据的方向适合发送转义序列、OSC 码等终端控制字节iterm2_ctl_cli.py L876-L904--hex模式会把十六进制字符串解码为字节后注入。读取可见屏幕与完整滚动历史cli-anything-iterm2 --json session screen # 仅可见区域 cli-anything-iterm2 --json session screen --lines 20 cli-anything-iterm2 --json session scrollback # 全部历史会话开始至今 cli-anything-iterm2 --json session scrollback --tail 100 cli-anything-iterm2 --json session scrollback --tail 500 --strip cli-anything-iterm2 --json session scrollback --lines 200关键区分screen只返回当前可见的终端区域scrollback则原子性地读取整个历史缓冲最旧→最新。注意读取屏幕类命令必须使用--json否则输出为空。--tail N只返回最近 N 行优先于--lines--strip会剔除空字节与不可打印控制字符实现见 iterm2_ctl_cli.py L705-L709 的正则清洗。响应中的overflow字段表示缓冲满时丢失的行数——如需要完整历史应在 iTerm2 Profile 中把 scrollback 上限设为 unlimited。读取选中文本cli-anything-iterm2 session selection返回{has_selection: bool, selected_text: ...}可用于读取用户在终端里框选的内容。Shell Integration可靠的 send→wait→read 执行模式对 Agent 而言仅仅发出命令是不够的必须知道命令何时执行完毕、退出码是多少。这依赖 iTerm2 的 Shell Integration安装一行命令curl -L https://iterm2.com/shell_integration/install_shell_integration.sh | bash安装后即可使用三个提示符相关命令详见 references/session-shell-integration.mdcli-anything-iterm2 session get-prompt # 最近一次提示符command、cwd、state cli-anything-iterm2 session wait-prompt --timeout 30 # 阻塞直到下一个提示符出现 cli-anything-iterm2 session wait-command-end --timeout 120 # 阻塞直到命令结束返回退出码其中wait-command-end返回{session_id: ..., exit_status: 0, timed_out: false}默认超时 30 秒、可通过-t调整iterm2_ctl_cli.py L947-L964。可靠执行模式Agent 铁律——发命令 → 等结束 → 读输出cli-anything-iterm2 session send make build cli-anything-iterm2 session wait-command-end --timeout 120 cli-anything-iterm2 --json session scrollback --tail 50 --stripwait-command-end返回的exit_status可直接作为 Agent 判断命令成败的结构化依据比盲目 sleep 或靠关键词匹配输出可靠得多。会话控制分屏、关闭、重命名、调整尺寸、变量cli-anything-iterm2 session list [--window-id ID] [--tab-id ID] cli-anything-iterm2 session activate [SESSION_ID] cli-anything-iterm2 session close [SESSION_ID] # 分屏 cli-anything-iterm2 session split # 水平分屏 cli-anything-iterm2 session split --vertical # 垂直左右并排 cli-anything-iterm2 session split --use-as-context # 新面板成为上下文 # 元数据 cli-anything-iterm2 session set-name API Worker cli-anything-iterm2 session restart cli-anything-iterm2 session resize --columns 220 --rows 50 # 会话变量 cli-anything-iterm2 session get-var hostname cli-anything-iterm2 session get-var path cli-anything-iterm2 session set-var user.role api-worker cli-anything-iterm2 session get-var user.rolesplit的底层实现core/session.py L76-L119值得注意当指定--command时会构造iterm2.LocalWriteOnlyProfile()并调用set_use_custom_command(Yes)让新面板直接运行指定命令而非默认 shell--before控制新面板插入分界线之前。布局管理窗口、标签、分屏导航与 Arrangement窗口Windowcli-anything-iterm2 window list cli-anything-iterm2 window create [--profile NAME] [--command CMD] cli-anything-iterm2 window close [WINDOW_ID] # 位置参数省略时用上下文窗口 cli-anything-iterm2 window activate [WINDOW_ID] cli-anything-iterm2 window set-title My Window cli-anything-iterm2 window frame # 获取位置/尺寸 cli-anything-iterm2 window set-frame --x 0 --y 0 --width 1200 --height 800 cli-anything-iterm2 window fullscreen on|off|toggle|status注意window close/activate用的是位置参数而非--window-id选项详见 references/layout-window-tab.md。标签Tab与分屏导航cli-anything-iterm2 tab list [--window-id ID] cli-anything-iterm2 tab create [--window-id ID] [--profile NAME] cli-anything-iterm2 tab close [TAB_ID] cli-anything-iterm2 tab activate [TAB_ID] cli-anything-iterm2 tab info [TAB_ID] cli-anything-iterm2 tab select-pane right # 聚焦相邻分屏 cli-anything-iterm2 tab select-pane left|above|below [--tab-id ID]tab select-pane返回{tab_id: ..., direction: right, new_session_id: ..., moved: true}moved: false表示该方向没有相邻面板。Arrangement布局存档cli-anything-iterm2 arrangement list cli-anything-iterm2 arrangement save my-layout cli-anything-iterm2 arrangement restore my-layout cli-anything-iterm2 arrangement save-window window-layout [--window-id ID]arrangement restore默认打开新窗口也可用--window-id恢复到既有窗口。仓库测试计划 TEST.md 中专门设计了 Layout save/restore 场景创建 2 个窗口各含 2 个标签 →arrangement save dev-env→arrangement list验证。tmux -CC 集成让 tmux 窗口变成原生 iTerm2 标签cli-anything-iterm2对 tmux 的支持是其最强大的差异化能力之一。tmux -CC会把每个 tmux 窗口渲染成原生 iTerm2 标签——完全可见、可读、可控完整工作流见 references/tmux-guide.md。# 1. 引导前必须先设置上下文否则 bootstrap 会超时 cli-anything-iterm2 app set-context --session-id id # 2. 引导启动 tmux -CC 并轮询等待集成连接出现 cli-anything-iterm2 --json tmux bootstrap cli-anything-iterm2 --json tmux bootstrap --attach # 附加到既有会话 cli-anything-iterm2 --json tmux bootstrap --session-id id --timeout 15 # 3. 枚举 cli-anything-iterm2 --json tmux send list-sessions cli-anything-iterm2 --json tmux send list-panes -a -F #{session_name}:#{window_index}:#{pane_index} #{pane_current_command} #{pane_current_path} cli-anything-iterm2 --json tmux tabs # tmux 窗口 → iTerm2 标签 ID 映射 cli-anything-iterm2 --json tmux list # 列出活动连接 # 4. 读取任意面板 cli-anything-iterm2 --json session screen --session-id pane-session-id cli-anything-iterm2 --json session scrollback --session-id pane-session-id --tail 500 --strip # 5. 向任意面板发送命令 cli-anything-iterm2 session send git log --oneline -10 --session-id pane-session-id # 6. 布局管理 cli-anything-iterm2 tmux send new-window -n logs cli-anything-iterm2 tmux send split-window -h -t logs cli-anything-iterm2 tmux send select-layout -t logs even-horizontal cli-anything-iterm2 tmux create-window --use-as-context关键区分务必牢记tmux send发送的是 tmux 协议命令发给 tmux 服务器例如new-window、rename-sessionsession send发送的是普通 shell 文本到某个具体面板。二者要配合使用。tmux 面板 → iTerm2 session ID 映射tmux 面板并不直接暴露 iTerm2 session ID需要交叉引用cli-anything-iterm2 --json tmux tabs # 得到每个 tmux 窗口对应的 tab_id cli-anything-iterm2 --json app status # 得到每个 tab_id 下的 session_idbootstrap实现细节iterm2_ctl_cli.py L1181-L1204向目标会话发送tmux -CC或tmux -CC attach然后轮询等待集成连接出现返回{connection_id: ..., elapsed_seconds: ...}。广播Broadcast一键同步多个面板广播域Broadcast Domain可以把按键同步到多个面板适合在所有环境上执行同一命令的场景详见 references/broadcast-menu.mdcli-anything-iterm2 broadcast list cli-anything-iterm2 broadcast add s1 s2 # 分组为一个广播域 cli-anything-iterm2 broadcast set s1,s2 s3,s4 # 一次性设置多个域逗号分隔 cli-anything-iterm2 broadcast all-panes [--window-id ID] cli-anything-iterm2 broadcast clear # 停止全部广播典型模式——向所有面板同时导出环境变量cli-anything-iterm2 broadcast all-panes cli-anything-iterm2 session send export ENVstaging cli-anything-iterm2 broadcast clear模态对话框、文件面板与菜单调用Agent 有时需要与人类交互或利用 macOS 原生界面app组提供了三类对话框底层实现见 core/dialogs.py# 模态警示框返回用户点击的按钮标签 cli-anything-iterm2 app alert Title Message cli-anything-iterm2 app alert Deploy? Push? --button Yes --button No # 返回: {button_index: 1000, button_label: OK}多按钮时 1000Yes、1001No # 文本输入框 cli-anything-iterm2 app text-input Rename Enter name: --default myapp # 返回: {cancelled: false, text: hello world} 或 {cancelled: true, text: null} # macOS 打开/保存文件面板 cli-anything-iterm2 app file-panel cli-anything-iterm2 app file-panel --ext py --ext txt --multi cli-anything-iterm2 app save-panel --filename output.txtmenu组则可以直接触发 iTerm2 菜单项cli-anything-iterm2 menu list-common cli-anything-iterm2 menu select Shell/Split Vertically with Current Profile cli-anything-iterm2 menu select Shell/New Window cli-anything-iterm2 menu state View/Enter Full Screen # 查询 checked enabled 状态Profile 与偏好设置读写profile组管理配色与配置详见 references/profile-pref.mdcli-anything-iterm2 profile list [--filter NAME] cli-anything-iterm2 profile get guid # 详细设置name/guid/badge_text cli-anything-iterm2 profile color-presets cli-anything-iterm2 profile apply-preset Solarized Dark [--session-id ID]pref组读写全局偏好键名直接对应iterm2.preferences.PreferenceKey枚举cli-anything-iterm2 pref list-keys # 列出全部合法键名 cli-anything-iterm2 pref list-keys --filter tmux # 按子串过滤 cli-anything-iterm2 pref get OPEN_TMUX_WINDOWS_IN cli-anything-iterm2 pref set OPEN_TMUX_WINDOWS_IN 2 cli-anything-iterm2 pref theme # 当前主题标签 is_dark 布尔值tmux 相关偏好有便捷简写cli-anything-iterm2 pref tmux-get # 一次读出全部 tmux 偏好 cli-anything-iterm2 pref tmux-set open_in 2 # 0native_windows 1new_window 2tabs_in_existing cli-anything-iterm2 pref tmux-set auto_hide_client true cli-anything-iterm2 pref tmux-set use_profile true cli-anything-iterm2 pref tmux-set dashboard_limit 10JSON Schema 与错误处理Agent 的协议契约为了供 Agent 稳定解析各命令的--json输出有明确结构完整定义见 references/json-session.md 与 references/json-tmux-app.md// session screen {session_id: ..., total_lines: 40, returned_lines: 40, lines: [$ echo hello, hello]} // session scrollback {session_id: ..., total_available: 4922, scrollback_lines: 4862, screen_lines: 60, overflow: 0, returned_lines: 100, lines: [..., ...]} // session wait-command-end {session_id: ..., exit_status: 0, timed_out: false} // tmux list {connections: [{connection_id: userhost, owning_session_id: ..., owning_session_name: tmux}]} // pref tmux-get {open_tmux_windows_in: 2, open_tmux_windows_in_label: tabs_in_existing, tmux_dashboard_limit: 10, auto_hide_tmux_client_session: true, use_tmux_profile: false}错误处理约定连接失败或会话不存在时人类可读模式输出Error: Cannot connect to iTerm2. Make sure iTerm2 is running...或Error: Session abc123 not found.--json模式下统一为{error: Session abc123 not found.}。Agent 应同时检查退出码与error键来判断命令是否真正成功。REPL 模式人机两用的交互终端不带子命令直接运行cli-anything-iterm2即进入交互式 REPL实现见 iterm2_ctl_cli.py L1410-L1531。REPL 会在命令之间维持上下文状态启动时若已有保存的上下文会显示提示内置 60 余条命令的help帮助支持quit/exit/q退出并在提示符前缀显示当前上下文的 session ID 片段。每条输入行会通过cli.main()原样走一遍 Click 解析因此与一次性命令行为完全一致适合人类手动调试、也适合作为 Agent 的长时间交互会话。测试与质量保障仓库为 CLI 提供了分层测试计划tests/TEST.mdtest_core.py含 28 个单元测试覆盖session_state的读写/损坏恢复、后端错误处理、send_text的新行拼接、各命令组--help与--json标志传播test_full_e2e.py含 18 个端到端测试要求 iTerm2 运行且 Python API 开启覆盖app status/current、窗口创建关闭、标签创建、session send_and_screen、分屏、Profile、Arrangement 等真实流程并用_resolve_cli(cli-anything-iterm2)以真实用户身份运行已安装命令做子进程级验证。测试中还设计了三个真实场景Agent 搭建多面板工作区、只读审计终端状态、布局保存恢复——与本文的工作流示例一一对应可作为功能验证的现成清单。适用前提与限制平台限制仅适用于 macOS 运行中的 iTerm2且必须开启 Python API连接依赖所有命令都通过 WebSocket 连接ws://localhost:1912iTerm2 未运行或 API 未启用时所有操作失败后端会给出修复步骤提示Shell Integration 是可选增强get-prompt/wait-prompt/wait-command-end需要先安装 Shell Integration 脚本未安装时get-prompt返回available: falsetmux 集成需先在 iTerm2 内启动tmux -CC且tmux bootstrap前必须先设置好上下文会话读取屏幕类命令必须配合--json否则输出为空这是 SKILL 文档特别强调的易错点。至此从工作区定向、上下文管理、会话 I/O、可靠执行模式、布局编排、tmux -CC 到广播与偏好设置cli-anything-iterm2为 Agent 提供了完整的 iTerm2 控制面。将本文的命令序列组合起来即可搭建出感知 → 决策 → 执行 → 验证闭环的自动化终端工作流。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考