cli-anything-iterm2

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cli-anything-iterm2

Stateful CLI harness for iTerm2. Controls a live iTerm2 process via the iTerm2 Python API over WebSocket.

面向iTerm2的有状态CLI控制工具。通过WebSocket借助iTerm2 Python API控制运行中的iTerm2进程。

Prerequisites

前提条件

macOS + iTerm2 running:
```
brew install --cask iterm2
```
Python API enabled: iTerm2 → Preferences → General → Magic → Enable Python API

Install:

pip install cli-anything-iterm2

(or

pip install -e .

from source)

运行macOS + iTerm2：执行
```
brew install --cask iterm2
```
安装
启用Python API：打开iTerm2 → 偏好设置 → 通用 → 魔法功能 → 启用Python API

安装工具：执行

pip install cli-anything-iterm2

（或从源码执行

pip install -e .

）

Basic Syntax

基础语法

bash

cli-anything-iterm2 [--json] <group> <command> [OPTIONS] [ARGS]

Always use

--json

for machine-readable output (required for agent use).

bash

cli-anything-iterm2 [--json] <group> <command> [OPTIONS] [ARGS]

如需机器可读输出（Agent使用时必填），请始终添加

--json

参数。

Command Groups

命令组

Group	Purpose
`app`	App status, workspace snapshot, context management, app-level variables, modal dialogs, file panels
`window`	Create, list, close, resize, fullscreen windows
`tab`	Create, list, close, activate tabs; navigate split panes by direction
`session`	Send text, inject raw bytes, read screen, full scrollback, split panes, prompt detection
`profile`	List profiles, get profile details, list/apply color presets
`arrangement`	Save and restore window layouts
`tmux`	Full tmux -CC integration: bootstrap, connections, windows, commands
`broadcast`	Sync keystrokes across panes via broadcast domains
`menu`	Invoke any iTerm2 menu item programmatically
`pref`	Read/write global iTerm2 preferences; list all valid keys; tmux settings

命令组	用途
`app`	应用状态、工作区快照、上下文管理、应用级变量、模态对话框、文件面板
`window`	创建、列出、关闭、调整大小、全屏窗口
`tab`	创建、列出、关闭、激活标签页；按方向导航拆分窗格
`session`	发送文本、注入原始字节、读取屏幕内容、完整回滚历史、拆分窗格、提示检测
`profile`	列出配置文件、获取配置文件详情、列出/应用颜色预设
`arrangement`	保存和恢复窗口布局
`tmux`	完整的tmux -CC集成：初始化、连接、窗口、命令
`broadcast`	通过广播域在多个窗格间同步按键操作
`menu`	以编程方式调用任意iTerm2菜单项
`pref`	读写全局iTerm2偏好设置；列出所有有效键；tmux设置

Orienting in an Existing Workspace

在现有工作区中定位

Use

app snapshot

when you land in a session with existing panes and need to understand what's running without reading full screen contents for each pane:

bash

cli-anything-iterm2 --json app snapshot

Returns name, current directory, foreground process,

user.role

label, and last visible output line for every session across all windows.

Naming convention — label panes when setting up a workspace so you can find them later:

bash

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

will surface these roles alongside process and path, giving you a full picture in one call.

当进入一个包含现有窗格的会话，且无需逐个读取全屏内容即可了解运行状态时，请使用

app snapshot

命令：

bash

cli-anything-iterm2 --json app snapshot

该命令会返回所有窗口中每个会话的名称、当前目录、前台进程、

user.role

标签和最后一行可见输出。

命名约定 — 设置工作区时为窗格添加标签，以便后续查找：

bash

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

会将这些角色信息与进程和路径一起展示，一次调用即可让你掌握全局情况。

Typical Agent Workflow

典型Agent工作流

bash

undefined

bash

undefined

1. Orient — snapshot every session: name, path, process, role, last output line

1. 定位——获取所有会话的快照：名称、路径、进程、角色、最后一行输出

cli-anything-iterm2 --json app snapshot

2. Establish context (saves window/tab/session IDs for subsequent commands)

2. 建立上下文（保存窗口/标签页/会话ID，供后续命令使用）

cli-anything-iterm2 app current

3. Interact — no --session-id needed once context is set

3. 交互——设置上下文后无需再指定--session-id

cli-anything-iterm2 session send "git status" cli-anything-iterm2 --json session scrollback --tail 200 --strip

4. Create a multi-pane workspace — label panes so snapshot identifies them later

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"

undefined

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"

undefined

Reference Files

参考文档

Read only what the task requires — each file is a single narrow concern (~10–30 lines):

File	Read when you need...
`references/session-io.md`	Send text, inject bytes, read screen/scrollback, get selection
`references/session-control.md`	Split panes, activate/close sessions, resize, rename, session variables
`references/session-shell-integration.md`	wait-prompt, wait-command-end, get-prompt; reliable send→wait→read pattern
`references/layout-window-tab.md`	Create/close/resize windows and tabs, navigate split panes
`references/layout-arrangement.md`	Save and restore window layouts
`references/app-context.md`	Snapshot (orientation), status, context management, app vars, modal dialogs, file panels
`references/profile-pref.md`	Profiles list/get/presets, preferences read/write, tmux pref shortcuts
`references/broadcast-menu.md`	Broadcast keystrokes to multiple panes, invoke menu items
`references/tmux-commands.md`	All tmux CLI commands (bootstrap, send, tabs, create-window, set-visible)
`references/tmux-guide.md`	Full tmux -CC workflow, pane→session ID mapping
`references/json-session.md`	`--json` schemas for session, window, tab, screen, scrollback, inject
`references/json-tmux-app.md`	`--json` schemas for tmux, app dialogs, preferences, errors

仅阅读任务所需内容——每个文档仅聚焦单一主题（约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命令（初始化、发送、标签页、创建窗口、设置可见性）
`references/tmux-guide.md`	完整的tmux -CC工作流、窗格→会话ID映射
`references/json-session.md`	会话、窗口、标签页、屏幕、回滚历史、注入操作的 `--json` schema
`references/json-tmux-app.md`	tmux、应用对话框、偏好设置、错误信息的 `--json` schema

REPL Mode

REPL模式

Run without arguments for an interactive REPL that maintains context between commands:

bash

cli-anything-iterm2

不带参数运行即可启动交互式REPL，该模式会在命令之间保留上下文：

bash

cli-anything-iterm2